refactor: replace GroupOptionList with OptionList in GroupSelect and related components

- Updated GroupSelect.vue to use OptionList for rendering options, improving consistency across components.
- Modified MultiSelect, MultiCombobox, and SingleSelect to utilize rows instead of labels for options.
- Enhanced OptionList to handle both flat and grouped options, collapsing group headers appropriately.
- Adjusted tests for GroupSelect and GroupCombobox to reflect changes in option rendering and interaction.
- Removed GroupOptionList component and updated related test utilities for clarity and maintainability.

Author: Elenyan-Script

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.
@@ -199,6 +245,8 @@ Models an **array of option ids**. Committing an option toggles its membership a
 | `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>`   |
 
@@ -304,6 +352,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`, 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.
@@ -609,7 +673,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';
 
@@ -653,6 +717,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']);
@@ -698,15 +769,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>`                      |
 
@@ -190,6 +192,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`, 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/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. */

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

@@ -36,9 +36,10 @@
              positions the ANCHOR, not the <ul>: the size() middleware sizes it to the
              trigger, so the menu's `min-width: 100%` measures the trigger. -->
         <div v-if="open" ref="floating" popover="manual" class="ui-menu-anchor" :style="floatingStyles">
-            <GroupOptionList
+            <OptionList
                 variant="ui-groupcombobox"
                 :rows="filteredRows"
+                :keys="optionKeys"
                 :pointer="pointer"
                 :listbox-id="listboxId"
                 :option-id="optionId"
@@ -55,8 +56,8 @@
                 @clear-hover="highlightClear"
                 @clear-commit="commitClear"
             >
-                <!-- Re-scope GroupOptionList's index into the typed per-option payload; the
-                     fallback (the plain labelOf text) keeps slotless consumers byte-identical. -->
+                <!-- Re-scope OptionList's index into the typed per-option payload; the fallback
+                     (the plain labelOf text) keeps slotless consumers byte-identical. -->
                 <template #option="{index}">
                     <slot
                         name="option"
@@ -68,7 +69,7 @@
                         {{ labelOf(filteredOptions[index]) }}
                     </slot>
                 </template>
-            </GroupOptionList>
+            </OptionList>
         </div>
     </div>
 </template>
@@ -81,7 +82,7 @@ import type {LabelKey, SelectItem} from '../types';
 
 import {useListbox} from '../composables/useListbox';
 import {ensureRefValueExists} from '../internal/reactivity';
-import GroupOptionList from './GroupOptionList.vue';
+import OptionList from './OptionList.vue';
 
 const {
     groups,
@@ -167,6 +168,8 @@ const filteredData = computed(() => {
 // The flat list every index (pointer, commit, isSelected) is keyed against — derived from
 // filteredData so indices align with filteredRows.
 const filteredOptions = computed(() => filteredData.value.flatMap((g) => g.options));
+// Stable `v-for` keys for OptionList, indexed by the flat (filtered) option index `rows` navigates.
+const optionKeys = computed(() => filteredOptions.value.map((option) => String(option.id)));
 
 // Build the mixed header/option row sequence from the filtered groups. Empty groups are already
 // excluded by filteredData, so we never emit a header row for a group with no visible options.
@@ -184,7 +187,7 @@ const filteredRows = computed(() => {
     return result;
 });
 
-/** `aria-selected` marks the COMMITTED value — GroupOptionList only asks about rendered indices. */
+/** `aria-selected` marks the COMMITTED value — OptionList only asks about rendered indices. */
 const isSelected = (index: number): boolean => filteredOptions.value[index].id === model.value;
 /** `.is-muted` marks visual de-emphasis only — a muted option stays committable. */
 const isMuted = (index: number): boolean =>
@@ -196,7 +199,7 @@ const input = useTemplateRef<HTMLInputElement>('input');
 // The teleported `.ui-menu-anchor` (null while closed) — floating-ui's floating element.
 const floating = useTemplateRef<HTMLElement>('floating');
 
-// Both keyboard (Enter via useListbox) and pointer (GroupOptionList `commit`) funnel through
+// Both keyboard (Enter via useListbox) and pointer (OptionList `commit`) funnel through
 // this one guard. Read through a local rather than indexing blind: the clamp watcher normally
 // keeps `pointer` in range, but a keypress landing between a filter change and the watcher
 // flush would otherwise index off the end.