@tempoxyz/ds 0.3.10 → 0.3.13

package/dist/docs/product/components/select.md

@@ -0,0 +1,751 @@
+# Select
+
+Opens a list of options for choosing one value.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Select.tsx)
+
+Figma: [Inputs/Select](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-5451) (`Select.Trigger`)
+
+## Overview
+
+Select renders a trigger that opens a listbox, for choosing one value from a short list. If the options fit on screen, prefer [ChoiceGroup](choice-group.md).
+
+## Examples
+
+### Basic
+
+```tsx
+import { Field, Select, style } from '@tempoxyz/ds'
+import { Coins, Ethereum, Wallet } from '@tempoxyz/ds/icons'
+import { useState } from 'react'
+
+const assets = [
+  { balance: '1,240.50', icon: <Coins />, label: 'pathUSD', value: 'pathusd' },
+  { balance: '845.00', icon: <Ethereum />, label: 'USDC.e', value: 'usdce' },
+  { balance: '0.00', icon: <Wallet />, label: 'Tether', value: 'usdt' },
+]
+
+const items = Object.fromEntries(assets.map((asset) => [asset.value, asset.label]))
+
+function Example(props: Pick<Select.Trigger.Props, 'disabled' | 'invalid' | 'variant'>) {
+  const [value, setValue] = useState<string | null>('pathusd')
+
+  return (
+    <Select.Root items={items} onValueChange={setValue} value={value}>
+      <Select.Trigger aria-label="Asset" {...props} {...styles.trigger()}>
+        <Select.Value placeholder="Select an asset" />
+        <Select.Icon />
+      </Select.Trigger>
+      <Select.Popup>
+        {assets.map((asset) => (
+          <Select.Item key={asset.value} label={asset.label} value={asset.value}>
+            <Select.ItemPrefix>{asset.icon}</Select.ItemPrefix>
+            <Select.ItemText>{asset.label}</Select.ItemText>
+            <Select.ItemSuffix>{asset.balance}</Select.ItemSuffix>
+          </Select.Item>
+        ))}
+        <Select.Separator />
+        <Select.Group>
+          <Select.GroupLabel>Coming soon</Select.GroupLabel>
+          <Select.Item disabled value="other">
+            <Select.ItemText>Other</Select.ItemText>
+          </Select.Item>
+        </Select.Group>
+      </Select.Popup>
+    </Select.Root>
+  )
+}
+
+export function Demo() {
+  return (
+    <Field.Root>
+      <Field.Label>Asset</Field.Label>
+      <Example />
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const trigger = style({ maxWidth: '320px !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Select/Basic.tsx)
+
+### Variant
+
+Set `variant` on `Select.Trigger` to `default` (default) or `outlined`, which draws a 1px line instead of the fill.
+
+```tsx
+import { Field, Select, style } from '@tempoxyz/ds'
+
+const items = { mainnet: 'Tempo', testnet: 'Tempo Testnet' }
+
+export function Demo() {
+  return (
+    <div {...styles.grid()}>
+      {(['default', 'outlined'] as const).map((variant) => (
+        <Field.Root key={variant}>
+          <Field.Label>Network</Field.Label>
+          <Select.Root defaultValue="mainnet" items={items}>
+            <Select.Trigger variant={variant}>
+              <Select.Value />
+              <Select.Icon />
+            </Select.Trigger>
+            <Select.Popup>
+              {Object.entries(items).map(([value, label]) => (
+                <Select.Item key={value} label={label} value={value}>
+                  <Select.ItemText>{label}</Select.ItemText>
+                </Select.Item>
+              ))}
+            </Select.Popup>
+          </Select.Root>
+        </Field.Root>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const grid = style({
+    alignItems: 'start',
+    display: 'grid',
+    gap: '24',
+    gridTemplateColumns: 'repeat(auto-fill, minmax(min(280px, 100%), 1fr)) !custom',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Select/Variant.tsx)
+
+### Prefix
+
+Put a `Select.Prefix` before `Select.Value` to name what a filter selects, such as By in By Anyone. Name the trigger with `aria-label` too.
+
+```tsx
+/**
+ * Prefix demo for the Select page: a dashboard filter whose prefix names what it filters.
+ * @module
+ */
+import { Select, style } from '@tempoxyz/ds'
+
+const owners = { anyone: 'Anyone', me: 'Me', team: 'My team' }
+
+/** Renders a filter that hugs its prefix, value, and chevron. */
+export function Demo() {
+  return (
+    <Select.Root defaultValue="anyone" items={owners}>
+      <Select.Trigger aria-label="Owner" {...styles.trigger()}>
+        <Select.Prefix>By</Select.Prefix>
+        <Select.Value />
+        <Select.Icon />
+      </Select.Trigger>
+      <Select.Popup>
+        {Object.entries(owners).map(([value, label]) => (
+          <Select.Item key={value} label={label} value={value}>
+            <Select.ItemText>{label}</Select.ItemText>
+          </Select.Item>
+        ))}
+      </Select.Popup>
+    </Select.Root>
+  )
+}
+
+namespace styles {
+  // A filter sizes to its content instead of filling the row.
+  export const trigger = style({ width: 'max-content !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Select/Prefix.tsx)
+
+### Field
+
+Wrap the select in a `Field.Root` to label it and describe it.
+
+```tsx
+import { Field, Select, style } from '@tempoxyz/ds'
+import { Coins, Ethereum, Wallet } from '@tempoxyz/ds/icons'
+import { useState } from 'react'
+
+const assets = [
+  { balance: '1,240.50', icon: <Coins />, label: 'pathUSD', value: 'pathusd' },
+  { balance: '845.00', icon: <Ethereum />, label: 'USDC.e', value: 'usdce' },
+  { balance: '0.00', icon: <Wallet />, label: 'Tether', value: 'usdt' },
+]
+
+const items = Object.fromEntries(assets.map((asset) => [asset.value, asset.label]))
+
+function Example(props: Pick<Select.Trigger.Props, 'disabled' | 'invalid' | 'variant'>) {
+  const [value, setValue] = useState<string | null>('pathusd')
+
+  return (
+    <Select.Root items={items} onValueChange={setValue} value={value}>
+      <Select.Trigger aria-label="Asset" {...props} {...styles.trigger()}>
+        <Select.Value placeholder="Select an asset" />
+        <Select.Icon />
+      </Select.Trigger>
+      <Select.Popup>
+        {assets.map((asset) => (
+          <Select.Item key={asset.value} label={asset.label} value={asset.value}>
+            <Select.ItemPrefix>{asset.icon}</Select.ItemPrefix>
+            <Select.ItemText>{asset.label}</Select.ItemText>
+            <Select.ItemSuffix>{asset.balance}</Select.ItemSuffix>
+          </Select.Item>
+        ))}
+        <Select.Separator />
+        <Select.Group>
+          <Select.GroupLabel>Coming soon</Select.GroupLabel>
+          <Select.Item disabled value="other">
+            <Select.ItemText>Other</Select.ItemText>
+          </Select.Item>
+        </Select.Group>
+      </Select.Popup>
+    </Select.Root>
+  )
+}
+
+export function Demo() {
+  return (
+    <div {...styles.grid()}>
+      <Field.Root>
+        <Field.Label>Asset</Field.Label>
+        <Example />
+        <Field.Description>Pays the network fee.</Field.Description>
+      </Field.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  export const grid = style({
+    alignItems: 'start',
+    display: 'grid',
+    gap: '12',
+    gridTemplateColumns: 'repeat(auto-fill, minmax(240px, 1fr)) !custom',
+  })
+
+  export const trigger = style({ maxWidth: '320px !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Select/Field.tsx)
+
+### Invalid
+
+Set `invalid` on `Select.Trigger` to mark the value as invalid.
+
+```tsx
+import { Select, style } from '@tempoxyz/ds'
+import { Coins, Ethereum, Wallet } from '@tempoxyz/ds/icons'
+import { useState } from 'react'
+
+const assets = [
+  { balance: '1,240.50', icon: <Coins />, label: 'pathUSD', value: 'pathusd' },
+  { balance: '845.00', icon: <Ethereum />, label: 'USDC.e', value: 'usdce' },
+  { balance: '0.00', icon: <Wallet />, label: 'Tether', value: 'usdt' },
+]
+
+const items = Object.fromEntries(assets.map((asset) => [asset.value, asset.label]))
+
+function Example(props: Pick<Select.Trigger.Props, 'disabled' | 'invalid' | 'variant'>) {
+  const [value, setValue] = useState<string | null>('pathusd')
+
+  return (
+    <Select.Root items={items} onValueChange={setValue} value={value}>
+      <Select.Trigger aria-label="Asset" {...props} {...styles.trigger()}>
+        <Select.Value placeholder="Select an asset" />
+        <Select.Icon />
+      </Select.Trigger>
+      <Select.Popup>
+        {assets.map((asset) => (
+          <Select.Item key={asset.value} label={asset.label} value={asset.value}>
+            <Select.ItemPrefix>{asset.icon}</Select.ItemPrefix>
+            <Select.ItemText>{asset.label}</Select.ItemText>
+            <Select.ItemSuffix>{asset.balance}</Select.ItemSuffix>
+          </Select.Item>
+        ))}
+        <Select.Separator />
+        <Select.Group>
+          <Select.GroupLabel>Coming soon</Select.GroupLabel>
+          <Select.Item disabled value="other">
+            <Select.ItemText>Other</Select.ItemText>
+          </Select.Item>
+        </Select.Group>
+      </Select.Popup>
+    </Select.Root>
+  )
+}
+
+export function Demo() {
+  return <Example invalid />
+}
+
+namespace styles {
+  export const trigger = style({ maxWidth: '320px !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Select/Invalid.tsx)
+
+### Disabled
+
+```tsx
+import { Select, style } from '@tempoxyz/ds'
+import { Coins, Ethereum, Wallet } from '@tempoxyz/ds/icons'
+import { useState } from 'react'
+
+const assets = [
+  { balance: '1,240.50', icon: <Coins />, label: 'pathUSD', value: 'pathusd' },
+  { balance: '845.00', icon: <Ethereum />, label: 'USDC.e', value: 'usdce' },
+  { balance: '0.00', icon: <Wallet />, label: 'Tether', value: 'usdt' },
+]
+
+const items = Object.fromEntries(assets.map((asset) => [asset.value, asset.label]))
+
+function Example(props: Pick<Select.Trigger.Props, 'disabled' | 'invalid' | 'variant'>) {
+  const [value, setValue] = useState<string | null>('pathusd')
+
+  return (
+    <Select.Root items={items} onValueChange={setValue} value={value}>
+      <Select.Trigger aria-label="Asset" {...props} {...styles.trigger()}>
+        <Select.Value placeholder="Select an asset" />
+        <Select.Icon />
+      </Select.Trigger>
+      <Select.Popup>
+        {assets.map((asset) => (
+          <Select.Item key={asset.value} label={asset.label} value={asset.value}>
+            <Select.ItemPrefix>{asset.icon}</Select.ItemPrefix>
+            <Select.ItemText>{asset.label}</Select.ItemText>
+            <Select.ItemSuffix>{asset.balance}</Select.ItemSuffix>
+          </Select.Item>
+        ))}
+        <Select.Separator />
+        <Select.Group>
+          <Select.GroupLabel>Coming soon</Select.GroupLabel>
+          <Select.Item disabled value="other">
+            <Select.ItemText>Other</Select.ItemText>
+          </Select.Item>
+        </Select.Group>
+      </Select.Popup>
+    </Select.Root>
+  )
+}
+
+export function Demo() {
+  return <Example disabled />
+}
+
+namespace styles {
+  export const trigger = style({ maxWidth: '320px !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Select/Disabled.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Select } from '@tempoxyz/ds'
+
+<Select.Root>
+  <Select.Trigger>
+    <Select.Prefix />
+    <Select.Value />
+    <Select.Icon />
+  </Select.Trigger>
+  <Select.Popup>
+    <Select.Item>
+      <Select.ItemPrefix />
+      <Select.ItemText />
+      <Select.ItemSuffix />
+    </Select.Item>
+    <Select.Separator />
+    <Select.Group>
+      <Select.GroupLabel />
+    </Select.Group>
+  </Select.Popup>
+</Select.Root>
+```
+
+## Guidelines
+
+### When to Use
+
+* Choose one value from more than five scannable options, such as an asset or a network.
+* Filter a dashboard or table where space is tight, such as a chart's time range.
+* Set `multiple` to pick several values when a [CheckboxGroup](checkbox-group.md) takes too much room.
+
+### When Not to Use
+
+* Use [RadioGroup](radio-group.md) for two to five options compared side by side.
+* Use [ChoiceGroup](choice-group.md) for two to four short options that switch a view, such as 1H, 24H, and 7D.
+* Use [Combobox](combobox.md) for a long list filtered by typing, such as every token on Tempo.
+* Use [Autocomplete](autocomplete.md) when any typed text is a valid value.
+* Use [Menu](menu.md) for a list of actions. A select holds a value.
+
+### Show Labels, Not Raw Values
+
+Pass `items` to `Select.Root` to map each value to its label. Without it, `Select.Value` renders the raw value.
+
+**Do:** Pass `items` so the trigger shows the asset's name.
+
+```tsx
+/**
+ * Do example for "Show Labels, Not Raw Values" on the Select page.
+ * Pass `items` so the trigger shows the asset's name.
+ * @module
+ */
+import { Field, Select, style } from '@tempoxyz/ds'
+
+const items = { pathusd: 'pathUSD', usdce: 'USDC.e' }
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <Field.Label>Asset</Field.Label>
+      <Select.Root defaultValue="usdce" items={items}>
+        <Select.Trigger>
+          <Select.Value placeholder="Select an asset" />
+          <Select.Icon />
+        </Select.Trigger>
+        <Select.Popup>
+          <Select.Item value="pathusd">
+            <Select.ItemText>pathUSD</Select.ItemText>
+          </Select.Item>
+          <Select.Item value="usdce">
+            <Select.ItemText>USDC.e</Select.ItemText>
+          </Select.Item>
+        </Select.Popup>
+      </Select.Root>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })
+}
+```
+
+**Don't:** Leave the trigger showing an internal value such as `usdce`.
+
+```tsx
+/**
+ * Don't example for "Show Labels, Not Raw Values" on the Select page.
+ * Don't leave the trigger showing an internal value such as `usdce`.
+ * @module
+ */
+import { Field, Select, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <Field.Label>Asset</Field.Label>
+      <Select.Root defaultValue="usdce">
+        <Select.Trigger>
+          <Select.Value placeholder="Select an asset" />
+          <Select.Icon />
+        </Select.Trigger>
+        <Select.Popup>
+          <Select.Item value="pathusd">
+            <Select.ItemText>pathUSD</Select.ItemText>
+          </Select.Item>
+          <Select.Item value="usdce">
+            <Select.ItemText>USDC.e</Select.ItemText>
+          </Select.Item>
+        </Select.Popup>
+      </Select.Root>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })
+}
+```
+
+### Order Options Predictably
+
+Pick one ordering rule per list and keep it everywhere the list appears.
+
+* **Numeric or Chronological (smallest first):** For values with a natural order, such as time ranges, sizes, and block heights.
+* **Alphabetical (Select.Group):** For tokens, networks, and countries, with the common ones grouped first.
+* **Most Used First:** For a few options with one clear favorite first, then the rest in a fixed order.
+
+* Don't reorder options by recent use. People learn positions and typeahead order.
+* Split long lists into `Select.Group` sections with a `Select.GroupLabel`, divided by `Select.Separator`.
+* Hide options that can never be chosen. Show a `disabled` item only when its group label or text states why, such as Coming soon.
+
+### Choose the Default Deliberately
+
+If one choice suits most people, preselect it with `defaultValue`, such as the largest balance or the last 24 hours. Always give a filter a default.
+
+**Do:** Give a dashboard filter a default that shows data right away.
+
+```tsx
+/**
+ * Do example for "Choose the Default Deliberately" on the Select page.
+ * Give a dashboard filter a default that shows data right away.
+ * @module
+ */
+import { Field, Select, style } from '@tempoxyz/ds'
+
+const items = { '1h': 'Last hour', '24h': 'Last 24 hours', '7d': 'Last 7 days' }
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <Field.Label>Time range</Field.Label>
+      <Select.Root defaultValue="24h" items={items}>
+        <Select.Trigger>
+          <Select.Value placeholder="Select a time range" />
+          <Select.Icon />
+        </Select.Trigger>
+        <Select.Popup size="small">
+          {Object.entries(items).map(([value, label]) => (
+            <Select.Item key={value} value={value}>
+              <Select.ItemText>{label}</Select.ItemText>
+            </Select.Item>
+          ))}
+        </Select.Popup>
+      </Select.Root>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ width: '12rem !custom' })
+}
+```
+
+**Don't:** Leave a filter empty with a generic placeholder.
+
+```tsx
+/**
+ * Don't example for "Choose the Default Deliberately" on the Select page.
+ * Don't leave a filter empty with a generic placeholder.
+ * @module
+ */
+import { Field, Select, style } from '@tempoxyz/ds'
+
+const items = { '1h': 'Last hour', '24h': 'Last 24 hours', '7d': 'Last 7 days' }
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <Field.Label>Time range</Field.Label>
+      <Select.Root items={items}>
+        <Select.Trigger>
+          <Select.Value placeholder="Select" />
+          <Select.Icon />
+        </Select.Trigger>
+        <Select.Popup size="small">
+          {Object.entries(items).map(([value, label]) => (
+            <Select.Item key={value} value={value}>
+              <Select.ItemText>{label}</Select.ItemText>
+            </Select.Item>
+          ))}
+        </Select.Popup>
+      </Select.Root>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ width: '12rem !custom' })
+}
+```
+
+If a guess could cost something, such as a withdrawal network, leave the select empty. Set a `placeholder` on `Select.Value` that names the choice, such as Select a network, and validate on submit. Add a None option only if none is a valid answer.
+
+### Keep Option Rows Scannable
+
+* **Prefix and suffix:** Put a token icon or [Avatar](avatar.md) in `Select.ItemPrefix`, and a secondary value such as a balance in `Select.ItemSuffix`.
+* **Typeahead label:** If a row holds a prefix or suffix, give `Select.Item` a `label`.
+* **Text length:** Keep `Select.ItemText` short. It truncates beside a prefix or suffix.
+* **First words:** Start options with distinct words, in a parallel format, such as Last hour and Last 24 hours. Typeahead jumps by first letters.
+
+**Do:** Put the icon and balance in the item's prefix and suffix, and keep the text short.
+
+```tsx
+/**
+ * Do example for "Keep Option Rows Scannable" on the Select page.
+ * Put the icon and balance in the item's prefix and suffix, and keep the text short.
+ * @module
+ */
+import { Check } from '@tempoxyz/ds/icons'
+import { style } from '@tempoxyz/ds'
+import pathusd from '../../coins/PathUSD.svg'
+import usdce from '../../coins/USDCe.svg'
+import usdt0 from '../../coins/USDT0.svg'
+
+const assets = [
+  { balance: '1,250.00', icon: pathusd, name: 'pathUSD', selected: true },
+  { balance: '480.25', icon: usdce, name: 'USDC.e', selected: false },
+  { balance: '12.00', icon: usdt0, name: 'USDT0', selected: false },
+]
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.popup()}>
+      {assets.map((asset) => (
+        <div key={asset.name} {...styles.item()}>
+          <img alt="" height={20} src={asset.icon} width={20} />
+          <span {...styles.text()}>{asset.name}</span>
+          <span {...styles.suffix()}>{asset.balance}</span>
+          <span {...styles.check()}>{asset.selected && <Check />}</span>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const check = style({ display: 'flex', width: '16px !custom' })
+
+  export const item = style({
+    alignItems: 'center',
+    borderRadius: 'xs',
+    color: 'content.primary',
+    display: 'flex',
+    gap: '8',
+    minHeight: '40',
+    paddingInline: '12',
+    typography: 'body.b2',
+  })
+
+  export const popup = style({
+    backgroundColor: 'background.elevated',
+    borderRadius: 'sm',
+    boxShadow: 'regular',
+    boxSizing: 'border-box',
+    padding: '8',
+    width: '16rem !custom',
+  })
+
+  export const suffix = style({ color: 'content.secondary', typography: 'body.b3' })
+
+  export const text = style({ flex: '1 !custom' })
+}
+```
+
+**Don't:** Pack names, details, and balances into the option text.
+
+```tsx
+/**
+ * Don't example for "Keep Option Rows Scannable" on the Select page.
+ * Don't pack names, details, and balances into the option text.
+ * @module
+ */
+import { Check } from '@tempoxyz/ds/icons'
+import { style } from '@tempoxyz/ds'
+
+const assets = [
+  { label: 'pathUSD, Tempo stablecoin, balance 1,250.00', selected: true },
+  { label: 'USDC.e, bridged USD Coin, balance 480.25', selected: false },
+  { label: 'USDT0, bridged Tether, balance 12.00', selected: false },
+]
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.popup()}>
+      {assets.map((asset) => (
+        <div key={asset.label} {...styles.item()}>
+          <span {...styles.text()}>{asset.label}</span>
+          <span {...styles.check()}>{asset.selected && <Check />}</span>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const check = style({ display: 'flex', flexShrink: '0 !custom', width: '16px !custom' })
+
+  export const item = style({
+    alignItems: 'center',
+    borderRadius: 'xs',
+    color: 'content.primary',
+    display: 'flex',
+    gap: '8',
+    minHeight: '40',
+    paddingInline: '12',
+    typography: 'body.b2',
+  })
+
+  export const popup = style({
+    backgroundColor: 'background.elevated',
+    borderRadius: 'sm',
+    boxShadow: 'regular',
+    boxSizing: 'border-box',
+    padding: '8',
+    width: '16rem !custom',
+  })
+
+  export const text = style({
+    flex: '1 !custom',
+    minWidth: '0 !custom',
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+    whiteSpace: 'nowrap',
+  })
+}
+```
+
+## Accessibility
+
+Select handles arrow keys, typeahead, and Escape. It follows the [WAI-ARIA Authoring Practices select-only combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-select-only/).
+
+### Semantics
+
+* **Select.Trigger (combobox):** A button that announces its popup and whether the list is open.
+* **Select.Popup and Select.Item (listbox):** The list renders in a portal. The selected option shows a check, not only a color.
+* **Select.Group (group):** A set of related options, named by the group label inside it.
+* **Invalid and Disabled (aria-invalid):** `invalid` marks the trigger and fills it red. `disabled` removes it from the tab order.
+* **Select.Icon (aria-hidden):** Decorative, so it is hidden from assistive technology and not announced.
+* **Target Size (48px):** The trigger matches the 48px field, above the 24px WCAG 2.2 minimum.
+
+### Keyboard
+
+* **Move to the Trigger (Tab):** Moves focus to the trigger.
+* **Open the List (Enter, Space, or Down Arrow):** Opens the list and focuses the selected option.
+* **Move Between Options (Down Arrow and Up Arrow):** Move focus to the next or previous option.
+* **Jump to the Ends (Home and End):** Move focus to the first or last option.
+* **Type to Find (Character):** Focuses the next option starting with that key.
+* **Select an Option (Enter or Space):** On an option, selects it and closes the list.
+* **Close the List (Escape):** Keeps the value and returns focus to the trigger.
+
+### Your Responsibilities
+
+* **Name the Trigger (Field.Label):** Use a visible field label. If none fits, set `aria-label`.
+* **Explain Invalid Values (Field.Error):** Explain invalid values in text, not only the red fill.
+
+## Related
+
+[Combobox](combobox.md)
+
+Use for long, filterable lists.
+
+[RadioGroup](radio-group.md)
+
+Use for a few options shown at once.
+
+[ChoiceGroup](choice-group.md)
+
+Use for switching views.
+
+[Menu](menu.md)
+
+Use for lists of actions.
+
+[Dashboards](../patterns/dashboards.md)
+
+Covers filter bars and controls.