feat(ui-inputs): add GroupSelect and GroupCombobox atoms (v0.13.0)

docs/packages/ui-inputs.md

@@ -110,6 +110,52 @@ Models an **array of option ids**. Committing an option toggles its membership a
 </FormField>
 ```
 
+### 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:
+
+<ClientOnly>
+<div class="ui-demo">
+<FormField id="demo-group-fruit" label="Fruit" #default="{controlId, describedby, invalid}">
+<GroupSelect :id="controlId" v-model="groupFruit" :groups="fruitGroups" label="name" :invalid="invalid" :describedby="describedby" />
+</FormField>
+<p class="ui-demo__state">Model value: <code>{{ groupFruit === null ? 'null' : JSON.stringify(groupFruit) }}</code></p>
+<FormField id="demo-group-fruit-search" label="Fruit (searchable)" #default="{controlId, describedby, invalid}">
+<GroupCombobox :id="controlId" v-model="groupFruitSearch" :groups="fruitGroups" label="name" :invalid="invalid" :describedby="describedby" />
+</FormField>
+<p class="ui-demo__state">Model value: <code>{{ groupFruitSearch === null ? 'null' : JSON.stringify(groupFruitSearch) }}</code></p>
+</div>
+</ClientOnly>
+
+```vue
+<FormField id="fruit" label="Fruit" #default="{controlId, describedby, invalid}">
+    <GroupSelect :id="controlId" v-model="fruit" :groups="fruitGroups" label="name" :invalid="invalid" :describedby="describedby" />
+</FormField>
+```
+
+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 `<input type="checkbox">` / `<input type="radio">` 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 `<button>` for a control that carries **no value** — replaces `<span @click>` / `<div @click>`; optional `aria-pressed` toggle mode |
 | `Disclosure`              | Show/hide a region from a real button (`aria-expanded` + `aria-controls`), optionally wrapped in a real heading — replaces `<h2 @click>`   |
 
@@ -320,6 +368,22 @@ danger-toned by default (`--ui-clear-text`, chaining to `--ui-danger-text`).
 />
 ```
 
+#### Grouped variants (`GroupSelect` / `GroupCombobox`)
+
+`GroupSelect` and `GroupCombobox` are the grouped single-selects. They share the family's
+contract — `label`, `id`, `placeholder`, `disabled`, `required`, `invalid`, `describedby`,
+`emptyText`, `optionsLabel`, `mutedOptions`, `clearLabel`, `emptyDisplayValue`, the `#option`
+slot, and (on `GroupCombobox`) the imperative `focus()` handle — with **`options` replaced by
+`groups`** and no `alphabeticalSort` (the partition is the order):
+
+```ts
+groups: {options: T[]; text: string; header?: boolean}[];
+```
+
+- Groups render in caller order; a single `T['id'] | null` model selects across the flattened option set.
+- A named group renders `text` as a `role="group"` header labelling its options; `header: false` renders the group's options flat (with a boundary so they never fold into the preceding group) — a leading ungrouped run.
+- An empty group renders nothing — a header never outlives its options, including when `GroupCombobox`'s filter drains a group.
+
 ### The checkbox family
 
 `Checkbox` and `Switch` share `id` (required), `label` (inline label text; the default slot overrides it for rich content), `disabled`, `required`, `invalid`, and `describedby`. Both model a **non-nullable `boolean`**. `Checkbox` adds `indeterminate` (visual prop → the element's DOM property). Native `required` is never set — `aria-required` is the conveyance, as everywhere in the family.
@@ -380,6 +444,7 @@ The variable surface groups into:
 - **Control** (inputs + select triggers) — `--ui-control-bg`, `--ui-control-text`, `--ui-control-text-muted`, `--ui-control-border-width`, `--ui-control-border-color`, `--ui-control-border-open`, `--ui-control-radius`, `--ui-control-pad-x`, `--ui-control-pad-y`, `--ui-control-shadow`, `--ui-control-shadow-hover`, `--ui-control-bg-disabled`, `--ui-focus-ring`, `--ui-control-font-size`, `--ui-control-line-height`, `--ui-control-min-height`
 - **Listbox menu** — `--ui-menu-bg`, `--ui-menu-border-width`, `--ui-menu-border-color`, `--ui-menu-radius`, `--ui-menu-pad`, `--ui-menu-shadow`, `--ui-menu-max-height`, `--ui-menu-min-width`, `--ui-menu-max-width`, `--ui-menu-font-size`
 - **Option** — `--ui-option-radius`, `--ui-option-pad`, `--ui-option-bg-active`, `--ui-option-min-height`, `--ui-option-text-muted` (`.is-muted`), `--ui-option-bg-selected` / `--ui-option-text-selected` (MultiSelect `[aria-selected="true"]`), `--ui-clear-text` (the clear entry)
+- **Group header** (GroupSelect / GroupCombobox) — `--ui-group-header-pad`, `--ui-group-header-color`, `--ui-group-header-size`, `--ui-group-header-weight`, `--ui-group-header-transform`, `--ui-group-header-tracking` — the non-navigable label above each option run; `pad`/`color` default to `--ui-option-pad` / `--ui-control-text-muted` so your token map themes them for free
 - **Chip** (MultiSelect) — `--ui-chip-bg`, `--ui-chip-text`, `--ui-chip-radius`, `--ui-chip-pad`, each defaulting to an existing resting token so chips are neutral until you opt in
 - **Check** (Checkbox / CheckboxGroup / RadioGroup) — `--ui-check-size`, `--ui-check-border-width` (shorthand-valued, like the control's), `--ui-check-border-color`, `--ui-check-bg`, `--ui-check-bg-checked`, `--ui-check-mark-color`, `--ui-check-radius`, `--ui-check-gap` (control ↔ label), `--ui-check-item-gap` (group rows) — every colour default derives from an existing resting token (`--ui-control-bg`, `--ui-control-border-color`, `--ui-control-border-open`), so your token map themes the family with no new mappings
 - **Switch** — `--ui-switch-track-width`, `--ui-switch-track-height`, `--ui-switch-track-radius`, `--ui-switch-track-bg`, `--ui-switch-track-bg-checked`, `--ui-switch-thumb-size`, `--ui-switch-thumb-bg` — the thumb travels track-width − track-height, so geometry stays coherent under any override
@@ -625,7 +690,7 @@ No file or range atoms; no date _picker_ (`DateInput` wraps the native control);
 <script setup lang="ts">
 import {computed, ref} from 'vue';
 
-import {Checkbox, CheckboxGroup, Combobox, Disclosure, FormField, MultiCombobox, MultiSelect, Pressable, RadioGroup, SingleSelect, Switch, TextInput} from '../../packages/ui-inputs/src/index';
+import {Checkbox, CheckboxGroup, Combobox, Disclosure, FormField, GroupCombobox, GroupSelect, MultiCombobox, MultiSelect, Pressable, RadioGroup, SingleSelect, Switch, TextInput} from '../../packages/ui-inputs/src/index';
 
 import '../../packages/ui-inputs/styles.css';
 
@@ -669,6 +734,13 @@ const city = ref<string | null>(null);
 const toppingIds = ref<string[]>([]);
 const tagIds = ref<string[]>([]);
 
+const fruitGroups = [
+    {text: 'Tropical', options: [{id: 'mango', name: 'Mango'}, {id: 'kiwi', name: 'Kiwi'}, {id: 'papaya', name: 'Papaya'}]},
+    {text: 'Stone', options: [{id: 'apricot', name: 'Apricot'}, {id: 'peach', name: 'Peach'}, {id: 'plum', name: 'Plum'}]},
+];
+const groupFruit = ref<string | null>(null);
+const groupFruitSearch = ref<string | null>(null);
+
 const accepted = ref(false);
 const notifications = ref(true);
 const extraIds = ref<string[]>(['sprinkles']);
@@ -714,15 +786,25 @@ const themeToppingIds = ref<string[]>(['caramel', 'sprinkles']);
    package's single-class menu selectors (0,1,0), re-adding list markers, indent, and
    inter-item margins inside the demos — something no real consumer sees. Restore the
    package's own menu layout at winning specificity. Chips are spans; the only <ul>s
-   in the demos are the listbox menus. */
+   in the demos are the listbox menus (and the grouped listbox's nested role="group"
+   sub-lists). */
 .vp-doc .ui-demo ul[role='listbox'],
-.vp-doc .demo-theme-panel ul[role='listbox'] {
+.vp-doc .ui-demo ul[role='group'],
+.vp-doc .demo-theme-panel ul[role='listbox'],
+.vp-doc .demo-theme-panel ul[role='group'] {
     list-style: none;
     margin: 0.25rem 0 0;
     padding: var(--ui-menu-pad);
 }
+.vp-doc .ui-demo ul[role='group'],
+.vp-doc .demo-theme-panel ul[role='group'] {
+    margin: 0;
+    padding: 0;
+}
 .vp-doc .ui-demo ul[role='listbox'] li + li,
-.vp-doc .demo-theme-panel ul[role='listbox'] li + li {
+.vp-doc .ui-demo ul[role='group'] li + li,
+.vp-doc .demo-theme-panel ul[role='listbox'] li + li,
+.vp-doc .demo-theme-panel ul[role='group'] li + li {
     margin-top: 0;
 }
 

packages/ui-inputs/README.md

@@ -35,6 +35,8 @@ import '@script-development/ui-inputs/style.css';
 | `Combobox`                | Accessible **searchable/filtering** single-select — a text input that filters the listbox as you type; exposes an imperative `focus()` handle                                       |
 | `MultiSelect`             | Accessible **multi-value** select — models an array of option ids; toggle-in-place listbox that stays open on commit, inline chip bar with per-chip remove                          |
 | `MultiCombobox`           | Accessible **searchable multi-value** select — MultiSelect's array model + chips with Combobox's filter-as-you-type 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 grouped listbox with `Combobox`'s filter-as-you-type input; exposes `focus()`                                     |
 | `Pressable`               | A real `<button>` for an interactive control that carries **no value** — the keyboard-correct replacement for `<span @click>` / `<div @click>`; optional `aria-pressed` toggle mode |
 | `Disclosure`              | Show/hide a region from a real `<button>` carrying `aria-expanded` + `aria-controls`; optionally wrapped in a real heading — the replacement for `<h2 @click>`                      |
 
@@ -213,6 +215,48 @@ Like `Combobox` it exposes an imperative `focus()` handle. `clearLabel` / `empty
 deliberately do not transfer — an empty array is the multi "nothing", so there is no `null`
 to commit and no committed label to name.
 
+### Grouped selects (`GroupSelect` / `GroupCombobox`)
+
+`GroupSelect` and `GroupCombobox` are the single-selects for options that arrive **already
+partitioned** — active sprints above the backlog, tropical fruit above stone fruit. They
+mirror `SingleSelect` / `Combobox` closely (model `T['id'] | null`, the `#option` slot,
+`mutedOptions`, `clearLabel`, `emptyDisplayValue`, the announced empty state, the top-layer
+popup, and — on `GroupCombobox` — the imperative `focus()` handle) with one contract swap:
+**`options` becomes `groups`**.
+
+```ts
+groups: {options: T[]; text: string; header?: boolean}[];
+```
+
+Each group carries its own `options`, a header `text`, and an optional `header` flag. Groups
+render in **caller order** — there is no `alphabeticalSort`, because the partition _is_ the
+order — and the flat option index runs through them in sequence, so a single `v-model` selects
+across the whole set.
+
+- A **named** group renders `text` as a `role="group"` header labelling its options for
+  assistive tech.
+- `header: false` renders a **headerless** group: its options render flat, and a boundary keeps
+  them from folding into the preceding group's `role="group"`. Use it for a leading "ungrouped"
+  run above the named groups.
+- An **empty** group (no options) renders nothing — no dangling header. On `GroupCombobox` this
+  also covers a group the filter drains to nothing: a header never outlives its options.
+
+```vue
+<FormField id="fruit" label="Fruit" :error="errors.fruit" #default="{controlId, describedby, invalid}">
+    <GroupSelect
+        :id="controlId"
+        v-model="fruit"
+        :groups="[
+            {text: 'Tropical', options: tropical},
+            {text: 'Stone', options: stone},
+        ]"
+        label="name"
+        :invalid="invalid"
+        :describedby="describedby"
+    />
+</FormField>
+```
+
 ### Checkbox family
 
 `Checkbox`, `CheckboxGroup`, `Switch`, and `RadioGroup` all sit on a **native input chassis** —

packages/ui-inputs/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@script-development/ui-inputs",
-    "version": "0.13.0",
+    "version": "0.14.0",
     "description": "Headless, themeable Vue 3 UI components — form inputs (field, label, error, text/number/date input, textarea, select, checkbox/radio/switch) plus keyboard-correct interactive controls (pressable, disclosure) — styled entirely through --ui-* CSS custom properties.",
     "homepage": "https://packages.script.nl/packages/ui-inputs",
     "license": "MIT",

packages/ui-inputs/src/components/Combobox.vue

@@ -38,7 +38,7 @@
         <div v-if="open" ref="floating" popover="manual" class="ui-menu-anchor" :style="floatingStyles">
             <OptionList
                 variant="ui-combobox"
-                :labels="optionLabels"
+                :rows="rows"
                 :keys="optionKeys"
                 :pointer="pointer"
                 :listbox-id="listboxId"
@@ -77,6 +77,7 @@
 <script setup lang="ts" generic="T extends SelectItem">
 import {computed, ref, useTemplateRef, watch} from 'vue';
 
+import type {GroupRow} from '../internal/group-rows';
 import type {LabelKey, SelectItem} from '../types';
 
 import {useListbox} from '../composables/useListbox';
@@ -175,6 +176,9 @@ const filtered = computed(() => {
 // stays the single list every index (pointer, commit, aria) is keyed against.
 const optionLabels = computed(() => filtered.value.map(labelOf));
 const optionKeys = computed(() => filtered.value.map((option) => String(option.id)));
+// A flat control renders one headerless run — an all-option row sequence OptionList lays out
+// flat (no group wrappers), the same component the grouped controls feed a header/option mix.
+const rows = computed<GroupRow[]>(() => filtered.value.map((_, index) => ({type: 'option', index})));
 /** `aria-selected` marks the COMMITTED value — OptionList only asks about rendered indices. */
 const isSelected = (index: number): boolean => filtered.value[index].id === model.value;
 /** `.is-muted` marks visual de-emphasis only — a muted option stays committable. */