@slotted/react 0.0.0-stage → 0.1.0-beta.0

package/dist/docs/select.examples.md

@@ -0,0 +1,1348 @@
+<!-- index: ./index.md -->
+# select
+
+`data-ui="select"` · Picks one option from a popup list.
+
+## Examples
+
+### Playground
+
+One select with every axis on it, driven by the controls under the canvas. Change size, variant and width and watch the control and its popup answer together.
+
+Excerpt — not a complete module
+
+```tsx
+<Select>
+  <SelectTrigger aria-label="Fruit">
+    <SelectValue placeholder="Choose a fruit" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="apple">Apple</SelectItem>
+    <SelectItem value="blueberry">Blueberry</SelectItem>
+  </SelectContent>
+</Select>;
+```
+
+### Controlled and uncontrolled
+
+The left one owns its own value; the right one hands it to the page, and the request carries the reason so a consumer can tell a press from a key.
+
+Excerpt — not a complete module
+
+```tsx
+<Select defaultValue="blueberry">…</Select>;
+
+<Select value={fruit} onValueChange={(next, request) => setFruit(next, request.reason)}>
+  …
+</Select>;
+```
+
+### Placeholder and unresolved values
+
+Nothing chosen shows the placeholder in the muted step. A value the collection cannot name shows the value itself, which is what an async list holds for one render.
+
+Example
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  type SelectOption,
+  SelectTrigger,
+  SelectValue,
+} from '@slotted/react/select';
+import { Stack } from '@slotted/react/stack';
+
+const REASONS: SelectOption[] = [
+  { value: 'damaged', label: 'Arrived damaged' },
+  { value: 'wrong-item', label: 'Wrong item shipped' },
+  { value: 'not-needed', label: 'No longer needed' },
+];
+
+const TERMS: SelectOption[] = [
+  { value: 'prepaid', label: 'Prepaid' },
+  { value: 'net-30', label: 'Net 30' },
+  { value: 'net-45', label: 'Net 45' },
+];
+
+export default function SelectPlaceholder() {
+  return (
+    <Stack gap={5}>
+      <Field>
+        <FieldLabel>Return reason</FieldLabel>
+        <Select>
+          <SelectTrigger>
+            <SelectValue placeholder="Choose a reason" />
+          </SelectTrigger>
+          <SelectContent>
+            {REASONS.map((reason) => (
+              <SelectItem key={reason.value} value={reason.value}>
+                {reason.label}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </Field>
+      <Field>
+        <FieldLabel>Payment terms</FieldLabel>
+        <Select defaultValue="net-30" items={TERMS}>
+          <SelectTrigger>
+            <SelectValue placeholder="Choose terms" />
+          </SelectTrigger>
+          <SelectContent>
+            {TERMS.map((term) => (
+              <SelectItem key={term.value} value={term.value}>
+                {term.label}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### Groups, icons and descriptions
+
+Two named groups with a line between them. Every label starts on the same line whether or not its option carries artwork, because the column belongs to the list.
+
+Example
+
+```tsx
+import { Fragment } from 'react';
+import { Field, FieldLabel } from '@slotted/react/field';
+import {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  type SelectOptionGroup,
+  SelectSeparator,
+  SelectTrigger,
+  SelectValue,
+} from '@slotted/react/select';
+
+const METHODS: SelectOptionGroup[] = [
+  {
+    label: 'Ground',
+    options: [
+      { value: 'ups-ground', label: 'UPS Ground' },
+      { value: 'fedex-ground', label: 'FedEx Ground' },
+    ],
+  },
+  {
+    label: 'Express',
+    options: [
+      { value: 'ups-2day', label: 'UPS 2nd Day Air' },
+      { value: 'fedex-overnight', label: 'FedEx Priority Overnight' },
+    ],
+  },
+  {
+    label: 'Freight',
+    options: [{ value: 'ltl', label: 'LTL freight, palletised' }],
+  },
+];
+
+export default function SelectGroups() {
+  return (
+    <Field>
+      <FieldLabel>Shipping method</FieldLabel>
+      <Select>
+        <SelectTrigger>
+          <SelectValue placeholder="Choose a method" />
+        </SelectTrigger>
+        <SelectContent>
+          {METHODS.map((group, index) => (
+            <Fragment key={group.label}>
+              {index > 0 ? <SelectSeparator /> : null}
+              <SelectGroup label={group.label}>
+                {group.options.map((method) => (
+                  <SelectItem key={method.value} value={method.value}>
+                    {method.label}
+                  </SelectItem>
+                ))}
+              </SelectGroup>
+            </Fragment>
+          ))}
+        </SelectContent>
+      </Select>
+    </Field>
+  );
+}
+```
+
+### Multiple selection
+
+The popup stays open as options are taken, and the control shows the first label and how many more. Space toggles without closing, which is the listbox pattern’s own model.
+
+Example
+
+```tsx
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  type SelectOption,
+  SelectTrigger,
+  SelectValue,
+} from '@slotted/react/select';
+
+const TEAMS: SelectOption[] = [
+  { value: 'fulfilment', label: 'Fulfilment' },
+  { value: 'finance', label: 'Finance' },
+  { value: 'customer-care', label: 'Customer care' },
+  { value: 'purchasing', label: 'Purchasing' },
+  { value: 'returns', label: 'Returns desk' },
+];
+
+export default function SelectMultiple() {
+  return (
+    <Field>
+      <FieldLabel>Notify teams</FieldLabel>
+      <Select multiple clearable defaultValue={['fulfilment', 'finance']} items={TEAMS}>
+        <SelectTrigger>
+          <SelectValue placeholder="No one is notified" />
+        </SelectTrigger>
+        <SelectContent>
+          {TEAMS.map((team) => (
+            <SelectItem key={team.value} value={team.value}>
+              {team.label}
+            </SelectItem>
+          ))}
+        </SelectContent>
+      </Select>
+      <FieldDescription>Each team gets an email when the order is delayed.</FieldDescription>
+    </Field>
+  );
+}
+```
+
+### Clearable
+
+The clear button appears only once something is chosen, and focus goes back to the control it belonged to rather than to the document.
+
+Example
+
+```tsx
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  type SelectOption,
+  SelectTrigger,
+  SelectValue,
+} from '@slotted/react/select';
+
+const OWNERS: SelectOption[] = [
+  { value: 'avery', label: 'Avery Collins' },
+  { value: 'kenji', label: 'Kenji Watanabe' },
+  { value: 'lucia', label: 'Lucía Fernández' },
+  { value: 'ruth', label: 'Ruth Adeyemi' },
+];
+
+export default function SelectClearable() {
+  return (
+    <Field>
+      <FieldLabel>Assignee</FieldLabel>
+      <Select clearable defaultValue="kenji" items={OWNERS}>
+        <SelectTrigger>
+          <SelectValue placeholder="Unassigned" />
+        </SelectTrigger>
+        <SelectContent>
+          {OWNERS.map((owner) => (
+            <SelectItem key={owner.value} value={owner.value}>
+              {owner.label}
+            </SelectItem>
+          ))}
+        </SelectContent>
+      </Select>
+      <FieldDescription>Clear the assignee to return the ticket to the queue.</FieldDescription>
+    </Field>
+  );
+}
+```
+
+### Sizes
+
+Three steps, and every one of them reads control geometry — so a select beside a text field of the same size is the same height to the pixel.
+
+Example
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  type SelectOption,
+  type SelectSize,
+  SelectTrigger,
+  SelectValue,
+} from '@slotted/react/select';
+import { Stack } from '@slotted/react/stack';
+
+const SIZES: { size: SelectSize; label: string }[] = [
+  { size: 'sm', label: 'Small' },
+  { size: 'md', label: 'Medium' },
+  { size: 'lg', label: 'Large' },
+];
+
+const WAREHOUSES: SelectOption[] = [
+  { value: 'RNO', label: 'Reno, NV' },
+  { value: 'CMH', label: 'Columbus, OH' },
+  { value: 'SAV', label: 'Savannah, GA' },
+];
+
+export default function SelectSizes() {
+  return (
+    <Stack gap={5}>
+      {SIZES.map((step) => (
+        <Field key={step.size}>
+          <FieldLabel>{step.label}</FieldLabel>
+          <Select size={step.size} defaultValue="RNO" items={WAREHOUSES}>
+            <SelectTrigger>
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              {WAREHOUSES.map((warehouse) => (
+                <SelectItem key={warehouse.value} value={warehouse.value}>
+                  {warehouse.label}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+        </Field>
+      ))}
+    </Stack>
+  );
+}
+```
+
+### Variants
+
+outline on the page, subtle where a form sinks into its card, and plain for a table cell that is only a control while it is being used.
+
+Example
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+  type SelectVariant,
+} from '@slotted/react/select';
+import { Stack } from '@slotted/react/stack';
+
+const VARIANTS: { variant: SelectVariant; label: string }[] = [
+  { variant: 'outline', label: 'Outline' },
+  { variant: 'subtle', label: 'Subtle' },
+  { variant: 'plain', label: 'Plain' },
+];
+
+const WAREHOUSES = [
+  { value: 'RNO', label: 'Reno, NV' },
+  { value: 'CMH', label: 'Columbus, OH' },
+  { value: 'SAV', label: 'Savannah, GA' },
+];
+
+export default function SelectVariants() {
+  return (
+    <Stack gap={5}>
+      {VARIANTS.map((step) => (
+        <Field key={step.variant}>
+          <FieldLabel>{step.label}</FieldLabel>
+          <Select variant={step.variant}>
+            <SelectTrigger>
+              <SelectValue placeholder="Choose a warehouse" />
+            </SelectTrigger>
+            <SelectContent>
+              {WAREHOUSES.map((warehouse) => (
+                <SelectItem key={warehouse.value} value={warehouse.value}>
+                  {warehouse.label}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+        </Field>
+      ))}
+    </Stack>
+  );
+}
+```
+
+### States
+
+Required, invalid, read-only and disabled side by side. Read-only keeps its value legible and refuses to open; disabled answers nothing at all.
+
+Example
+
+```tsx
+import { Field, FieldDescription, FieldError, FieldLabel } from '@slotted/react/field';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  type SelectOption,
+  SelectTrigger,
+  SelectValue,
+} from '@slotted/react/select';
+import { Stack } from '@slotted/react/stack';
+
+const WAREHOUSES: SelectOption[] = [
+  { value: 'RNO', label: 'Reno, NV' },
+  { value: 'CMH', label: 'Columbus, OH' },
+  { value: 'SAV', label: 'Savannah, GA' },
+];
+
+export default function SelectStates() {
+  return (
+    <Stack gap={5}>
+      <Field invalid required>
+        <FieldLabel>Return warehouse</FieldLabel>
+        <Select defaultValue="SAV" items={WAREHOUSES}>
+          <SelectTrigger>
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            {WAREHOUSES.map((warehouse) => (
+              <SelectItem key={warehouse.value} value={warehouse.value}>
+                {warehouse.label}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+        <FieldError>Savannah does not accept returns. Choose Reno or Columbus.</FieldError>
+      </Field>
+      <Field readOnly>
+        <FieldLabel>Origin warehouse</FieldLabel>
+        <Select defaultValue="RNO" items={WAREHOUSES}>
+          <SelectTrigger>
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            {WAREHOUSES.map((warehouse) => (
+              <SelectItem key={warehouse.value} value={warehouse.value}>
+                {warehouse.label}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+        <FieldDescription>Set when the order was picked.</FieldDescription>
+      </Field>
+      <Field disabled>
+        <FieldLabel>Transfer warehouse</FieldLabel>
+        <Select defaultValue="CMH" items={WAREHOUSES}>
+          <SelectTrigger>
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            {WAREHOUSES.map((warehouse) => (
+              <SelectItem key={warehouse.value} value={warehouse.value}>
+                {warehouse.label}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+        <FieldDescription>Transfers open once the order is invoiced.</FieldDescription>
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### Loading and empty
+
+A popup with nothing in it opens onto a sentence rather than onto a two-pixel box, and a loading one keeps that measure so nothing jumps when the options land.
+
+Excerpt — not a complete module
+
+```tsx
+<Select loading>
+  <SelectContent status="Fetching teams…">{options}</SelectContent>
+</Select>;
+
+<SelectContent empty="No teams yet">{[]}</SelectContent>;
+```
+
+### Content the family did not choose
+
+A translated label, an unbroken identifier and a hundred options. The label clamps at two lines with the whole string still in the DOM, and the token breaks inside the option.
+
+Excerpt — not a complete module
+
+```tsx
+<SelectItem value="urn">urn:acme:catalogue:9f2c41ab8de07c5511903fbe</SelectItem>;
+```
+
+### Searching a long list
+
+search opens the popup onto a field. The query filters the options, the span it matched is marked, and the count is announced. It is transient: it never becomes a value, it is emptied when an option is taken, and the control goes on showing the chosen label. Escape clears the query before it closes the popup, and Tab commits and leaves the control.
+
+Example
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  type SelectOption,
+  SelectTrigger,
+  SelectValue,
+} from '@slotted/react/select';
+
+const COUNTRIES: SelectOption[] = [
+  { value: 'AR', label: 'Argentina' },
+  { value: 'AU', label: 'Australia' },
+  { value: 'AT', label: 'Austria' },
+  { value: 'BE', label: 'Belgium' },
+  { value: 'BR', label: 'Brazil' },
+  { value: 'CA', label: 'Canada' },
+  { value: 'CL', label: 'Chile' },
+  { value: 'CO', label: 'Colombia' },
+  { value: 'CI', label: 'Côte d’Ivoire' },
+  { value: 'DK', label: 'Denmark' },
+  { value: 'FI', label: 'Finland' },
+  { value: 'FR', label: 'France' },
+  { value: 'DE', label: 'Germany' },
+  { value: 'IE', label: 'Ireland' },
+  { value: 'IT', label: 'Italy' },
+  { value: 'JP', label: 'Japan' },
+  { value: 'MX', label: 'Mexico' },
+  { value: 'NL', label: 'Netherlands' },
+  { value: 'NZ', label: 'New Zealand' },
+  { value: 'NO', label: 'Norway' },
+  { value: 'PL', label: 'Poland' },
+  { value: 'PT', label: 'Portugal' },
+  { value: 'ES', label: 'Spain' },
+  { value: 'SE', label: 'Sweden' },
+  { value: 'CH', label: 'Switzerland' },
+  { value: 'TR', label: 'Türkiye' },
+  { value: 'GB', label: 'United Kingdom' },
+  { value: 'US', label: 'United States' },
+  { value: 'UY', label: 'Uruguay' },
+  { value: 'VN', label: 'Vietnam' },
+];
+
+export default function SelectSearch() {
+  return (
+    <Field>
+      <FieldLabel>Ship-to country</FieldLabel>
+      <Select
+        search
+        defaultValue="US"
+        items={COUNTRIES}
+        messages={{ searchPlaceholder: 'Filter countries' }}
+      >
+        <SelectTrigger>
+          <SelectValue placeholder="Choose a country" />
+        </SelectTrigger>
+        <SelectContent>
+          {COUNTRIES.map((country) => (
+            <SelectItem key={country.value} value={country.value}>
+              {country.label}
+            </SelectItem>
+          ))}
+        </SelectContent>
+      </Select>
+    </Field>
+  );
+}
+```
+
+### Placement and width
+
+The popup hangs from the start edge of its control. It is never narrower than the control and grows when an option needs more room, so a narrow control does not wrap its labels. width="anchor" pins it to the width of the control.
+
+Example
+
+```tsx
+import { Inline } from '@slotted/react/inline';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  type SelectOption,
+  SelectTrigger,
+  SelectValue,
+} from '@slotted/react/select';
+
+const PAGE_SIZES: SelectOption[] = [
+  { value: '25', label: '25 rows' },
+  { value: '50', label: '50 rows' },
+  { value: '100', label: '100 rows' },
+];
+
+const SORTS: (SelectOption & { description: string })[] = [
+  { value: 'newest', label: 'Newest', description: 'Most recent order date first.' },
+  { value: 'total', label: 'Total', description: 'Largest order total first.' },
+  { value: 'ship-date', label: 'Ship date', description: 'Earliest promised ship date first.' },
+];
+
+export default function SelectPlacement() {
+  return (
+    <Inline gap={3} justify="between" align="center">
+      <Select side="top" fullWidth={false} defaultValue="25" items={PAGE_SIZES}>
+        <SelectTrigger aria-label="Rows per page">
+          <SelectValue />
+        </SelectTrigger>
+        <SelectContent>
+          {PAGE_SIZES.map((size) => (
+            <SelectItem key={size.value} value={size.value}>
+              {size.label}
+            </SelectItem>
+          ))}
+        </SelectContent>
+      </Select>
+      <Select align="end" width="content" fullWidth={false} defaultValue="newest" items={SORTS}>
+        <SelectTrigger aria-label="Sort orders">
+          <SelectValue />
+        </SelectTrigger>
+        <SelectContent>
+          {SORTS.map((sort) => (
+            <SelectItem key={sort.value} value={sort.value} description={sort.description}>
+              {sort.label}
+            </SelectItem>
+          ))}
+        </SelectContent>
+      </Select>
+    </Inline>
+  );
+}
+```
+
+### Keyboard
+
+Focus never leaves the button: the arrows, Home, End and the page keys move aria-activedescendant, and typing jumps to the first option that begins with it.
+
+Excerpt — not a complete module
+
+```tsx
+<Select loop={false} typeahead typeaheadTimeout={500}>
+  …
+</Select>;
+```
+
+### In a form
+
+Inside a field, with a label, a description and an error. name renders a hidden native select, so a plain form submits and reset() restores.
+
+Example
+
+```tsx
+import { useState } from 'react';
+import type { SubmitEvent } from 'react';
+import { Button } from '@slotted/react/button';
+import { Field, FieldError, FieldLabel } from '@slotted/react/field';
+import { Inline } from '@slotted/react/inline';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  type SelectOption,
+  SelectTrigger,
+  SelectValue,
+} from '@slotted/react/select';
+import { Stack } from '@slotted/react/stack';
+import { Text } from '@slotted/react/typography';
+
+const WAREHOUSES: SelectOption[] = [
+  { value: 'RNO', label: 'Reno, NV' },
+  { value: 'CMH', label: 'Columbus, OH' },
+  { value: 'SAV', label: 'Savannah, GA' },
+];
+
+const CARRIERS: SelectOption[] = [
+  { value: 'ups', label: 'UPS Ground' },
+  { value: 'fedex', label: 'FedEx Ground' },
+  { value: 'usps', label: 'USPS Priority Mail' },
+];
+
+const labelOf = (options: SelectOption[], value: FormDataEntryValue | null) =>
+  options.find((option) => option.value === value)?.label;
+
+export default function SelectForm() {
+  const [missing, setMissing] = useState(false);
+  const [saved, setSaved] = useState<string | null>(null);
+
+  const submit = (event: SubmitEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const data = new FormData(event.currentTarget);
+    const warehouse = labelOf(WAREHOUSES, data.get('warehouse'));
+    const carrier = labelOf(CARRIERS, data.get('carrier'));
+    setMissing(warehouse === undefined);
+    setSaved(warehouse === undefined ? null : `Ships from ${warehouse} by ${carrier}.`);
+  };
+
+  const reset = () => {
+    setMissing(false);
+    setSaved(null);
+  };
+
+  return (
+    <form noValidate onSubmit={submit} onReset={reset}>
+      <Stack gap={5}>
+        <Field required invalid={missing ? true : undefined}>
+          <FieldLabel>Fulfilment warehouse</FieldLabel>
+          <Select name="warehouse" items={WAREHOUSES} onValueChange={() => setMissing(false)}>
+            <SelectTrigger>
+              <SelectValue placeholder="Choose a warehouse" />
+            </SelectTrigger>
+            <SelectContent>
+              {WAREHOUSES.map((warehouse) => (
+                <SelectItem key={warehouse.value} value={warehouse.value}>
+                  {warehouse.label}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+          <FieldError live="polite" reserve>
+            {missing ? 'Choose the warehouse that ships this order.' : ''}
+          </FieldError>
+        </Field>
+        <Field>
+          <FieldLabel>Carrier</FieldLabel>
+          <Select name="carrier" defaultValue="ups" items={CARRIERS}>
+            <SelectTrigger>
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              {CARRIERS.map((carrier) => (
+                <SelectItem key={carrier.value} value={carrier.value}>
+                  {carrier.label}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+        </Field>
+        <Inline gap={3} align="center">
+          <Button type="submit">Save</Button>
+          <Button type="reset" tone="secondary" variant="outline">
+            Reset
+          </Button>
+          {saved && (
+            <Text size="sm" tone="muted">
+              {saved}
+            </Text>
+          )}
+        </Inline>
+      </Stack>
+    </form>
+  );
+}
+```
+
+### Composition
+
+Defaults set once for a whole application, a summary the consumer writes, and the frame replaced with an element of their own through render.
+
+Excerpt — not a complete module
+
+```tsx
+<SelectDefaultsProvider size="sm" variant="subtle" width="anchor">
+  <Select ref={handle}>
+    <SelectTrigger render={(props) => <label {...props} />}>
+      <SelectValue>{(values, labels) => labels.join(', ')}</SelectValue>
+    </SelectTrigger>
+    …
+  </Select>
+</SelectDefaultsProvider>;
+```
+
+### controlled.tsx
+
+Example
+
+```tsx
+import { useState } from 'react';
+import { Field, FieldLabel } from '@slotted/react/field';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@slotted/react/select';
+import { Stack } from '@slotted/react/stack';
+
+const SPEEDS = [
+  { value: 'ground', label: 'Ground', transit: '3–5 business days', price: '$8.40' },
+  { value: 'two-day', label: 'Two-day', transit: '2 business days', price: '$18.90' },
+  { value: 'overnight', label: 'Overnight', transit: 'Next business day', price: '$42.75' },
+];
+
+export default function SelectControlled() {
+  const [speed, setSpeed] = useState('ground');
+  const chosen = SPEEDS.find((option) => option.value === speed);
+
+  return (
+    <Stack gap={4}>
+      <Field>
+        <FieldLabel>Delivery speed</FieldLabel>
+        <Select
+          value={speed}
+          items={SPEEDS}
+          onValueChange={(next) => {
+            if (typeof next === 'string') setSpeed(next);
+          }}
+        >
+          <SelectTrigger>
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            {SPEEDS.map((option) => (
+              <SelectItem key={option.value} value={option.value}>
+                {option.label}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </Field>
+      <span>
+        Arrives in {chosen?.transit}. Shipping: {chosen?.price}
+      </span>
+    </Stack>
+  );
+}
+```
+
+### defaults.tsx
+
+Example
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import {
+  Select,
+  SelectContent,
+  SelectDefaultsProvider,
+  SelectItem,
+  type SelectOption,
+  SelectTrigger,
+  SelectValue,
+} from '@slotted/react/select';
+import { Stack } from '@slotted/react/stack';
+
+const OWNERS: SelectOption[] = [
+  { value: 'avery', label: 'Avery Collins' },
+  { value: 'kenji', label: 'Kenji Watanabe' },
+  { value: 'lucia', label: 'Lucía Fernández' },
+];
+
+const SEGMENTS: SelectOption[] = [
+  { value: 'enterprise', label: 'Enterprise' },
+  { value: 'wholesale', label: 'Wholesale' },
+  { value: 'retail', label: 'Retail' },
+];
+
+export default function SelectDefaults() {
+  return (
+    <SelectDefaultsProvider size="sm" variant="subtle" clearable>
+      <Stack gap={4}>
+        <Field>
+          <FieldLabel>Account owner</FieldLabel>
+          <Select defaultValue="lucia" items={OWNERS}>
+            <SelectTrigger>
+              <SelectValue placeholder="Any owner" />
+            </SelectTrigger>
+            <SelectContent>
+              {OWNERS.map((owner) => (
+                <SelectItem key={owner.value} value={owner.value}>
+                  {owner.label}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+        </Field>
+        <Field>
+          <FieldLabel>Segment</FieldLabel>
+          <Select defaultValue="wholesale" items={SEGMENTS}>
+            <SelectTrigger>
+              <SelectValue placeholder="Any segment" />
+            </SelectTrigger>
+            <SelectContent>
+              {SEGMENTS.map((segment) => (
+                <SelectItem key={segment.value} value={segment.value}>
+                  {segment.label}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+        </Field>
+      </Stack>
+    </SelectDefaultsProvider>
+  );
+}
+```
+
+### descriptions.tsx
+
+Example
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import { Glyph, type GlyphName, Icon } from '@slotted/react/icon';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  type SelectOption,
+  SelectTrigger,
+  SelectValue,
+} from '@slotted/react/select';
+
+const FORMATS: (SelectOption & { icon: GlyphName; description: string })[] = [
+  {
+    value: 'csv',
+    label: 'CSV',
+    icon: 'file-spreadsheet',
+    description: 'Opens in Excel and Google Sheets.',
+  },
+  {
+    value: 'pdf',
+    label: 'PDF',
+    icon: 'file-text',
+    description: 'Paginated, with the company letterhead.',
+  },
+  {
+    value: 'json',
+    label: 'JSON',
+    icon: 'file',
+    description: 'For an import into another system.',
+  },
+];
+
+export default function SelectDescriptions() {
+  return (
+    <Field>
+      <FieldLabel>Export format</FieldLabel>
+      <Select defaultValue="csv" items={FORMATS}>
+        <SelectTrigger>
+          <SelectValue />
+        </SelectTrigger>
+        <SelectContent>
+          {FORMATS.map((format) => (
+            <SelectItem
+              key={format.value}
+              value={format.value}
+              description={format.description}
+              icon={
+                <Icon>
+                  <Glyph name={format.icon} />
+                </Icon>
+              }
+            >
+              {format.label}
+            </SelectItem>
+          ))}
+        </SelectContent>
+      </Select>
+    </Field>
+  );
+}
+```
+
+### disabled-options.tsx
+
+Example
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@slotted/react/select';
+
+const CARRIERS: { value: string; label: string; disabled?: boolean; description?: string }[] = [
+  { value: 'ups', label: 'UPS Ground' },
+  { value: 'fedex', label: 'FedEx Ground' },
+  {
+    value: 'dhl',
+    label: 'DHL Express',
+    disabled: true,
+    description: 'Account on hold until invoice INV-21462 is paid.',
+  },
+  { value: 'usps', label: 'USPS Priority Mail' },
+];
+
+export default function SelectDisabledOptions() {
+  return (
+    <Field>
+      <FieldLabel>Carrier</FieldLabel>
+      <Select>
+        <SelectTrigger>
+          <SelectValue placeholder="Choose a carrier" />
+        </SelectTrigger>
+        <SelectContent>
+          {CARRIERS.map((carrier) => (
+            <SelectItem
+              key={carrier.value}
+              value={carrier.value}
+              disabled={carrier.disabled ?? false}
+              description={carrier.description}
+            >
+              {carrier.label}
+            </SelectItem>
+          ))}
+        </SelectContent>
+      </Select>
+    </Field>
+  );
+}
+```
+
+### empty.tsx
+
+Example
+
+```tsx
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import { Select, SelectContent, SelectTrigger, SelectValue } from '@slotted/react/select';
+
+export default function SelectEmpty() {
+  return (
+    <Field>
+      <FieldLabel>Purchase order to receive</FieldLabel>
+      <Select messages={{ empty: 'No open purchase orders for Kiln & Co.' }}>
+        <SelectTrigger>
+          <SelectValue placeholder="Choose a purchase order" />
+        </SelectTrigger>
+        <SelectContent />
+      </Select>
+      <FieldDescription>Only orders awaiting receipt are listed.</FieldDescription>
+    </Field>
+  );
+}
+```
+
+### loading.tsx
+
+Example
+
+```tsx
+import { useState } from 'react';
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  type SelectOption,
+  SelectTrigger,
+  SelectValue,
+} from '@slotted/react/select';
+
+const SLOTS: SelectOption[] = [
+  { value: 'thu-am', label: 'Thursday, 8:00–12:00' },
+  { value: 'thu-pm', label: 'Thursday, 13:00–17:00' },
+  { value: 'fri-am', label: 'Friday, 8:00–12:00' },
+];
+
+/** Stands in for a request to the carrier's pickup API. */
+const fetchSlots = () =>
+  new Promise<SelectOption[]>((resolve) => setTimeout(() => resolve(SLOTS), 1500));
+
+export default function SelectLoading() {
+  const [slots, setSlots] = useState<SelectOption[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [loaded, setLoaded] = useState(false);
+
+  const load = async (open: boolean) => {
+    if (!open || loaded || loading) return;
+    setLoading(true);
+    setSlots(await fetchSlots());
+    setLoading(false);
+    setLoaded(true);
+  };
+
+  return (
+    <Field>
+      <FieldLabel>Pickup slot</FieldLabel>
+      <Select
+        loading={loading}
+        items={slots}
+        messages={{ loading: 'Fetching pickup slots…' }}
+        onOpenChange={(open) => void load(open)}
+      >
+        <SelectTrigger>
+          <SelectValue placeholder="Choose a slot" />
+        </SelectTrigger>
+        <SelectContent>
+          {slots.map((slot) => (
+            <SelectItem key={slot.value} value={slot.value}>
+              {slot.label}
+            </SelectItem>
+          ))}
+        </SelectContent>
+      </Select>
+      <FieldDescription>Slots load from the carrier when the list opens.</FieldDescription>
+    </Field>
+  );
+}
+```
+
+### long-labels.tsx
+
+Example
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  type SelectOption,
+  SelectTrigger,
+  SelectValue,
+} from '@slotted/react/select';
+
+const LISTINGS: SelectOption[] = [
+  {
+    value: 'mug-sage',
+    label: 'Stoneware mug, 12 oz, sage glaze, case of 24, for the autumn wholesale catalogue',
+  },
+  { value: 'mug-sku', label: 'SKU-NW-STONEWARE-MUG-12OZ-SAGE-GLAZE-CASE24-WHOLESALE' },
+  { value: 'tumbler', label: 'Glass tumbler, 8 oz' },
+];
+
+export default function SelectLongLabels() {
+  return (
+    <Field>
+      <FieldLabel>Catalogue listing</FieldLabel>
+      <Select defaultValue="mug-sage" items={LISTINGS}>
+        <SelectTrigger>
+          <SelectValue />
+        </SelectTrigger>
+        <SelectContent>
+          {LISTINGS.map((listing) => (
+            <SelectItem key={listing.value} value={listing.value}>
+              {listing.label}
+            </SelectItem>
+          ))}
+        </SelectContent>
+      </Select>
+    </Field>
+  );
+}
+```
+
+### narrow.tsx
+
+Example
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  type SelectOption,
+  SelectTrigger,
+  SelectValue,
+} from '@slotted/react/select';
+import { Stack } from '@slotted/react/stack';
+
+const STATUSES: SelectOption[] = [
+  { value: 'open', label: 'Open' },
+  { value: 'on-hold', label: 'On hold' },
+  { value: 'shipped', label: 'Shipped' },
+];
+
+const CHANNELS: SelectOption[] = [
+  { value: 'web', label: 'Web store' },
+  { value: 'marketplace', label: 'Marketplace' },
+  { value: 'wholesale', label: 'Wholesale' },
+  { value: 'phone', label: 'Phone orders' },
+];
+
+const WAREHOUSES: SelectOption[] = [
+  { value: 'RNO', label: 'Reno, NV' },
+  { value: 'CMH', label: 'Columbus, OH' },
+  { value: 'SAV', label: 'Savannah, GA' },
+];
+
+export default function SelectNarrow() {
+  return (
+    <Stack gap={4} style={{ inlineSize: '7rem' }}>
+      <Field>
+        <FieldLabel>Status</FieldLabel>
+        <Select size="sm" defaultValue="on-hold" items={STATUSES}>
+          <SelectTrigger>
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            {STATUSES.map((status) => (
+              <SelectItem key={status.value} value={status.value}>
+                {status.label}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </Field>
+      <Field>
+        <FieldLabel>Channels</FieldLabel>
+        <Select
+          size="sm"
+          multiple
+          defaultValue={['web', 'marketplace', 'wholesale']}
+          items={CHANNELS}
+        >
+          <SelectTrigger>
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            {CHANNELS.map((channel) => (
+              <SelectItem key={channel.value} value={channel.value}>
+                {channel.label}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </Field>
+      <Field>
+        <FieldLabel>Warehouse</FieldLabel>
+        <Select size="sm" width="content" defaultValue="CMH" items={WAREHOUSES}>
+          <SelectTrigger>
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            {WAREHOUSES.map((warehouse) => (
+              <SelectItem key={warehouse.value} value={warehouse.value}>
+                {warehouse.label}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### status-filter.tsx
+
+Example
+
+```tsx
+import { useState } from 'react';
+import { Glyph, type GlyphName, Icon } from '@slotted/react/icon';
+import { Inline } from '@slotted/react/inline';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  type SelectOption,
+  SelectSeparator,
+  SelectTrigger,
+  SelectValue,
+} from '@slotted/react/select';
+import { Stack } from '@slotted/react/stack';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableColumnHeader,
+  TableContent,
+  TableHead,
+  TableRow,
+  TableRowHeader,
+} from '@slotted/react/table';
+import { Text } from '@slotted/react/typography';
+
+const ORDERS = [
+  { id: 'SO-10482', customer: 'Harbor & Pine', status: 'open', total: '$1,240.00' },
+  { id: 'SO-10483', customer: 'Brightline Studio', status: 'on-hold', total: '$318.50' },
+  { id: 'SO-10484', customer: 'Northgate Labs', status: 'shipped', total: '$2,906.10' },
+  { id: 'SO-10485', customer: 'Verde Kitchen', status: 'delayed', total: '$86.00' },
+  { id: 'SO-10486', customer: 'Quill & Co.', status: 'shipped', total: '$540.25' },
+  { id: 'SO-10487', customer: 'Atlas Freight', status: 'open', total: '$1,912.00' },
+];
+
+const STATUSES: (SelectOption & { icon: GlyphName })[] = [
+  { value: 'open', label: 'Open', icon: 'circle' },
+  { value: 'on-hold', label: 'On hold', icon: 'clock' },
+  { value: 'delayed', label: 'Delayed', icon: 'triangle-alert' },
+  { value: 'shipped', label: 'Shipped', icon: 'circle-check' },
+];
+
+const ALL: SelectOption = { value: 'all', label: 'All statuses' };
+const OPTIONS = [ALL, ...STATUSES];
+
+const labelOf = (status: string) => STATUSES.find((option) => option.value === status)?.label;
+
+export default function SelectStatusFilter() {
+  const [status, setStatus] = useState('all');
+  const rows = status === 'all' ? ORDERS : ORDERS.filter((order) => order.status === status);
+
+  return (
+    <Stack gap={3}>
+      <Inline gap={3} justify="between" align="center">
+        <Text size="sm" tone="muted">
+          {rows.length} of {ORDERS.length} orders
+        </Text>
+        <Select
+          size="sm"
+          align="end"
+          fullWidth={false}
+          value={status}
+          items={OPTIONS}
+          onValueChange={(next) => setStatus(typeof next === 'string' ? next : 'all')}
+        >
+          <SelectTrigger aria-label="Filter by status">
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectItem value={ALL.value}>{ALL.label}</SelectItem>
+            <SelectSeparator />
+            {STATUSES.map((option) => (
+              <SelectItem
+                key={option.value}
+                value={option.value}
+                icon={
+                  <Icon>
+                    <Glyph name={option.icon} />
+                  </Icon>
+                }
+              >
+                {option.label}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </Inline>
+      <Table columns={4}>
+        <TableContent aria-label="Orders">
+          <TableHead>
+            <TableRow>
+              <TableColumnHeader>Order</TableColumnHeader>
+              <TableColumnHeader>Customer</TableColumnHeader>
+              <TableColumnHeader>Status</TableColumnHeader>
+              <TableColumnHeader numeric>Total</TableColumnHeader>
+            </TableRow>
+          </TableHead>
+          <TableBody>
+            {rows.map((order) => (
+              <TableRow key={order.id} value={order.id}>
+                <TableRowHeader>{order.id}</TableRowHeader>
+                <TableCell>{order.customer}</TableCell>
+                <TableCell>{labelOf(order.status)}</TableCell>
+                <TableCell numeric>{order.total}</TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </TableContent>
+      </Table>
+    </Stack>
+  );
+}
+```