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

package/dist/docs/combobox.examples.md

@@ -0,0 +1,1739 @@
+<!-- index: ./index.md -->
+# combobox
+
+`data-ui="combobox"` · Text input that filters a list of options.
+
+## Examples
+
+### Playground
+
+One combobox with every axis on it, driven by the controls under the canvas. Type into it and watch the list, the marks and the count answer together.
+
+Excerpt — not a complete module
+
+```tsx
+<Combobox>
+  <ComboboxInput aria-label="Fruit" placeholder="Search fruit" />
+  <ComboboxContent>
+    <ComboboxItem value="blueberry">Blueberry</ComboboxItem>
+    <ComboboxItem value="raspberry">Raspberry</ComboboxItem>
+  </ComboboxContent>
+</Combobox>;
+```
+
+### Filtering, and the mark
+
+The default comparison is locale-sensitive, so resume finds Resumé — and the mark shows the span the collator matched rather than a naive substring that would disagree with it.
+
+Example
+
+```tsx
+import { Combobox, ComboboxContent, ComboboxInput, ComboboxItem } from '@slotted/react/combobox';
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+
+const CITIES = [
+  'São Paulo',
+  'Zürich',
+  'Montréal',
+  'Kraków',
+  'Malmö',
+  'Querétaro',
+  'Reykjavík',
+  'Düsseldorf',
+];
+
+export default function ComboboxFiltering() {
+  return (
+    <Field>
+      <FieldLabel>Destination city</FieldLabel>
+      <Combobox>
+        <ComboboxInput placeholder="Try “sao” or “zurich”" />
+        <ComboboxContent>
+          {CITIES.map((city) => (
+            <ComboboxItem key={city} value={city}>
+              {city}
+            </ComboboxItem>
+          ))}
+        </ComboboxContent>
+      </Combobox>
+      <FieldDescription>Accents and case are ignored when matching.</FieldDescription>
+    </Field>
+  );
+}
+```
+
+### Autocomplete
+
+The pattern’s own three values. both writes the rest of the first match into the field as a selected range, so the next character replaces it and Backspace withdraws it.
+
+Excerpt — not a complete module
+
+```tsx
+<Combobox autocomplete="none">…</Combobox>;
+<Combobox autocomplete="list">…</Combobox>;
+<Combobox autocomplete="both">…</Combobox>;
+```
+
+### A value that is not on the list
+
+With allowsCustomValue the typed text commits as the value. Without it, Enter puts the text back to the committed option’s label — the pattern’s own "reverts".
+
+Example
+
+```tsx
+import { useState } from 'react';
+import { Combobox, ComboboxContent, ComboboxInput, ComboboxItem } from '@slotted/react/combobox';
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+
+const BOXES = [
+  { id: 'small', label: 'Small · 20 × 15 × 10 cm' },
+  { id: 'medium', label: 'Medium · 35 × 25 × 15 cm' },
+  { id: 'large', label: 'Large · 50 × 40 × 30 cm' },
+];
+
+export default function ComboboxCustomValue() {
+  const [value, setValue] = useState<string | null>(null);
+
+  return (
+    <Field>
+      <FieldLabel>Box size</FieldLabel>
+      <Combobox allowsCustomValue value={value} onValueChange={setValue}>
+        <ComboboxInput placeholder="Pick a box or type dimensions" />
+        <ComboboxContent>
+          {BOXES.map((box) => (
+            <ComboboxItem key={box.id} value={box.id}>
+              {box.label}
+            </ComboboxItem>
+          ))}
+        </ComboboxContent>
+      </Combobox>
+      <FieldDescription>Value: {value ?? 'none'}</FieldDescription>
+    </Field>
+  );
+}
+```
+
+### Adding a value the list does not hold
+
+With onCreate, the last option offers to add what was typed once nothing matched. It is an option — ArrowDown reaches it, Enter takes it — and taking it reports the query and selects nothing: the collection is the consumer’s, and only it knows whether this one can grow.
+
+Excerpt — not a complete module
+
+```tsx
+<Combobox onCreate={(query) => add(query)}>…</Combobox>;
+```
+
+### Asynchronous results
+
+Debounce the fetch, not the combobox: a component that delayed its own request would delay a controlled consumer’s re-render and drop characters between them.
+
+Excerpt — not a complete module
+
+```tsx
+const [query, setQuery] = useState('');
+const deferred = useDeferredValue(query);
+const { data, isPending } = useQuery({ queryKey: ['people', deferred], queryFn: search });
+
+<Combobox
+  filter={null}
+  inputValue={query}
+  loading={isPending}
+  onInputValueChange={setQuery}
+  onLoadMore={fetchNextPage}
+>
+  …
+</Combobox>;
+```
+
+### Groups
+
+Two named groups. A group whose every option was filtered away disappears with them, so a heading never claims a category matched when none did.
+
+Example
+
+```tsx
+import {
+  Combobox,
+  ComboboxContent,
+  ComboboxGroup,
+  ComboboxInput,
+  ComboboxItem,
+} from '@slotted/react/combobox';
+import { Field, FieldLabel } from '@slotted/react/field';
+
+const CATALOG = [
+  {
+    category: 'Kitchen',
+    products: [
+      { sku: 'KIT-1042', name: 'Cast-iron skillet' },
+      { sku: 'KIT-1043', name: 'Stoneware mug' },
+      { sku: 'KIT-1051', name: 'Pour-over kettle' },
+    ],
+  },
+  {
+    category: 'Bags',
+    products: [
+      { sku: 'BAG-2010', name: 'Canvas tote' },
+      { sku: 'BAG-2014', name: 'Trail daypack' },
+      { sku: 'BAG-2019', name: 'Weekender bag' },
+    ],
+  },
+  {
+    category: 'Stationery',
+    products: [
+      { sku: 'STA-3002', name: 'Field notebook' },
+      { sku: 'STA-3007', name: 'Fountain pen' },
+      { sku: 'STA-3011', name: 'Brass stapler' },
+    ],
+  },
+];
+
+export default function ComboboxGroups() {
+  return (
+    <Field>
+      <FieldLabel>Product</FieldLabel>
+      <Combobox>
+        <ComboboxInput placeholder="Search the catalog" />
+        <ComboboxContent>
+          {CATALOG.map((group) => (
+            <ComboboxGroup key={group.category} label={group.category}>
+              {group.products.map((product) => (
+                <ComboboxItem key={product.sku} value={product.sku}>
+                  {product.name}
+                </ComboboxItem>
+              ))}
+            </ComboboxGroup>
+          ))}
+        </ComboboxContent>
+      </Combobox>
+    </Field>
+  );
+}
+```
+
+### Clearable
+
+One press takes both contracts back — the text and the chosen key — and focus returns to the field rather than to the document.
+
+Example
+
+```tsx
+import { Combobox, ComboboxContent, ComboboxInput, ComboboxItem } from '@slotted/react/combobox';
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import { Stack } from '@slotted/react/stack';
+
+export default function ComboboxClearable() {
+  return (
+    <Stack gap={5}>
+      <Field>
+        <FieldLabel>Default warehouse</FieldLabel>
+        <Combobox defaultInputValue="Columbus, OH" defaultValue="CMH">
+          <ComboboxInput />
+          <ComboboxContent>
+            <ComboboxItem value="RNO">Reno, NV</ComboboxItem>
+            <ComboboxItem value="CMH">Columbus, OH</ComboboxItem>
+            <ComboboxItem value="SAV">Savannah, GA</ComboboxItem>
+          </ComboboxContent>
+        </Combobox>
+        <FieldDescription>Optional. Clearing it routes orders by distance.</FieldDescription>
+      </Field>
+      <Field>
+        <FieldLabel>Payment terms</FieldLabel>
+        <Combobox clearable={false} defaultInputValue="Net 30" defaultValue="net-30">
+          <ComboboxInput />
+          <ComboboxContent>
+            <ComboboxItem value="prepaid">Prepaid</ComboboxItem>
+            <ComboboxItem value="net-30">Net 30</ComboboxItem>
+            <ComboboxItem value="net-45">Net 45</ComboboxItem>
+          </ComboboxContent>
+        </Combobox>
+        <FieldDescription>Every account has terms, so there is nothing to clear.</FieldDescription>
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### Sizes
+
+Three steps, every one reading control geometry — so a combobox beside a text field of the same size is the same height to the pixel.
+
+Example
+
+```tsx
+import {
+  Combobox,
+  ComboboxContent,
+  ComboboxInput,
+  ComboboxItem,
+  type ComboboxSize,
+} from '@slotted/react/combobox';
+import { Field, FieldLabel } from '@slotted/react/field';
+import { Stack } from '@slotted/react/stack';
+
+const SIZES: { size: ComboboxSize; label: string }[] = [
+  { size: 'sm', label: 'Small' },
+  { size: 'md', label: 'Medium' },
+  { size: 'lg', label: 'Large' },
+];
+
+const WAREHOUSES = ['Reno, NV', 'Columbus, OH', 'Savannah, GA'];
+
+export default function ComboboxSizes() {
+  return (
+    <Stack gap={5}>
+      {SIZES.map((step) => (
+        <Field key={step.size}>
+          <FieldLabel>{step.label}</FieldLabel>
+          <Combobox size={step.size} defaultInputValue="Reno, NV" defaultValue="Reno, NV">
+            <ComboboxInput />
+            <ComboboxContent>
+              {WAREHOUSES.map((warehouse) => (
+                <ComboboxItem key={warehouse} value={warehouse}>
+                  {warehouse}
+                </ComboboxItem>
+              ))}
+            </ComboboxContent>
+          </Combobox>
+        </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 {
+  Combobox,
+  ComboboxContent,
+  ComboboxInput,
+  ComboboxItem,
+  type ComboboxVariant,
+} from '@slotted/react/combobox';
+import { Field, FieldLabel } from '@slotted/react/field';
+import { Stack } from '@slotted/react/stack';
+
+const VARIANTS: { variant: ComboboxVariant; label: string }[] = [
+  { variant: 'outline', label: 'Outline' },
+  { variant: 'subtle', label: 'Subtle' },
+  { variant: 'plain', label: 'Plain' },
+];
+
+const WAREHOUSES = ['Reno, NV', 'Columbus, OH', 'Savannah, GA'];
+
+export default function ComboboxVariants() {
+  return (
+    <Stack gap={5}>
+      {VARIANTS.map((step) => (
+        <Field key={step.variant}>
+          <FieldLabel>{step.label}</FieldLabel>
+          <Combobox variant={step.variant}>
+            <ComboboxInput placeholder="Search warehouses" />
+            <ComboboxContent>
+              {WAREHOUSES.map((warehouse) => (
+                <ComboboxItem key={warehouse} value={warehouse}>
+                  {warehouse}
+                </ComboboxItem>
+              ))}
+            </ComboboxContent>
+          </Combobox>
+        </Field>
+      ))}
+    </Stack>
+  );
+}
+```
+
+### States
+
+Required, invalid, read-only and disabled. Read-only keeps the caret, the selection and the copy, and withholds only the popup, which the combobox decides because the pattern has no read-only state.
+
+Example
+
+```tsx
+import { Combobox, ComboboxContent, ComboboxInput, ComboboxItem } from '@slotted/react/combobox';
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import { Stack } from '@slotted/react/stack';
+
+export default function ComboboxStates() {
+  return (
+    <Stack gap={5}>
+      <Field disabled>
+        <FieldLabel>Warehouse</FieldLabel>
+        <Combobox defaultInputValue="Reno, NV" defaultValue="RNO">
+          <ComboboxInput />
+          <ComboboxContent>
+            <ComboboxItem value="RNO">Reno, NV</ComboboxItem>
+            <ComboboxItem value="CMH">Columbus, OH</ComboboxItem>
+          </ComboboxContent>
+        </Combobox>
+        <FieldDescription>Locked while the transfer is in transit.</FieldDescription>
+      </Field>
+      <Field readOnly>
+        <FieldLabel>Billing entity</FieldLabel>
+        <Combobox defaultInputValue="Northwind Trading Co." defaultValue="northwind-us">
+          <ComboboxInput />
+          <ComboboxContent>
+            <ComboboxItem value="northwind-us">Northwind Trading Co.</ComboboxItem>
+            <ComboboxItem value="northwind-eu">Northwind Europe B.V.</ComboboxItem>
+          </ComboboxContent>
+        </Combobox>
+        <FieldDescription>
+          Set by the contract. The text can still be selected and copied.
+        </FieldDescription>
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### Nothing matched, and still travelling
+
+A query with no answers opens onto a sentence. A query whose answer is in flight keeps the same measure, so nothing jumps when the results land.
+
+Excerpt — not a complete module
+
+```tsx
+<ComboboxContent empty="Try a different spelling" status="Searching…" />;
+```
+
+### Long, translated and unbroken content
+
+A translated label, an unbroken identifier and two hundred options. The label clamps at two lines with the whole string in the DOM, and the mark sits inside the token that broke.
+
+Excerpt — not a complete module
+
+```tsx
+<ComboboxItem textValue="urn:acme:catalogue:9f2c41ab" value="urn">
+  urn:acme:catalogue:9f2c41ab8de07c5511903fbe
+</ComboboxItem>;
+```
+
+### Keyboard
+
+The arrows and the page keys move the highlight without moving the caret; Home, End, Backspace and Delete are never intercepted, which the pattern asks for by name.
+
+Excerpt — not a complete module
+
+```tsx
+<Combobox autoHighlight={false} loop={false} openOn="input">
+  …
+</Combobox>;
+```
+
+### In a form
+
+Inside a field, with a label, a description and an error. name renders a hidden input carrying the chosen key — never the typed text, which is the other contract.
+
+Example
+
+```tsx
+import { useState } from 'react';
+import type { SubmitEvent } from 'react';
+import { Button } from '@slotted/react/button';
+import { Combobox, ComboboxContent, ComboboxInput, ComboboxItem } from '@slotted/react/combobox';
+import { Field, FieldError, FieldLabel } from '@slotted/react/field';
+import { Inline } from '@slotted/react/inline';
+import { Stack } from '@slotted/react/stack';
+import { Text } from '@slotted/react/typography';
+
+const WAREHOUSES = [
+  { code: 'RNO', city: 'Reno, NV' },
+  { code: 'CMH', city: 'Columbus, OH' },
+  { code: 'SAV', city: 'Savannah, GA' },
+];
+
+export default function ComboboxForm() {
+  const [missing, setMissing] = useState(false);
+  const [submitted, setSubmitted] = useState<string | null>(null);
+
+  const submit = (event: SubmitEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const warehouse = new FormData(event.currentTarget).get('warehouse');
+    setMissing(!warehouse);
+    setSubmitted(warehouse ? `warehouse=${String(warehouse)}` : null);
+  };
+
+  return (
+    <form noValidate onSubmit={submit}>
+      <Stack gap={4}>
+        <Field required invalid={missing}>
+          <FieldLabel>Fulfil from</FieldLabel>
+          <Combobox name="warehouse" onValueChange={(next) => next && setMissing(false)}>
+            <ComboboxInput placeholder="Search warehouses" />
+            <ComboboxContent>
+              {WAREHOUSES.map((warehouse) => (
+                <ComboboxItem key={warehouse.code} value={warehouse.code}>
+                  {warehouse.city}
+                </ComboboxItem>
+              ))}
+            </ComboboxContent>
+          </Combobox>
+          {missing && <FieldError>Choose the warehouse that ships this order.</FieldError>}
+        </Field>
+        <Inline gap={3} align="center">
+          <Button type="submit">Create transfer</Button>
+          {submitted && (
+            <Text size="sm" tone="muted">
+              Submitted {submitted}
+            </Text>
+          )}
+        </Inline>
+      </Stack>
+    </form>
+  );
+}
+```
+
+### Composition
+
+Defaults set once for an application, the words from the language in force, the frame replaced through render, and the imperative handle for what a consumer cannot say declaratively.
+
+Excerpt — not a complete module
+
+```tsx
+<ComboboxDefaultsProvider size="sm">
+  <Combobox ref={handle}>
+    <ComboboxInput render={(props) => <label {...props} />} />…
+  </Combobox>
+</ComboboxDefaultsProvider>;
+```
+
+### assignee-picker.tsx
+
+Example
+
+```tsx
+import { Avatar } from '@slotted/react/avatar';
+import { Combobox, ComboboxContent, ComboboxInput, ComboboxItem } from '@slotted/react/combobox';
+import { Field, FieldLabel } from '@slotted/react/field';
+
+const PEOPLE = [
+  { id: 'avery', name: 'Avery Collins', role: 'Fulfilment lead', away: false },
+  { id: 'kenji', name: 'Kenji Watanabe', role: 'Customer care', away: false },
+  { id: 'lucia', name: 'Lucía Fernández', role: 'Account manager', away: false },
+  { id: 'ruth', name: 'Ruth Adeyemi', role: 'On leave until 14 October', away: true },
+  { id: 'tomasz', name: 'Tomasz Nowak', role: 'Warehouse supervisor, Reno', away: false },
+  { id: 'omar', name: 'Omar Haddad', role: 'Finance', away: false },
+];
+
+export default function ComboboxAssigneePicker() {
+  return (
+    <Field>
+      <FieldLabel>Assignee</FieldLabel>
+      <Combobox autoHighlight>
+        <ComboboxInput placeholder="Assign to…" />
+        <ComboboxContent>
+          {PEOPLE.map((person) => (
+            <ComboboxItem
+              key={person.id}
+              value={person.id}
+              description={person.role}
+              disabled={person.away}
+              icon={<Avatar name={person.name} size="xs" decorative />}
+            >
+              {person.name}
+            </ComboboxItem>
+          ))}
+        </ComboboxContent>
+      </Combobox>
+    </Field>
+  );
+}
+```
+
+### async-search.tsx
+
+Example
+
+```tsx
+import { useEffect, useState } from 'react';
+import { Combobox, ComboboxContent, ComboboxInput, ComboboxItem } from '@slotted/react/combobox';
+import { Field, FieldLabel } from '@slotted/react/field';
+
+interface Customer {
+  id: string;
+  name: string;
+  city: string;
+}
+
+const DIRECTORY: Customer[] = [
+  { id: 'brightline', name: 'Brightline Studio', city: 'Portland, OR' },
+  { id: 'harbor-pine', name: 'Harbor & Pine', city: 'Seattle, WA' },
+  { id: 'northgate', name: 'Northgate Labs', city: 'Austin, TX' },
+  { id: 'quill', name: 'Quill & Co.', city: 'Brooklyn, NY' },
+  { id: 'solstice', name: 'Solstice Outdoor', city: 'Boulder, CO' },
+  { id: 'verde', name: 'Verde Kitchen', city: 'Oakland, CA' },
+  { id: 'atlas', name: 'Atlas Freight', city: 'Memphis, TN' },
+  { id: 'juniper', name: 'Juniper Health', city: 'Minneapolis, MN' },
+  { id: 'kestrel', name: 'Kestrel Robotics', city: 'Pittsburgh, PA' },
+  { id: 'larkspur', name: 'Larkspur Books', city: 'Asheville, NC' },
+  { id: 'meridian', name: 'Meridian Hotels', city: 'Chicago, IL' },
+  { id: 'oakline', name: 'Oakline Furniture', city: 'Grand Rapids, MI' },
+  { id: 'pelican', name: 'Pelican Coffee', city: 'Tampa, FL' },
+  { id: 'saltmarsh', name: 'Saltmarsh Dairy', city: 'Burlington, VT' },
+  { id: 'tidewater', name: 'Tidewater Supply', city: 'Norfolk, VA' },
+];
+
+/** Stands in for a request to the server, which answers after 600 ms. */
+function searchCustomers(query: string): Promise<Customer[]> {
+  const needle = query.trim().toLowerCase();
+  const found = DIRECTORY.filter((customer) => customer.name.toLowerCase().includes(needle));
+  return new Promise((resolve) => setTimeout(() => resolve(found), 600));
+}
+
+export default function ComboboxAsyncSearch() {
+  const [query, setQuery] = useState('');
+  const [results, setResults] = useState<Customer[]>([]);
+  const [loading, setLoading] = useState(false);
+
+  useEffect(() => {
+    if (query.trim() === '') {
+      setResults([]);
+      setLoading(false);
+      return;
+    }
+    let current = true;
+    setLoading(true);
+    const debounce = setTimeout(() => {
+      void searchCustomers(query).then((found) => {
+        if (!current) return;
+        setResults(found);
+        setLoading(false);
+      });
+    }, 250);
+    return () => {
+      current = false;
+      clearTimeout(debounce);
+    };
+  }, [query]);
+
+  return (
+    <Field>
+      <FieldLabel>Customer</FieldLabel>
+      <Combobox
+        filter={null}
+        inputValue={query}
+        onInputValueChange={setQuery}
+        loading={loading}
+        messages={{
+          empty: query.trim() === '' ? 'Type a name to search.' : 'No customer by that name.',
+        }}
+      >
+        <ComboboxInput placeholder="Search 15 customers" />
+        <ComboboxContent>
+          {results.map((customer) => (
+            <ComboboxItem key={customer.id} value={customer.id} description={customer.city}>
+              {customer.name}
+            </ComboboxItem>
+          ))}
+        </ComboboxContent>
+      </Combobox>
+    </Field>
+  );
+}
+```
+
+### auto-highlight.tsx
+
+Example
+
+```tsx
+import { Combobox, ComboboxContent, ComboboxInput, ComboboxItem } from '@slotted/react/combobox';
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+
+const UNITS = ['Each', 'Case of 6', 'Case of 12', 'Pallet', 'Kilogram', 'Pound', 'Meter', 'Liter'];
+
+export default function ComboboxAutoHighlight() {
+  return (
+    <Field>
+      <FieldLabel>Unit of measure</FieldLabel>
+      <Combobox autoHighlight loop>
+        <ComboboxInput placeholder="Type “ca” and press Enter" />
+        <ComboboxContent>
+          {UNITS.map((unit) => (
+            <ComboboxItem key={unit} value={unit}>
+              {unit}
+            </ComboboxItem>
+          ))}
+        </ComboboxContent>
+      </Combobox>
+      <FieldDescription>The first match is highlighted, so Enter takes it.</FieldDescription>
+    </Field>
+  );
+}
+```
+
+### controlled.tsx
+
+Example
+
+```tsx
+import { useState } from 'react';
+import { Button } from '@slotted/react/button';
+import { Combobox, ComboboxContent, ComboboxInput, ComboboxItem } from '@slotted/react/combobox';
+import { Field, FieldLabel } from '@slotted/react/field';
+import { Inline } from '@slotted/react/inline';
+import { Stack } from '@slotted/react/stack';
+import { Text } from '@slotted/react/typography';
+
+const PEOPLE = [
+  { id: 'avery', name: 'Avery Collins' },
+  { id: 'kenji', name: 'Kenji Watanabe' },
+  { id: 'lucia', name: 'Lucía Fernández' },
+  { id: 'ruth', name: 'Ruth Adeyemi' },
+  { id: 'tomasz', name: 'Tomasz Nowak' },
+];
+
+export default function ComboboxControlled() {
+  const [text, setText] = useState('');
+  const [value, setValue] = useState<string | null>(null);
+
+  const assignToMe = () => {
+    setValue('ruth');
+    setText('Ruth Adeyemi');
+  };
+
+  return (
+    <Stack gap={4}>
+      <Field>
+        <FieldLabel>Reviewer</FieldLabel>
+        <Combobox
+          inputValue={text}
+          onInputValueChange={setText}
+          value={value}
+          onValueChange={setValue}
+        >
+          <ComboboxInput placeholder="Search people" />
+          <ComboboxContent>
+            {PEOPLE.map((person) => (
+              <ComboboxItem key={person.id} value={person.id}>
+                {person.name}
+              </ComboboxItem>
+            ))}
+          </ComboboxContent>
+        </Combobox>
+      </Field>
+      <Inline gap={3} align="center">
+        <Button size="sm" variant="outline" onClick={assignToMe}>
+          Assign to me
+        </Button>
+        <Text size="sm" tone="muted">
+          Text “{text}” · Value {value ?? 'none'}
+        </Text>
+      </Inline>
+    </Stack>
+  );
+}
+```
+
+### country-picker.tsx
+
+Example
+
+```tsx
+import {
+  Combobox,
+  ComboboxContent,
+  ComboboxGroup,
+  ComboboxInput,
+  ComboboxItem,
+} from '@slotted/react/combobox';
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+
+const REGIONS = [
+  {
+    region: 'Americas',
+    countries: [
+      { code: 'BR', name: 'Brazil', detail: 'BRL · +55' },
+      { code: 'CA', name: 'Canada', detail: 'CAD · +1' },
+      { code: 'MX', name: 'Mexico', detail: 'MXN · +52' },
+      { code: 'US', name: 'United States', detail: 'USD · +1' },
+    ],
+  },
+  {
+    region: 'Europe',
+    countries: [
+      { code: 'FR', name: 'France', detail: 'EUR · +33' },
+      { code: 'DE', name: 'Germany', detail: 'EUR · +49' },
+      { code: 'PL', name: 'Poland', detail: 'PLN · +48' },
+      { code: 'CH', name: 'Switzerland', detail: 'CHF · +41' },
+      { code: 'TR', name: 'Türkiye', detail: 'TRY · +90' },
+      { code: 'GB', name: 'United Kingdom', detail: 'GBP · +44' },
+    ],
+  },
+  {
+    region: 'Asia Pacific',
+    countries: [
+      { code: 'AU', name: 'Australia', detail: 'AUD · +61' },
+      { code: 'JP', name: 'Japan', detail: 'JPY · +81' },
+      { code: 'SG', name: 'Singapore', detail: 'SGD · +65' },
+      { code: 'VN', name: 'Việt Nam', detail: 'VND · +84' },
+    ],
+  },
+  {
+    region: 'Middle East and Africa',
+    countries: [
+      { code: 'CI', name: 'Côte d’Ivoire', detail: 'XOF · +225' },
+      { code: 'EG', name: 'Egypt', detail: 'EGP · +20' },
+      { code: 'KE', name: 'Kenya', detail: 'KES · +254' },
+      { code: 'AE', name: 'United Arab Emirates', detail: 'AED · +971' },
+    ],
+  },
+];
+
+export default function ComboboxCountryPicker() {
+  return (
+    <Field required>
+      <FieldLabel>Country or region</FieldLabel>
+      <Combobox autoHighlight name="country">
+        <ComboboxInput placeholder="Search countries" />
+        <ComboboxContent>
+          {REGIONS.map((group) => (
+            <ComboboxGroup key={group.region} label={group.region}>
+              {group.countries.map((country) => (
+                <ComboboxItem key={country.code} value={country.code} description={country.detail}>
+                  {country.name}
+                </ComboboxItem>
+              ))}
+            </ComboboxGroup>
+          ))}
+        </ComboboxContent>
+      </Combobox>
+      <FieldDescription>Sets the currency and the phone prefix on the invoice.</FieldDescription>
+    </Field>
+  );
+}
+```
+
+### creatable.tsx
+
+Example
+
+```tsx
+import { useState } from 'react';
+import { Combobox, ComboboxContent, ComboboxInput, ComboboxItem } from '@slotted/react/combobox';
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+
+const CATEGORIES = ['Apparel', 'Bags', 'Home', 'Kitchen', 'Stationery', 'Outdoor'];
+
+export default function ComboboxCreatable() {
+  const [categories, setCategories] = useState(CATEGORIES);
+  const [value, setValue] = useState<string | null>(null);
+
+  const create = (query: string) => {
+    setCategories((held) => [...held, query]);
+    setValue(query);
+  };
+
+  return (
+    <Field>
+      <FieldLabel>Category</FieldLabel>
+      <Combobox onCreate={create} value={value} onValueChange={setValue}>
+        <ComboboxInput placeholder="Type “Garden” to add it" />
+        <ComboboxContent>
+          {categories.map((category) => (
+            <ComboboxItem key={category} value={category}>
+              {category}
+            </ComboboxItem>
+          ))}
+        </ComboboxContent>
+      </Combobox>
+      <FieldDescription>{categories.length} categories</FieldDescription>
+    </Field>
+  );
+}
+```
+
+### custom-filter.tsx
+
+Example
+
+```tsx
+import { Combobox, ComboboxContent, ComboboxInput, ComboboxItem } from '@slotted/react/combobox';
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+
+const PRODUCTS = [
+  { sku: 'KIT-1042', name: 'Cast-iron skillet' },
+  { sku: 'KIT-1043', name: 'Stoneware mug' },
+  { sku: 'BAG-2010', name: 'Canvas tote' },
+  { sku: 'BAG-2014', name: 'Trail daypack' },
+  { sku: 'HOM-4010', name: 'Wool throw' },
+  { sku: 'HOM-4014', name: 'Brass desk lamp' },
+  { sku: 'STA-3010', name: 'Field notebook' },
+];
+
+const startsWith = (label: string, query: string) =>
+  label.toLowerCase().startsWith(query.toLowerCase());
+
+export default function ComboboxCustomFilter() {
+  return (
+    <Field>
+      <FieldLabel>SKU</FieldLabel>
+      <Combobox filter={startsWith}>
+        <ComboboxInput placeholder="KIT-, BAG-, HOM-…" />
+        <ComboboxContent>
+          {PRODUCTS.map((product) => (
+            <ComboboxItem key={product.sku} value={product.sku} description={product.name}>
+              {product.sku}
+            </ComboboxItem>
+          ))}
+        </ComboboxContent>
+      </Combobox>
+      <FieldDescription>
+        Codes match from the first character, so “10” finds nothing.
+      </FieldDescription>
+    </Field>
+  );
+}
+```
+
+### defaults.tsx
+
+Example
+
+```tsx
+import {
+  Combobox,
+  ComboboxContent,
+  ComboboxDefaultsProvider,
+  ComboboxInput,
+  ComboboxItem,
+} from '@slotted/react/combobox';
+import { Field, FieldLabel } from '@slotted/react/field';
+import { Stack } from '@slotted/react/stack';
+
+const WAREHOUSES = ['Reno, NV', 'Columbus, OH', 'Savannah, GA'];
+const CARRIERS = ['UPS', 'FedEx', 'DHL', 'USPS'];
+
+export default function ComboboxAppDefaults() {
+  return (
+    <ComboboxDefaultsProvider variant="subtle" autoHighlight>
+      <Stack gap={4}>
+        <Field>
+          <FieldLabel>Warehouse</FieldLabel>
+          <Combobox>
+            <ComboboxInput placeholder="Any warehouse" />
+            <ComboboxContent>
+              {WAREHOUSES.map((warehouse) => (
+                <ComboboxItem key={warehouse} value={warehouse}>
+                  {warehouse}
+                </ComboboxItem>
+              ))}
+            </ComboboxContent>
+          </Combobox>
+        </Field>
+        <Field>
+          <FieldLabel>Carrier</FieldLabel>
+          <Combobox>
+            <ComboboxInput placeholder="Any carrier" />
+            <ComboboxContent>
+              {CARRIERS.map((carrier) => (
+                <ComboboxItem key={carrier} value={carrier}>
+                  {carrier}
+                </ComboboxItem>
+              ))}
+            </ComboboxContent>
+          </Combobox>
+        </Field>
+      </Stack>
+    </ComboboxDefaultsProvider>
+  );
+}
+```
+
+### descriptions.tsx
+
+Example
+
+```tsx
+import { Combobox, ComboboxContent, ComboboxInput, ComboboxItem } from '@slotted/react/combobox';
+import { Field, FieldLabel } from '@slotted/react/field';
+
+const WAREHOUSES = [
+  { code: 'RNO', city: 'Reno, NV', detail: 'West · same-day cutoff 2:00 pm PT' },
+  { code: 'CMH', city: 'Columbus, OH', detail: 'Midwest · same-day cutoff 3:00 pm ET' },
+  { code: 'SAV', city: 'Savannah, GA', detail: 'Southeast · port of entry for ocean freight' },
+  { code: 'DFW', city: 'Dallas, TX', detail: 'South · opens November 2026' },
+];
+
+export default function ComboboxDescriptions() {
+  return (
+    <Field>
+      <FieldLabel>Ship from</FieldLabel>
+      <Combobox>
+        <ComboboxInput placeholder="Search warehouses" />
+        <ComboboxContent>
+          {WAREHOUSES.map((warehouse) => (
+            <ComboboxItem
+              key={warehouse.code}
+              value={warehouse.code}
+              description={warehouse.detail}
+            >
+              {warehouse.city}
+            </ComboboxItem>
+          ))}
+        </ComboboxContent>
+      </Combobox>
+    </Field>
+  );
+}
+```
+
+### disabled-options.tsx
+
+Example
+
+```tsx
+import { Combobox, ComboboxContent, ComboboxInput, ComboboxItem } from '@slotted/react/combobox';
+import { Field, FieldLabel } from '@slotted/react/field';
+
+const SERVICES = [
+  { id: 'usps-priority', name: 'USPS Priority Mail', note: '1–3 business days', disabled: false },
+  { id: 'ups-ground', name: 'UPS Ground', note: '1–5 business days', disabled: false },
+  { id: 'fedex-2day', name: 'FedEx 2Day', note: '2 business days', disabled: false },
+  {
+    id: 'dhl-express',
+    name: 'DHL Express Worldwide',
+    note: 'International shipments only',
+    disabled: true,
+  },
+  { id: 'ups-next-day', name: 'UPS Next Day Air', note: 'Cutoff passed for today', disabled: true },
+];
+
+export default function ComboboxDisabledOptions() {
+  return (
+    <Field>
+      <FieldLabel>Shipping service</FieldLabel>
+      <Combobox>
+        <ComboboxInput placeholder="Search services" />
+        <ComboboxContent>
+          {SERVICES.map((service) => (
+            <ComboboxItem
+              key={service.id}
+              value={service.id}
+              description={service.note}
+              disabled={service.disabled}
+            >
+              {service.name}
+            </ComboboxItem>
+          ))}
+        </ComboboxContent>
+      </Combobox>
+    </Field>
+  );
+}
+```
+
+### field.tsx
+
+Example
+
+```tsx
+import { Combobox, ComboboxContent, ComboboxInput, ComboboxItem } from '@slotted/react/combobox';
+import { Field, FieldDescription, FieldError, FieldLabel } from '@slotted/react/field';
+import { Stack } from '@slotted/react/stack';
+
+const OWNERS = ['Avery Collins', 'Kenji Watanabe', 'Lucía Fernández', 'Omar Haddad'];
+const COST_CENTERS = ['4100 Fulfilment', '4200 Customer care', '4300 Marketing'];
+
+export default function ComboboxField() {
+  return (
+    <Stack gap={5}>
+      <Field required>
+        <FieldLabel>Account manager</FieldLabel>
+        <Combobox>
+          <ComboboxInput placeholder="Search people" />
+          <ComboboxContent>
+            {OWNERS.map((owner) => (
+              <ComboboxItem key={owner} value={owner}>
+                {owner}
+              </ComboboxItem>
+            ))}
+          </ComboboxContent>
+        </Combobox>
+        <FieldDescription>Receives the renewal reminders for this account.</FieldDescription>
+      </Field>
+      <Field invalid required>
+        <FieldLabel>Cost center</FieldLabel>
+        <Combobox defaultInputValue="4900">
+          <ComboboxInput />
+          <ComboboxContent>
+            {COST_CENTERS.map((center) => (
+              <ComboboxItem key={center} value={center}>
+                {center}
+              </ComboboxItem>
+            ))}
+          </ComboboxContent>
+        </Combobox>
+        <FieldError>4900 is closed. Choose an open cost center.</FieldError>
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### filter-facets.tsx
+
+Example
+
+```tsx
+import { useState } from 'react';
+import { Button } from '@slotted/react/button';
+import { Combobox, ComboboxContent, ComboboxInput, ComboboxItem } from '@slotted/react/combobox';
+import { Inline } from '@slotted/react/inline';
+import { Text } from '@slotted/react/typography';
+
+type Facet = 'warehouse' | 'carrier' | 'owner';
+
+const WAREHOUSES = ['Reno, NV', 'Columbus, OH', 'Savannah, GA'];
+const CARRIERS = ['UPS', 'FedEx', 'DHL', 'USPS'];
+const OWNERS = ['Avery Collins', 'Kenji Watanabe', 'Lucía Fernández', 'Omar Haddad'];
+
+const FACETS: { id: Facet; label: string; options: string[] }[] = [
+  { id: 'warehouse', label: 'Warehouse', options: WAREHOUSES },
+  { id: 'carrier', label: 'Carrier', options: CARRIERS },
+  { id: 'owner', label: 'Owner', options: OWNERS },
+];
+
+/** Open orders, counted per warehouse, carrier and owner. */
+const ORDERS = WAREHOUSES.flatMap((warehouse, w) =>
+  CARRIERS.flatMap((carrier, c) =>
+    OWNERS.map((owner, o) => ({ warehouse, carrier, owner, count: 1 + ((w + 2 * c + 3 * o) % 5) })),
+  ),
+);
+const TOTAL = ORDERS.reduce((sum, row) => sum + row.count, 0);
+
+const NONE: Record<Facet, string | null> = { warehouse: null, carrier: null, owner: null };
+const EMPTY: Record<Facet, string> = { warehouse: '', carrier: '', owner: '' };
+
+export default function ComboboxFilterFacets() {
+  const [chosen, setChosen] = useState(NONE);
+  const [texts, setTexts] = useState(EMPTY);
+
+  const matching = ORDERS.filter((row) =>
+    FACETS.every((facet) => chosen[facet.id] === null || row[facet.id] === chosen[facet.id]),
+  ).reduce((sum, row) => sum + row.count, 0);
+  const active = FACETS.filter((facet) => chosen[facet.id] !== null).length;
+
+  const clear = () => {
+    setChosen(NONE);
+    setTexts(EMPTY);
+  };
+
+  return (
+    <Inline gap={2} align="center" wrap="wrap">
+      {FACETS.map((facet) => (
+        <Combobox
+          key={facet.id}
+          size="sm"
+          fullWidth={false}
+          width="content"
+          value={chosen[facet.id]}
+          onValueChange={(next) => setChosen((held) => ({ ...held, [facet.id]: next }))}
+          inputValue={texts[facet.id]}
+          onInputValueChange={(next) => setTexts((held) => ({ ...held, [facet.id]: next }))}
+        >
+          <ComboboxInput aria-label={facet.label} placeholder={facet.label} />
+          <ComboboxContent aria-label={facet.label}>
+            {facet.options.map((option) => (
+              <ComboboxItem key={option} value={option}>
+                {option}
+              </ComboboxItem>
+            ))}
+          </ComboboxContent>
+        </Combobox>
+      ))}
+      <Button size="sm" variant="ghost" disabled={active === 0} onClick={clear}>
+        Clear filters
+      </Button>
+      <Text size="sm" tone="muted">
+        {matching} of {TOTAL} orders
+      </Text>
+    </Inline>
+  );
+}
+```
+
+### global-search.tsx
+
+Example
+
+```tsx
+import { useState } from 'react';
+import {
+  Combobox,
+  ComboboxContent,
+  ComboboxGroup,
+  ComboboxInput,
+  ComboboxItem,
+} from '@slotted/react/combobox';
+import { Glyph, Icon } from '@slotted/react/icon';
+import { Stack } from '@slotted/react/stack';
+import { Text } from '@slotted/react/typography';
+
+const CUSTOMERS = [
+  { id: 'brightline', name: 'Brightline Studio', city: 'Portland, OR' },
+  { id: 'harbor-pine', name: 'Harbor & Pine', city: 'Seattle, WA' },
+  { id: 'northgate', name: 'Northgate Labs', city: 'Austin, TX' },
+];
+const ORDERS = [
+  { id: '10482', customer: 'Brightline Studio', total: '$1,284.00' },
+  { id: '10479', customer: 'Atlas Freight', total: '$356.40' },
+  { id: '10471', customer: 'Northgate Labs', total: '$2,910.15' },
+];
+const LABELS = new Map<string, string>([
+  ...CUSTOMERS.map((customer) => [`customer:${customer.id}`, customer.name] as const),
+  ...ORDERS.map((order) => [`order:${order.id}`, `Order ${order.id}`] as const),
+]);
+
+export default function ComboboxGlobalSearch() {
+  const [opened, setOpened] = useState<string | null>(null);
+
+  return (
+    <Stack gap={3}>
+      <Combobox openOn="focus" size="sm" onValueChange={setOpened}>
+        <ComboboxInput aria-label="Search Northwind" placeholder="Search customers and orders" />
+        <ComboboxContent aria-label="Search Northwind">
+          <ComboboxGroup label="Customers">
+            {CUSTOMERS.map((customer) => (
+              <ComboboxItem
+                key={customer.id}
+                value={`customer:${customer.id}`}
+                description={customer.city}
+                icon={
+                  <Icon>
+                    <Glyph name="person" />
+                  </Icon>
+                }
+              >
+                {customer.name}
+              </ComboboxItem>
+            ))}
+          </ComboboxGroup>
+          <ComboboxGroup label="Orders">
+            {ORDERS.map((order) => (
+              <ComboboxItem
+                key={order.id}
+                value={`order:${order.id}`}
+                description={`${order.customer} · ${order.total}`}
+                icon={
+                  <Icon>
+                    <Glyph name="file-text" />
+                  </Icon>
+                }
+              >
+                {`Order ${order.id}`}
+              </ComboboxItem>
+            ))}
+          </ComboboxGroup>
+        </ComboboxContent>
+      </Combobox>
+      <Text size="sm" tone="muted">
+        {opened === null ? 'Focus the field to see every result.' : `Opening ${LABELS.get(opened)}`}
+      </Text>
+    </Stack>
+  );
+}
+```
+
+### icons.tsx
+
+Example
+
+```tsx
+import { Combobox, ComboboxContent, ComboboxInput, ComboboxItem } from '@slotted/react/combobox';
+import { Field, FieldLabel } from '@slotted/react/field';
+import { Glyph, type GlyphName, Icon } from '@slotted/react/icon';
+
+const DOCUMENTS: { id: string; name: string; glyph: GlyphName }[] = [
+  { id: 'price-list', name: 'Q4 wholesale price list.xlsx', glyph: 'file-spreadsheet' },
+  { id: 'carrier-contract', name: 'Carrier contract 2026.pdf', glyph: 'file-text' },
+  { id: 'floor-plan', name: 'Reno floor plan.png', glyph: 'file-image' },
+  { id: 'returns-deck', name: 'Returns policy review.key', glyph: 'presentation' },
+  { id: 'product-photos', name: 'Autumn product photos.zip', glyph: 'file-archive' },
+];
+
+export default function ComboboxIcons() {
+  return (
+    <Field>
+      <FieldLabel>Attach a document</FieldLabel>
+      <Combobox>
+        <ComboboxInput placeholder="Search shared files" />
+        <ComboboxContent>
+          {DOCUMENTS.map((document) => (
+            <ComboboxItem
+              key={document.id}
+              value={document.id}
+              icon={
+                <Icon>
+                  <Glyph name={document.glyph} />
+                </Icon>
+              }
+            >
+              {document.name}
+            </ComboboxItem>
+          ))}
+        </ComboboxContent>
+      </Combobox>
+    </Field>
+  );
+}
+```
+
+### inline-completion.tsx
+
+Example
+
+```tsx
+import { Combobox, ComboboxContent, ComboboxInput, ComboboxItem } from '@slotted/react/combobox';
+import { Field, FieldLabel } from '@slotted/react/field';
+
+const TIME_ZONES = [
+  'America/New_York',
+  'America/Chicago',
+  'America/Denver',
+  'America/Los_Angeles',
+  'Europe/London',
+  'Europe/Berlin',
+  'Asia/Tokyo',
+  'Australia/Sydney',
+];
+
+export default function ComboboxInlineCompletion() {
+  return (
+    <Field>
+      <FieldLabel>Time zone</FieldLabel>
+      <Combobox autocomplete="both">
+        <ComboboxInput placeholder="Type “eu” or “am”" />
+        <ComboboxContent>
+          {TIME_ZONES.map((zone) => (
+            <ComboboxItem key={zone} value={zone}>
+              {zone}
+            </ComboboxItem>
+          ))}
+        </ComboboxContent>
+      </Combobox>
+    </Field>
+  );
+}
+```
+
+### load-more.tsx
+
+Example
+
+```tsx
+import { useMemo, useRef, useState } from 'react';
+import { Combobox, ComboboxContent, ComboboxInput, ComboboxItem } from '@slotted/react/combobox';
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+
+const PRODUCTS = [
+  'Canvas tote',
+  'Merino beanie',
+  'Stoneware mug',
+  'Linen apron',
+  'Trail daypack',
+  'Wool throw',
+  'Ceramic planter',
+  'Field notebook',
+  'Rain shell',
+  'Leather wallet',
+  'Weekender bag',
+  'Cotton crewneck',
+  'Camp mug',
+  'Insulated bottle',
+  'Chambray shirt',
+  'Waffle towel',
+  'Beeswax candle',
+  'Rattan basket',
+  'Hiking socks',
+  'Down vest',
+  'Sketchbook',
+  'Wool blanket',
+  'Market crossbody',
+  'Felt slippers',
+];
+const COLORS = [
+  'Natural',
+  'Charcoal',
+  'Olive',
+  'Rust',
+  'Navy',
+  'Sand',
+  'Forest',
+  'Slate',
+  'Clay',
+  'Ink',
+];
+const SKUS = PRODUCTS.flatMap((product, row) =>
+  COLORS.map((color, column) => ({
+    sku: `NW-${1001 + row * COLORS.length + column}`,
+    label: `${product}, ${color}`,
+  })),
+);
+const PAGE = 30;
+
+export default function ComboboxLoadMore() {
+  const [query, setQuery] = useState('');
+  const [shown, setShown] = useState(PAGE);
+  const [loading, setLoading] = useState(false);
+  const request = useRef(0);
+
+  /* The server's answer: every SKU whose label holds the query, a page at a time. */
+  const matching = useMemo(() => {
+    const needle = query.trim().toLowerCase();
+    return SKUS.filter((item) => item.label.toLowerCase().includes(needle));
+  }, [query]);
+
+  const type = (text: string) => {
+    request.current += 1;
+    setQuery(text);
+    setShown(PAGE);
+    setLoading(false);
+  };
+
+  const loadMore = () => {
+    if (loading || shown >= matching.length) return;
+    const current = ++request.current;
+    setLoading(true);
+    setTimeout(() => {
+      if (current !== request.current) return;
+      setShown((count) => count + PAGE);
+      setLoading(false);
+    }, 500);
+  };
+
+  return (
+    <Field>
+      <FieldLabel>Variant</FieldLabel>
+      <Combobox
+        filter={null}
+        inputValue={query}
+        onInputValueChange={type}
+        loading={loading}
+        onLoadMore={loadMore}
+        total={matching.length}
+      >
+        <ComboboxInput placeholder="Search 240 SKUs" />
+        <ComboboxContent>
+          {matching.slice(0, shown).map((item, index) => (
+            <ComboboxItem
+              key={item.sku}
+              value={item.sku}
+              description={item.sku}
+              position={index + 1}
+            >
+              {item.label}
+            </ComboboxItem>
+          ))}
+        </ComboboxContent>
+      </Combobox>
+      <FieldDescription>
+        Thirty at a time; scrolling to the end fetches the next page.
+      </FieldDescription>
+    </Field>
+  );
+}
+```
+
+### long-labels.tsx
+
+Example
+
+```tsx
+import { Combobox, ComboboxContent, ComboboxInput, ComboboxItem } from '@slotted/react/combobox';
+import { Field, FieldLabel } from '@slotted/react/field';
+
+const ACCOUNTS = [
+  {
+    id: '4010',
+    label:
+      '4010 · Revenue, wholesale channel, net of returns, allowances and early-payment discounts',
+  },
+  { id: '4020', label: '4020 · Revenue, online store' },
+  {
+    id: 'urn',
+    label: 'urn:northwind:ledger:4030-9f2c41ab8de07c5511903fbe',
+    description: 'Imported from the previous ledger',
+  },
+  {
+    id: '5100',
+    label: '5100 · Cost of goods sold, including inbound freight and duties',
+    description: 'Posted when an order ships, at the weighted average cost of the warehouse',
+  },
+];
+
+export default function ComboboxLongLabels() {
+  return (
+    <Field>
+      <FieldLabel>Ledger account</FieldLabel>
+      <Combobox>
+        <ComboboxInput placeholder="Search accounts" />
+        <ComboboxContent>
+          {ACCOUNTS.map((account) => (
+            <ComboboxItem key={account.id} value={account.id} description={account.description}>
+              {account.label}
+            </ComboboxItem>
+          ))}
+        </ComboboxContent>
+      </Combobox>
+    </Field>
+  );
+}
+```
+
+### long-list.tsx
+
+Example
+
+```tsx
+import { Combobox, ComboboxContent, ComboboxInput, ComboboxItem } from '@slotted/react/combobox';
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+
+const BINS = Array.from({ length: 240 }, (_, index) => {
+  const aisle = String(Math.floor(index / 20) + 1).padStart(2, '0');
+  const bay = String((index % 20) + 1).padStart(2, '0');
+  return { id: `A${aisle}-B${bay}`, detail: `Aisle ${Number(aisle)}, bay ${Number(bay)} · Reno` };
+});
+
+export default function ComboboxLongList() {
+  return (
+    <Field>
+      <FieldLabel>Put-away bin</FieldLabel>
+      <Combobox>
+        <ComboboxInput placeholder="Search 240 bins" />
+        <ComboboxContent>
+          {BINS.map((bin) => (
+            <ComboboxItem key={bin.id} value={bin.id} description={bin.detail}>
+              {bin.id}
+            </ComboboxItem>
+          ))}
+        </ComboboxContent>
+      </Combobox>
+      <FieldDescription>Page Down and Page Up move ten bins at a time.</FieldDescription>
+    </Field>
+  );
+}
+```
+
+### messages.tsx
+
+Example
+
+```tsx
+import { Combobox, ComboboxContent, ComboboxInput, ComboboxItem } from '@slotted/react/combobox';
+import { Field, FieldLabel } from '@slotted/react/field';
+
+const CARRIERS = ['UPS', 'FedEx', 'DHL', 'USPS', 'OnTrac'];
+
+export default function ComboboxCustomMessages() {
+  return (
+    <Field>
+      <FieldLabel>Carrier</FieldLabel>
+      <Combobox
+        messages={{
+          clear: 'Clear carrier',
+          count: '{count, plural, one {# carrier} other {# carriers}}',
+          empty: 'No carrier by that name. Check the spelling on the label.',
+        }}
+      >
+        <ComboboxInput placeholder="Type “royal mail”" />
+        <ComboboxContent>
+          {CARRIERS.map((carrier) => (
+            <ComboboxItem key={carrier} value={carrier}>
+              {carrier}
+            </ComboboxItem>
+          ))}
+        </ComboboxContent>
+      </Combobox>
+    </Field>
+  );
+}
+```
+
+### open-on.tsx
+
+Example
+
+```tsx
+import {
+  Combobox,
+  ComboboxContent,
+  ComboboxInput,
+  ComboboxItem,
+  type ComboboxOpenOn,
+} from '@slotted/react/combobox';
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import { Stack } from '@slotted/react/stack';
+
+const MODES: { openOn: ComboboxOpenOn; label: string; hint: string }[] = [
+  { openOn: 'input', label: 'Opens on typing', hint: 'Typing or a press on the field opens it.' },
+  { openOn: 'focus', label: 'Opens on focus', hint: 'Every focus opens it, Tab included.' },
+  {
+    openOn: 'manual',
+    label: 'Opens on request',
+    hint: 'Only the button and the arrow keys open it.',
+  },
+];
+
+const CHANNELS = ['Online store', 'Wholesale portal', 'Marketplace', 'Retail partners'];
+
+export default function ComboboxOpening() {
+  return (
+    <Stack gap={5}>
+      {MODES.map((mode) => (
+        <Field key={mode.openOn}>
+          <FieldLabel>{mode.label}</FieldLabel>
+          <Combobox openOn={mode.openOn}>
+            <ComboboxInput placeholder="Sales channel" />
+            <ComboboxContent>
+              {CHANNELS.map((channel) => (
+                <ComboboxItem key={channel} value={channel}>
+                  {channel}
+                </ComboboxItem>
+              ))}
+            </ComboboxContent>
+          </Combobox>
+          <FieldDescription>{mode.hint}</FieldDescription>
+        </Field>
+      ))}
+    </Stack>
+  );
+}
+```
+
+### search-error.tsx
+
+Example
+
+```tsx
+import { useRef, useState } from 'react';
+import { Button } from '@slotted/react/button';
+import { Combobox, ComboboxContent, ComboboxInput, ComboboxItem } from '@slotted/react/combobox';
+import { Field, FieldError, FieldLabel } from '@slotted/react/field';
+import { Stack } from '@slotted/react/stack';
+
+const CARRIERS = ['UPS', 'FedEx', 'DHL', 'USPS', 'OnTrac', 'LaserShip'];
+
+/** Stands in for a rate service that fails its first request and answers after. */
+let outage = true;
+function searchCarriers(query: string): Promise<string[]> {
+  const needle = query.trim().toLowerCase();
+  return new Promise((resolve, reject) =>
+    setTimeout(() => {
+      if (outage) {
+        outage = false;
+        reject(new Error('The rate service did not answer.'));
+        return;
+      }
+      resolve(CARRIERS.filter((carrier) => carrier.toLowerCase().includes(needle)));
+    }, 500),
+  );
+}
+
+export default function ComboboxSearchError() {
+  const [query, setQuery] = useState('');
+  const [results, setResults] = useState<string[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [failed, setFailed] = useState(false);
+  const latest = useRef(0);
+
+  const search = (text: string) => {
+    const request = ++latest.current;
+    setLoading(true);
+    setFailed(false);
+    searchCarriers(text).then(
+      (found) => {
+        if (request !== latest.current) return;
+        setResults(found);
+        setLoading(false);
+      },
+      () => {
+        if (request !== latest.current) return;
+        setResults([]);
+        setFailed(true);
+        setLoading(false);
+      },
+    );
+  };
+
+  const type = (text: string) => {
+    setQuery(text);
+    if (text.trim() !== '') search(text);
+  };
+
+  return (
+    <Stack gap={3}>
+      <Field invalid={failed}>
+        <FieldLabel>Carrier</FieldLabel>
+        <Combobox
+          filter={null}
+          inputValue={query}
+          onInputValueChange={type}
+          loading={loading}
+          messages={{ empty: failed ? 'Rates are unavailable.' : 'No carrier by that name.' }}
+        >
+          <ComboboxInput placeholder="Search carriers" />
+          <ComboboxContent>
+            {results.map((carrier) => (
+              <ComboboxItem key={carrier} value={carrier}>
+                {carrier}
+              </ComboboxItem>
+            ))}
+          </ComboboxContent>
+        </Combobox>
+        {failed && <FieldError>The rate service did not answer. Your text is kept.</FieldError>}
+      </Field>
+      {failed && (
+        <div>
+          <Button size="sm" variant="outline" onClick={() => search(query)}>
+            Retry
+          </Button>
+        </div>
+      )}
+    </Stack>
+  );
+}
+```
+
+### width.tsx
+
+Example
+
+```tsx
+import { Combobox, ComboboxContent, ComboboxInput, ComboboxItem } from '@slotted/react/combobox';
+import { Field, FieldLabel } from '@slotted/react/field';
+
+const ZONES = [
+  { id: 'pacific', label: '(UTC−08:00) Pacific Time — Los Angeles, Vancouver' },
+  { id: 'mountain', label: '(UTC−07:00) Mountain Time — Denver, Calgary' },
+  { id: 'central', label: '(UTC−06:00) Central Time — Chicago, Mexico City' },
+  { id: 'eastern', label: '(UTC−05:00) Eastern Time — New York, Toronto' },
+  { id: 'london', label: '(UTC+00:00) Greenwich Mean Time — London, Lisbon' },
+];
+
+export default function ComboboxPopupWidth() {
+  return (
+    <Field>
+      <FieldLabel>Report time zone</FieldLabel>
+      <Combobox fullWidth={false} width="content">
+        <ComboboxInput placeholder="Search zones" />
+        <ComboboxContent>
+          {ZONES.map((zone) => (
+            <ComboboxItem key={zone.id} value={zone.id}>
+              {zone.label}
+            </ComboboxItem>
+          ))}
+        </ComboboxContent>
+      </Combobox>
+    </Field>
+  );
+}
+```