diff --git a/docs/packages/ui-inputs.md b/docs/packages/ui-inputs.md index 8ad3a311..fd103ce1 100644 --- a/docs/packages/ui-inputs.md +++ b/docs/packages/ui-inputs.md @@ -110,6 +110,52 @@ Models an **array of option ids**. Committing an option toggles its membership a ``` +### GroupSelect & GroupCombobox + +When options arrive **already partitioned** — active sprints above the backlog, tropical fruit above stone fruit — `GroupSelect` and `GroupCombobox` are `SingleSelect` / `Combobox` over **`groups`** instead of `options`. Each group renders a `role="group"` header; a single `v-model` selects across the whole set, and groups stay in **caller order** (there is no `alphabeticalSort` — the partition _is_ the order). `GroupCombobox` filters within groups and drops any group its filter empties. Try typing `a` in the searchable one: + + +
+ + + +

Model value: {{ groupFruit === null ? 'null' : JSON.stringify(groupFruit) }}

+ + + +

Model value: {{ groupFruitSearch === null ? 'null' : JSON.stringify(groupFruitSearch) }}

+
+ + +```vue + + + +``` + +The `groups` prop replaces `options` — each group carries its own `options`, a header `text`, and an optional `header` flag: + +```ts +const fruitGroups = [ + { + text: 'Tropical', + options: [ + {id: 'mango', name: 'Mango'}, + {id: 'kiwi', name: 'Kiwi'}, + ], + }, + { + text: 'Stone', + options: [ + {id: 'apricot', name: 'Apricot'}, + {id: 'peach', name: 'Peach'}, + ], + }, +]; +``` + +Pass `header: false` on a group to render its options **flat** (a leading "ungrouped" run above the named groups); an empty group renders nothing, so a header never outlives its options. + ### The checkbox family `Checkbox`, `Switch`, `CheckboxGroup`, and `RadioGroup` sit on a **native input chassis** — a real `` / `` restyled through the same `--ui-*` contract, never a div-with-role — so keyboard and assistive-tech behaviour come from the platform. The radio group's arrow-key selection below is the **browser's own** roving focus; the component hand-rolls none of it. @@ -215,6 +261,8 @@ By default `FormField` stacks the label above the control. Pass `orientation="ho | `Combobox` | Accessible searchable/filtering single-select; exposes an imperative `focus()` handle | | `MultiSelect` | Accessible multi-value select — models an array of option ids; toggle-in-place listbox, inline chip bar with per-chip remove | | `MultiCombobox` | Accessible **searchable** multi-value select — MultiSelect's model + chips with Combobox's filtering input as the trigger | +| `GroupSelect` | Accessible **grouped** single-select — `SingleSelect` over caller-ordered `groups` with `role="group"` headers; models `T['id'] \| null` | +| `GroupCombobox` | Accessible **searchable grouped** single-select — `GroupSelect`'s listbox with `Combobox`'s filtering input; exposes `focus()` | | `Pressable` | A real `