@nxgt/material-vue 0.21.0 → 0.22.0

package/docs/components/selection-and-choice.md

@@ -0,0 +1,647 @@
+# Selection & choice
+
+Pick one or several values from a set: selects, comboboxes, autocompletes,
+checkboxes, radios, cards, chips and list pickers. Every field comes with a
+vee-validate wrapper (`SelectFormField`…) that takes a `name` inside a
+`useForm` form — see the [forms guide](../guides/forms.md) for wiring, and
+[what each field emits](../guides/forms.md#what-each-field-emits) for the
+value type each one writes. Everything is imported from
+`@nxgt/material-vue/components`.
+
+| | Component | What it does |
+| --- | --- | --- |
+| <img src="../previews/selection-choice-select.webp" width="96" alt=""> | [Select](#select) | Select primitives with groups and labels, and a native select |
+| <img src="../previews/selection-choice-selectfield.webp" width="96" alt=""> | [SelectField](#selectfield) | Labelled select built from `options` |
+| | [Combobox](#combobox) | Not in `@nxgt/material-vue` — use `ComboboxField` |
+| <img src="../previews/selection-choice-comboboxfield.webp" width="96" alt=""> | [ComboboxField](#comboboxfield) | Labelled, searchable single select |
+| <img src="../previews/selection-choice-autocomplete.webp" width="96" alt=""> | [Autocomplete](#autocomplete) | Single or multiple autocomplete with chips |
+| <img src="../previews/selection-choice-checkbox.webp" width="96" alt=""> | [Checkbox](#checkbox) | Checkbox with an indeterminate state |
+| <img src="../previews/selection-choice-checkboxgroup.webp" width="96" alt=""> | [CheckboxGroup](#checkboxgroup) | Checkbox list valued as `string[]` |
+| <img src="../previews/selection-choice-radiogroup.webp" width="96" alt=""> | [RadioGroup](#radiogroup) | Labelled radio group from `options` |
+| <img src="../previews/selection-choice-checkcardfield.webp" width="96" alt=""> | [CheckCardField](#checkcardfield) | Yes / no as two cards |
+| <img src="../previews/selection-choice-selectcardfield.webp" width="96" alt=""> | [SelectCardField](#selectcardfield) | Choice shown as cards |
+| <img src="../previews/selection-choice-selectchipfield.webp" width="96" alt=""> | [SelectChipField](#selectchipfield) | Choice shown as chips |
+| <img src="../previews/selection-choice-transferlist.webp" width="96" alt=""> | [TransferList](#transferlist) | Two-pane picker |
+| <img src="../previews/selection-choice-sortablelist.webp" width="96" alt=""> | [SortableList](#sortablelist) | Reorderable list of strings |
+| <img src="../previews/selection-choice-switcher.webp" width="96" alt=""> | [Switcher](#switcher) | Workspace or account switcher |
+
+## Select
+
+![Select](../previews/selection-choice-select.webp)
+
+Select primitives with groups, labels and scroll buttons, plus a styled native `<select>`.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectLabel,
+  SelectSeparator,
+  SelectTrigger,
+  SelectValue,
+} from '@nxgt/material-vue/components';
+
+const food = ref('banana');
+</script>
+
+<template>
+  <Select v-model="food">
+    <SelectTrigger>
+      <SelectValue placeholder="Pick one" />
+    </SelectTrigger>
+    <SelectContent>
+      <SelectGroup>
+        <SelectLabel>Fruits</SelectLabel>
+        <SelectItem value="apple">Apple</SelectItem>
+        <SelectItem value="banana">Banana</SelectItem>
+      </SelectGroup>
+      <SelectSeparator />
+      <SelectGroup>
+        <SelectLabel>Vegetables</SelectLabel>
+        <SelectItem value="leek">Leek</SelectItem>
+      </SelectGroup>
+    </SelectContent>
+  </Select>
+</template>
+```
+
+Parts: `Select`, `SelectTrigger`, `SelectValue`, `SelectContent`,
+`SelectGroup`, `SelectLabel`, `SelectItem`, `SelectItemText`,
+`SelectSeparator`, `SelectScrollUpButton`, `SelectScrollDownButton`. They
+wrap Reka UI Select; `Select` takes its root props (`v-model`,
+`default-value`, `open`, `default-open`, `multiple`, `disabled`, `name`).
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `SelectContent` `position` | `'popper' \| 'item-aligned'` | `'popper'` | below the trigger, as wide as it; `item-aligned` overlays it macOS-style |
+| `SelectTrigger` `size` | `'sm' \| 'default'` | `'default'` | trigger height |
+
+`NativeSelect` is the browser's own `<select>` with the library's styling and
+chevron — the calendar's month and year pickers use it. Parts: `NativeSelect` (`v-model`),
+`NativeSelectOption`, `NativeSelectOptGroup`; every other attribute goes to
+the `<select>`.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { NativeSelect, NativeSelectOptGroup, NativeSelectOption } from '@nxgt/material-vue/components';
+
+const food = ref('banana');
+</script>
+
+<template>
+  <NativeSelect v-model="food" aria-label="Food">
+    <NativeSelectOptGroup label="Fruits">
+      <NativeSelectOption value="apple">Apple</NativeSelectOption>
+      <NativeSelectOption value="banana">Banana</NativeSelectOption>
+    </NativeSelectOptGroup>
+  </NativeSelect>
+</template>
+```
+
+**Emits:** `update:modelValue` with the item value (`string` here). For a
+form, use `SelectField` / `SelectFormField`.
+**Storybook:** `Selection & choice/Select` · **React:** `Select` (same parts)
+
+---
+
+## SelectField
+
+![SelectField](../previews/selection-choice-selectfield.webp)
+
+Labelled select built from `options`.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { SelectField } from '@nxgt/material-vue/components';
+
+const frameworks = [
+  { value: 'nuxt', label: 'Nuxt' },
+  { value: 'vitepress', label: 'VitePress' },
+  { value: 'astro', label: 'Astro' },
+];
+
+const framework = ref('nuxt');
+</script>
+
+<template>
+  <SelectField v-model="framework" label="Framework" :options="frameworks" />
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `options` | `{ value: string; label: string }[]` | — | required; the items |
+| `v-model` | `string` | `''` | the selected `value`; `''` for nothing selected |
+| `placeholder` | `string` | `label` | the trigger's text while nothing is selected |
+| `required` | `boolean` | — | an asterisk after the label, and the select's `required` |
+| `label`, `helper-text`, `error`, `disabled` | | — | the field's text and state |
+
+React's `renderOption` is not in Vue: an option shows its `label`.
+
+**Emits:** `update:modelValue` with `string`.
+**Form wrapper:** `SelectFormField` — `name` inside a vee-validate form, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Selection & choice/SelectField` · **React:** `SelectField`, `SelectFormField`
+
+---
+
+## Combobox
+
+The raw combobox primitives are not in `@nxgt/material-vue`. Use
+[`ComboboxField`](#comboboxfield) for a searchable single select,
+[`Autocomplete`](#autocomplete) for several values or free text, or the
+`Command` parts (Overlays & menus) for a hand-built list.
+
+**Storybook:** — · **React:** `Combobox`
+
+---
+
+## ComboboxField
+
+![ComboboxField](../previews/selection-choice-comboboxfield.webp)
+
+Labelled, searchable single select over `{ value, label }` options, in a popover.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { ComboboxField } from '@nxgt/material-vue/components';
+
+const frameworks = [
+  { value: 'nuxt', label: 'Nuxt' },
+  { value: 'vitepress', label: 'VitePress' },
+];
+
+const framework = ref<string | null>(null);
+</script>
+
+<template>
+  <ComboboxField v-model="framework" label="Framework" :options="frameworks" />
+</template>
+```
+
+The trigger shows the selected option's `label`; the search box filters the
+options by label. Picking the selected option again clears it.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `options` | `{ value: string; label: string }[]` | — | required; the items |
+| `v-model` | `string \| null` | `null` | the selected `value`; `null` when cleared |
+| `placeholder` | `string` | "Search…" | trigger and search placeholder |
+| `label`, `helper-text`, `error`, `disabled` | | — | the field's text and state |
+| `required` | `boolean` | — | the asterisk, and `aria-required` on the `combobox` trigger |
+
+**Emits:** `update:modelValue` with `string | null`.
+**Form wrapper:** `ComboboxFormField` — `name` inside a vee-validate form, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Selection & choice/ComboboxField` · **React:** `ComboboxField`, `ComboboxFormField`
+
+---
+
+## Autocomplete
+
+![Autocomplete](../previews/selection-choice-autocomplete.webp)
+
+Single or multiple (chips) autocomplete with free-solo values and a query event.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Autocomplete } from '@nxgt/material-vue/components';
+
+const frameworks = [
+  { value: 'nuxt', label: 'Nuxt' },
+  { value: 'vitepress', label: 'VitePress' },
+  { value: 'astro', label: 'Astro' },
+];
+
+const picked = ref<string[]>(['nuxt']);
+</script>
+
+<template>
+  <Autocomplete
+    v-model="picked"
+    mode="multiple"
+    label="Framework"
+    placeholder="Choose a framework"
+    :options="frameworks"
+  />
+</template>
+```
+
+| Prop / event | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `mode` | `'single' \| 'multiple'` | `'single'` | decides the `v-model` type |
+| `v-model` | `string \| string[] \| null` | `null` | per `mode` |
+| `options` | `{ value: string; label: string }[]` | — | required; the items |
+| `free-solo` | `boolean` | `false` | accept a typed value that is not an option ("Add …") |
+| `@query-change` | `(query: string) => void` | — | the typed text, debounced 300 ms — fetch options here |
+| `empty` | `string` | "No option found." | text when nothing matches |
+| `required` | `boolean` | — | the asterisk, and `aria-required` on the input, which the label names |
+| `error` | `boolean` | — | red border on the box, error helper text, `aria-invalid` on the input |
+
+React's `getOptionValue` / `getOptionLabel` and `actions` are not in Vue:
+options are `{ value, label }`. In `multiple` mode each chip is a dismissible
+`Chip`: its remove button is named "Remove {label}", and is disabled with the
+field.
+
+**Emits:** `update:modelValue` with `string | null` in `single` mode,
+`string[]` in `multiple`.
+**Form wrapper:** `AutocompleteFormField` — `name` inside a vee-validate form, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Selection & choice/Autocomplete` · **React:** `Autocomplete`, `AutocompleteFormField`
+
+---
+
+## Checkbox
+
+![Checkbox](../previews/selection-choice-checkbox.webp)
+
+Reka UI checkbox with an indeterminate state; pair it with a `Label`.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Checkbox, Label } from '@nxgt/material-vue/components';
+
+const receipts = ref(true);
+</script>
+
+<template>
+  <div class="flex items-center gap-2">
+    <Checkbox id="receipts" v-model="receipts" />
+    <Label for="receipts">Email me receipts</Label>
+  </div>
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `v-model` / `default-value` | `boolean \| 'indeterminate'` | — | Reka UI checkbox state |
+| `disabled`, `required`, `name`, `value` | | — | as on a native checkbox |
+
+Unlike React, `Checkbox` has no `label` / `helper-text` of its own, and there
+is no `CheckboxFormField`: bind `v-model` to a `useField` value, or use
+`CheckboxGroup` / `SwitchFormField`.
+
+**Emits:** `update:modelValue` with `boolean | 'indeterminate'`.
+**Form wrapper:** none — `useField` + `v-model`, see [forms](../guides/forms.md#the-pair).
+**Storybook:** `Selection & choice/Checkbox` · **React:** `Checkbox`, `CheckboxFormField`
+
+---
+
+## CheckboxGroup
+
+![CheckboxGroup](../previews/selection-choice-checkboxgroup.webp)
+
+Checkbox list built from `options`, valued as `string[]`.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CheckboxGroup } from '@nxgt/material-vue/components';
+
+const frameworks = [
+  { value: 'nuxt', label: 'Nuxt' },
+  { value: 'astro', label: 'Astro' },
+];
+
+const picked = ref<string[]>(['astro']);
+</script>
+
+<template>
+  <CheckboxGroup v-model="picked" label="Framework" :options="frameworks" />
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `options` | `{ value: string; label: string }[]` | — | required; the boxes |
+| `v-model` | `string[]` | `[]` | the checked values; the new list on each toggle |
+| `orientation` | `'vertical' \| 'horizontal'` | `'horizontal'` | layout |
+| `label`, `helper-text` | `string` | — | the question and its help or error text, above the boxes |
+| `disabled`, `error` | `boolean` | — | every box / error colour |
+| `id` | `string` | generated | the group's `id`; option *i* gets `` `${id}-${i}` ``, which its label points at, whatever characters its `value` holds; the label is `` `${id}-label` ``, the helper text `` `${id}-helper` `` |
+
+The group's root `div` is a `role="group"` named by `label`
+(`aria-labelledby`) and described by `helper-text` (`aria-describedby`), so a
+screen reader announces the question before the first box. Your own
+`aria-label` / `aria-labelledby` wins, and your `aria-describedby` ids come
+first. A `group` may not carry `aria-invalid`, so one you pass is dropped: an
+error is said through the helper text, or a visually hidden "This value is not
+valid." when there is none. `CheckboxGroupFormField` touched and invalid with no
+message yet (the form validated silently) keeps your `helper-text` and adds a
+visually hidden "This value is not valid." inside it, so the group's description
+is "<helper-text> This value is not valid.". See
+[troubleshooting](../troubleshooting.md#a-checkboxgroup-or-radiogroupfield-option-selected-by-id-value-stops-matching)
+if a selector built from an option's `value`, or an attribute on the group,
+stops matching.
+
+The `#helper-text` slot replaces the helper text's content (shown only while
+`helper-text` is set) and stays part of the group's description.
+
+**Emits:** `update:modelValue` with `string[]`.
+**Form wrapper:** `CheckboxGroupFormField` — `name` inside a vee-validate form, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Selection & choice/CheckboxGroup` · **React:** `CheckboxGroup`, `CheckboxGroupFormField`
+
+---
+
+## RadioGroup
+
+![RadioGroup](../previews/selection-choice-radiogroup.webp)
+
+Labelled radio group built from `options`, horizontal or vertical.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { RadioGroupField } from '@nxgt/material-vue/components';
+
+const plans = [
+  { value: 'free', label: 'Free' },
+  { value: 'pro', label: 'Pro' },
+];
+
+const plan = ref('free');
+</script>
+
+<template>
+  <RadioGroupField v-model="plan" label="Plan" :options="plans" />
+</template>
+```
+
+Parts: `RadioGroupField` (labelled, from `options`), and the Reka UI
+primitives `RadioGroup` and `RadioGroupItem` for a hand-built layout. In
+React the labelled one is called `RadioGroup`.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `options` | `{ value: string; label: string }[]` | — | required; the radios |
+| `v-model` | `string` | — | the selected `value` |
+| `orientation` | `'vertical' \| 'horizontal'` | `'horizontal'` | layout |
+| `label`, `helper-text`, `error`, `disabled` | | — | the field's text and state |
+| `id` | `string` | generated | the group's `id`; option *i* gets `` `${id}-${i}` ``, which its label points at, whatever characters its `value` holds; the label is `` `${id}-label` ``, the helper text `` `${id}-helper` `` |
+
+The `radiogroup` is named by `label` (`aria-labelledby`), described by
+`helper-text` (`aria-describedby`) and carries `aria-invalid` while `error`
+(your own `aria-invalid` wins), so a screen reader announces the question before the first radio. Attributes you
+put on `RadioGroupField` land on the `radiogroup` (`class` and `style` stay on
+the layout wrapper): your own `aria-label` / `aria-labelledby` wins, and your
+`aria-describedby` ids come first.
+
+**Emits:** `update:modelValue` with `string`.
+**Form wrapper:** `RadioGroupFormField` — `name` inside a vee-validate form, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Selection & choice/RadioGroup` · **React:** `RadioGroup`, `RadioGroupItem`, `RadioGroupFormField`
+
+---
+
+## CheckCardField
+
+![CheckCardField](../previews/selection-choice-checkcardfield.webp)
+
+A yes / no choice shown as two selectable cards.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CheckCardField, type CheckCardFieldOption } from '@nxgt/material-vue/components';
+
+const options: [CheckCardFieldOption, CheckCardFieldOption] = [
+  { title: 'Delivery', description: 'Brought to your door' },
+  { title: 'Pick-up', description: 'Collect it in store' },
+];
+
+const delivery = ref(true);
+</script>
+
+<template>
+  <CheckCardField v-model="delivery" label="How do you want it?" :options="options" />
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `options` | `[yes, no]`, each `{ title, description? }` | — | required; the first card is `true`, the second `false` |
+| `v-model` | `boolean` | — | `undefined` selects the second card |
+| `label`, `helper-text`, `error`, `disabled` | | — | the field's text and state |
+
+**Emits:** `update:modelValue` with `boolean`.
+**Form wrapper:** `CheckCardFormField` — `name` inside a vee-validate form, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Selection & choice/CheckCardField` · **React:** `CheckCardField`, `CheckCardFormField`
+
+---
+
+## SelectCardField
+
+![SelectCardField](../previews/selection-choice-selectcardfield.webp)
+
+Single or multiple choice shown as selectable cards.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { SelectCardField } from '@nxgt/material-vue/components';
+
+const plans = [
+  { value: 'starter', title: 'Starter', description: '1 seat' },
+  { value: 'team', title: 'Team', description: 'Up to 20 seats' },
+];
+
+const plan = ref<string[]>(['team']);
+</script>
+
+<template>
+  <SelectCardField v-model="plan" label="Plan" :options="plans" />
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `mode` | `'single' \| 'multiple'` | `'single'` | clicking the selected card in `single` mode clears it |
+| `v-model` | `string[]` | `[]` | the selected values, even in `single` mode |
+| `options` | `{ value, title, description? }[]` | — | required; the cards |
+| `label`, `helper-text`, `error`, `disabled` | | — | the field's text and state |
+
+**Emits:** `update:modelValue` with `string[]`. `SelectCardFormField` stores
+`string[]` in both modes (React stores `string | null` in `single` mode).
+**Form wrapper:** `SelectCardFormField` — `name` inside a vee-validate form, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Selection & choice/SelectCardField` · **React:** `SelectCardField`, `SelectCardFormField`
+
+---
+
+## SelectChipField
+
+![SelectChipField](../previews/selection-choice-selectchipfield.webp)
+
+Single or multiple choice shown as toggleable chips.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { SelectChipField } from '@nxgt/material-vue/components';
+
+const topics = [
+  { value: 'design', label: 'Design' },
+  { value: 'code', label: 'Code' },
+];
+
+const picked = ref<string[]>([]);
+</script>
+
+<template>
+  <SelectChipField v-model="picked" label="Topics" mode="multiple" :options="topics" />
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `mode` | `'single' \| 'multiple'` | `'single'` | clicking the selected chip in `single` mode clears it |
+| `v-model` | `string[]` | `[]` | the selected values, even in `single` mode |
+| `options` | `{ value: string; label: string }[]` | — | required; the chips |
+| `label`, `helper-text`, `error`, `disabled` | | — | the field's text and state |
+
+**Emits:** `update:modelValue` with `string[]`. `SelectChipFormField` stores
+`string[]` in both modes (React stores `string | null` in `single` mode).
+**Form wrapper:** `SelectChipFormField` — `name` inside a vee-validate form, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Selection & choice/SelectChipField` · **React:** `SelectChipField`, `SelectChipFormField`
+
+---
+
+## TransferList
+
+![TransferList](../previews/selection-choice-transferlist.webp)
+
+Two-pane picker with search, drag-and-drop, reordering and a `max`.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { TransferList, type TransferListItem } from '@nxgt/material-vue/components';
+
+const people: TransferListItem[] = [
+  { value: 'ada', label: 'Ada Lovelace', subtitle: 'Mathematics' },
+  { value: 'alan', label: 'Alan Turing', subtitle: 'Computing' },
+  { value: 'grace', label: 'Grace Hopper', subtitle: 'Compilers' },
+];
+
+const team = ref<string[]>(['ada']);
+</script>
+
+<template>
+  <TransferList v-model="team" label="Team" :items="people" :max="2" />
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `items` | `TransferListItem[]` | — | required; `{ value, label, subtitle?, icon?, group?, disabled?, locked? }` |
+| `v-model` / `default-value` | `string[]` | — | the selected values, in order |
+| `max` | `number` | — | cap on the selected pane |
+| `reorderable` | `boolean` | `false` | reorder inside the selected pane |
+| `draggable` | `boolean` | `true` | drag between panes |
+| `searchable`, `show-select-all`, `show-transfer-all` | `boolean` | `true` | pane chrome |
+| `titles` | `{ available?, selected? }` | "Available", "Selected" | pane titles |
+| `height` | `number \| string` | `320` | pane height |
+| `required` | `boolean` | — | the asterisk, and `aria-required` on the Selected `listbox`, which holds the value |
+
+Each pane is a `listbox` named by the field's label, then its title:
+`getByRole('listbox', { name: 'Team Selected' })`.
+
+The `#item` slot replaces a row's content. `useTransferList` is the
+composable behind it, for a custom layout.
+
+**Emits:** `update:modelValue` with `string[]`.
+**Form wrapper:** `TransferListFormField` — `name` inside a vee-validate form, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Selection & choice/TransferList` · **React:** `TransferList`, `TransferListFormField`
+
+---
+
+## SortableList
+
+![SortableList](../previews/selection-choice-sortablelist.webp)
+
+Searchable list of strings you reorder by dragging or with the keyboard.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { SortableList, type SortableListItem } from '@nxgt/material-vue/components';
+
+const people: SortableListItem[] = [
+  { value: 'ada', label: 'Ada Lovelace' },
+  { value: 'alan', label: 'Alan Turing' },
+  { value: 'grace', label: 'Grace Hopper' },
+];
+
+const ranking = ref(people.map((item) => item.value));
+</script>
+
+<template>
+  <SortableList v-model="ranking" label="Ranking" :items="people" />
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `items` | `SortableListItem[]` | — | required; `{ value, label, subtitle?, icon?, disabled? }` |
+| `v-model` / `default-value` | `string[]` | — | the order |
+| `draggable` | `boolean` | `true` | drag handles |
+| `reorderable` | `boolean` | `false` | move up / down buttons |
+| `searchable` | `boolean` | `true` | filter box |
+| `height` | `number \| string` | `320` | list height |
+| `required` | `boolean` | — | the asterisk, and `aria-required` on the `listbox`, which the label names |
+
+The `#item` slot replaces a row's content.
+
+**Emits:** `update:modelValue` with `string[]`, in the new order.
+**Form wrapper:** `SortableListFormField` — `name` inside a vee-validate form, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Selection & choice/SortableList` · **React:** `SortableList`, `SortableListFormField`
+
+---
+
+## Switcher
+
+![Switcher](../previews/selection-choice-switcher.webp)
+
+Dropdown for switching the active workspace or account, with an avatar.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Switcher, type SwitcherItem } from '@nxgt/material-vue/components';
+
+const workspaces: SwitcherItem[] = [
+  { id: 'acme', title: 'Acme Studio', subtitle: 'ada@acme.example' },
+  { id: 'personal', title: 'Personal', subtitle: 'ada@example.com' },
+];
+
+const workspace = ref('acme');
+</script>
+
+<template>
+  <Switcher v-model="workspace" label="Workspaces" :options="workspaces" />
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `options` | `SwitcherItem[]` | — | required; `{ id, title, subtitle? }`, shown with an initial avatar |
+| `v-model` | `string` | — | required; the active `id` |
+| `label` | `string` | — | required; heading of the menu |
+
+**Emits:** `update:modelValue` with `string` (the item `id`). No form
+wrapper — it switches context, it is not a form value.
+**Storybook:** `Selection & choice/Switcher` · **React:** `Switcher`