spec: 0030 combobox (single + multi-select with badges)

[mattmaynes]

Draft - spec for review, not a build. Per the Spectra protocol I stop here for your approval before planning/implementing.

Summary

Proposes docs/specs/0030-combobox.md: a Combobox component for @rogueoak/canopy supporting both single-select and, the priority, multi-select with removable Badge chips in the field.

Key decision (yours)

Built on the Radix Popover + cmdk stack - consistent with every existing canopy component and the 0005 recipe - rather than the Base UI combobox from the linked docs. Trade-off captured in the spec: multi-select chips are composed on Badge rather than native, in exchange for one primitive family across the system.

Two new canopy runtime deps: @radix-ui/react-popover and cmdk (the missing primitives). Architecture/security personas should weigh the new-dependency surface at review time.

Scope highlights

• In: single + multi mode in one API, client-side filtering, badge chips with labelled remove + Backspace-removes-last, disabled/aria-invalid parity with Select/Input, full keyboard + ARIA, Storybook stories, tests.
• Out (follow-ups): async/remote options, creatable free-text, standalone Command palette, grouping/virtualization.

Next step

Approve or leave comments on the spec. On approval I'll turn it into a plan (docs/plans/), build it in a worktree with tests, and run it through the engineer/tester/architect/designer personas before merge.

🤖 Generated with Claude Code

[mattmaynes]

Spec approved and implemented. This PR now carries spec 0030, the build plan, and the full implementation:

• packages/canopy/src/seeds/Combobox.tsx - the component family (single + multiple modes)
• Combobox.test.tsx - 18 tests; Combobox.stories.tsx - 6 stories under Seeds/Combobox
• new deps @radix-ui/react-popover ^1.1.19 + cmdk ^1.1.1 (externalized in tsup)
• barrel exports + README

Full suite green locally: pnpm test (243 passed), build, lint, format:check, storybook build.

Spectra personas (engineer, tester, architect, designer) to review inline next.

[mattmaynes]

Review addressed - all 12 findings resolved

Thanks to the four personas. Summary of how each was handled (commit 775359a):

🏛 Architect

• major - tier placement: moved Combobox from seeds/ to branches/ (it owns interaction state + a portal and composes the Badge seed - Branch-shaped, like Dialog). Exported on ./branches; Badge import now crosses tiers downward. Captured in docs/feedback/0013 + a learning.
• minor - over-exposed API: barrel now exports only Combobox + ComboboxOption + the prop-type unions; parts are internal.
• minor - cmdk precedent: recorded in architecture.md as the sanctioned first non-Radix primitive.

🧪 Tester

• major - keyboard nav: added arrow/enter/escape test. major - controlled mode: added single + multiple controlled tests (+ the isControlled latch case). minor - Backspace boundary: added the non-empty-search case. Captured in docs/feedback/0014 + a learning. 22 Combobox tests (was 18); 247 total.

🛠 Engineer

• cmdk item now keyed by value (+ keywords={[label]}) so duplicate labels don't collapse; emit deps narrowed; isControlled latched via ref.

🎨 Designer

• multi-mode field ring scoped to the trigger (has-[>button:focus-visible]); chip remove target enlarged to 20px with an offset ring; added multi-mode disabled + invalid stories and a disabled option.

Full suite green: test (247) / build / lint / format:check / storybook build. Reflection (features + architecture + learnings + two feedback docs) is in this PR.