@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/components/combobox.md

@@ -0,0 +1,939 @@
+# Combobox
+
+A text input that filters a list of fixed options while people type.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Combobox.tsx)
+
+## Overview
+
+A text input with a listbox popup. The value must be one of the options.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Combobox } from '@tempoxyz/ds'
+import { Search } from '@tempoxyz/ds/icons'
+import { useState } from 'react'
+import cbBtc from '../../coins/CbBTC.svg'
+import ethereumEth from '../../coins/EthereumETH.svg'
+import pathUsd from '../../coins/PathUSD.svg'
+import usdce from '../../coins/USDCe.svg'
+import usdt0 from '../../coins/USDT0.svg'
+
+const coins: Record<string, string> = {
+  'Bridged ETH': ethereumEth,
+  pathUSD: pathUsd,
+  Tether: usdt0,
+  'USDC.e': usdce,
+  USDT0: usdt0,
+  'Wrapped BTC': cbBtc,
+}
+
+const assets = ['pathUSD', 'USDC.e', 'Tether', 'USDT0', 'Bridged ETH', 'Wrapped BTC']
+
+function Coin(props: { asset: string }) {
+  return <img alt="" height={20} src={coins[props.asset]} width={20} />
+}
+
+function Single(props: Pick<Combobox.InputGroup.Props, 'invalid' | 'variant'>) {
+  const [value, setValue] = useState<string | null>('pathUSD')
+
+  return (
+    <Combobox.Root items={assets} onValueChange={setValue} value={value}>
+      <Combobox.InputGroup {...props}>
+        <Combobox.Prefix>{value ? <Coin asset={value} /> : <Search />}</Combobox.Prefix>
+        <Combobox.Input aria-label="Asset" placeholder="Search assets" />
+        <Combobox.Clear />
+        <Combobox.Trigger />
+      </Combobox.InputGroup>
+      <Combobox.Popup>
+        <Combobox.Empty>No results</Combobox.Empty>
+        <Combobox.List>
+          {(asset: string) => (
+            <Combobox.Item key={asset} value={asset}>
+              <Combobox.ItemPrefix>
+                <Coin asset={asset} />
+              </Combobox.ItemPrefix>
+              <Combobox.ItemText>{asset}</Combobox.ItemText>
+            </Combobox.Item>
+          )}
+        </Combobox.List>
+      </Combobox.Popup>
+    </Combobox.Root>
+  )
+}
+
+export function Demo() {
+  return <Single />
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Combobox/Basic.tsx)
+
+### Variant
+
+Set `variant` on `Combobox.InputGroup` to `filled` (default) or `outlined`.
+
+```tsx
+import { Combobox, style } from '@tempoxyz/ds'
+import { Search } from '@tempoxyz/ds/icons'
+import { useState } from 'react'
+import cbBtc from '../../coins/CbBTC.svg'
+import ethereumEth from '../../coins/EthereumETH.svg'
+import pathUsd from '../../coins/PathUSD.svg'
+import usdce from '../../coins/USDCe.svg'
+import usdt0 from '../../coins/USDT0.svg'
+
+const coins: Record<string, string> = {
+  'Bridged ETH': ethereumEth,
+  pathUSD: pathUsd,
+  Tether: usdt0,
+  'USDC.e': usdce,
+  USDT0: usdt0,
+  'Wrapped BTC': cbBtc,
+}
+
+const assets = ['pathUSD', 'USDC.e', 'Tether', 'USDT0', 'Bridged ETH', 'Wrapped BTC']
+
+function Coin(props: { asset: string }) {
+  return <img alt="" height={20} src={coins[props.asset]} width={20} />
+}
+
+function Single(props: Pick<Combobox.InputGroup.Props, 'invalid' | 'variant'>) {
+  const [value, setValue] = useState<string | null>('pathUSD')
+
+  return (
+    <Combobox.Root items={assets} onValueChange={setValue} value={value}>
+      <Combobox.InputGroup {...props}>
+        <Combobox.Prefix>{value ? <Coin asset={value} /> : <Search />}</Combobox.Prefix>
+        <Combobox.Input aria-label="Asset" placeholder="Search assets" />
+        <Combobox.Clear />
+        <Combobox.Trigger />
+      </Combobox.InputGroup>
+      <Combobox.Popup>
+        <Combobox.Empty>No results</Combobox.Empty>
+        <Combobox.List>
+          {(asset: string) => (
+            <Combobox.Item key={asset} value={asset}>
+              <Combobox.ItemPrefix>
+                <Coin asset={asset} />
+              </Combobox.ItemPrefix>
+              <Combobox.ItemText>{asset}</Combobox.ItemText>
+            </Combobox.Item>
+          )}
+        </Combobox.List>
+      </Combobox.Popup>
+    </Combobox.Root>
+  )
+}
+
+export function Demo() {
+  return (
+    <div {...styles.grid()}>
+      <Single />
+      <Single variant="outlined" />
+    </div>
+  )
+}
+
+namespace styles {
+  export const grid = style({
+    alignItems: 'start',
+    display: 'grid',
+    gap: '12',
+    gridTemplateColumns: 'repeat(auto-fill, minmax(280px, 1fr)) !custom',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Combobox/Variant.tsx)
+
+### Invalid
+
+Set `invalid` on `Combobox.InputGroup` to style the frame, and `aria-invalid` on the input to expose the state.
+
+```tsx
+import { Combobox } from '@tempoxyz/ds'
+import { Search } from '@tempoxyz/ds/icons'
+import { useState } from 'react'
+import cbBtc from '../../coins/CbBTC.svg'
+import ethereumEth from '../../coins/EthereumETH.svg'
+import pathUsd from '../../coins/PathUSD.svg'
+import usdce from '../../coins/USDCe.svg'
+import usdt0 from '../../coins/USDT0.svg'
+
+const coins: Record<string, string> = {
+  'Bridged ETH': ethereumEth,
+  pathUSD: pathUsd,
+  Tether: usdt0,
+  'USDC.e': usdce,
+  USDT0: usdt0,
+  'Wrapped BTC': cbBtc,
+}
+
+const assets = ['pathUSD', 'USDC.e', 'Tether', 'USDT0', 'Bridged ETH', 'Wrapped BTC']
+
+function Coin(props: { asset: string }) {
+  return <img alt="" height={20} src={coins[props.asset]} width={20} />
+}
+
+function Single(props: Pick<Combobox.InputGroup.Props, 'invalid' | 'variant'>) {
+  const [value, setValue] = useState<string | null>('pathUSD')
+
+  return (
+    <Combobox.Root items={assets} onValueChange={setValue} value={value}>
+      <Combobox.InputGroup {...props}>
+        <Combobox.Prefix>{value ? <Coin asset={value} /> : <Search />}</Combobox.Prefix>
+        <Combobox.Input aria-label="Asset" placeholder="Search assets" />
+        <Combobox.Clear />
+        <Combobox.Trigger />
+      </Combobox.InputGroup>
+      <Combobox.Popup>
+        <Combobox.Empty>No results</Combobox.Empty>
+        <Combobox.List>
+          {(asset: string) => (
+            <Combobox.Item key={asset} value={asset}>
+              <Combobox.ItemPrefix>
+                <Coin asset={asset} />
+              </Combobox.ItemPrefix>
+              <Combobox.ItemText>{asset}</Combobox.ItemText>
+            </Combobox.Item>
+          )}
+        </Combobox.List>
+      </Combobox.Popup>
+    </Combobox.Root>
+  )
+}
+
+export function Demo() {
+  return <Single invalid />
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Combobox/Invalid.tsx)
+
+### Multiple
+
+Set `multiple` on `Combobox.Root` to select several values, shown as chips.
+
+```tsx
+import { Combobox } from '@tempoxyz/ds'
+import { useState } from 'react'
+
+const assets = ['pathUSD', 'USDC.e', 'Tether', 'USDT0', 'Bridged ETH', 'Wrapped BTC']
+
+function Multiple() {
+  const [value, setValue] = useState(['pathUSD', 'USDC.e'])
+
+  return (
+    <Combobox.Root items={assets} multiple onValueChange={setValue} value={value}>
+      <Combobox.InputGroup>
+        <Combobox.Value>
+          {(selected: string[]) => (
+            <Combobox.Chips aria-label="Selected assets">
+              {selected.map((asset) => (
+                <Combobox.Chip key={asset}>
+                  {asset}
+                  <Combobox.ChipRemove aria-label={`Remove ${asset}`} />
+                </Combobox.Chip>
+              ))}
+              <Combobox.Input
+                aria-label="Assets"
+                placeholder={selected.length ? '' : 'Add assets'}
+              />
+            </Combobox.Chips>
+          )}
+        </Combobox.Value>
+      </Combobox.InputGroup>
+      <Combobox.Popup>
+        <Combobox.Empty>No results</Combobox.Empty>
+        <Combobox.List>
+          {(asset: string) => (
+            <Combobox.Item key={asset} value={asset}>
+              <Combobox.ItemText>{asset}</Combobox.ItemText>
+            </Combobox.Item>
+          )}
+        </Combobox.List>
+      </Combobox.Popup>
+    </Combobox.Root>
+  )
+}
+
+export function Demo() {
+  return <Multiple />
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Combobox/Multiple.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Combobox } from '@tempoxyz/ds'
+
+<Combobox.Root>
+  <Combobox.InputGroup>
+    <Combobox.Prefix />
+    <Combobox.Value>
+      <Combobox.Chips>
+        <Combobox.Chip>
+          <Combobox.ChipRemove />
+        </Combobox.Chip>
+        <Combobox.Input />
+      </Combobox.Chips>
+    </Combobox.Value>
+    <Combobox.Clear />
+    <Combobox.Trigger />
+  </Combobox.InputGroup>
+  <Combobox.Popup>
+    <Combobox.Empty />
+    <Combobox.List>
+      <Combobox.Group>
+        <Combobox.GroupLabel />
+        <Combobox.Collection>
+          <Combobox.Item>
+            <Combobox.ItemPrefix />
+            <Combobox.ItemText />
+            <Combobox.ItemSuffix />
+          </Combobox.Item>
+        </Combobox.Collection>
+      </Combobox.Group>
+      <Combobox.Separator />
+    </Combobox.List>
+  </Combobox.Popup>
+</Combobox.Root>
+```
+
+## Guidelines
+
+### When to Use
+
+* Choose one item from a long, fixed list filtered by typing, such as the asset to send or the country on an account.
+* Choose several items from that list with `multiple`, such as the assets a report covers.
+
+### When Not to Use
+
+* If people can scan the whole list without typing, use [Select](/docs/components/select).
+* If any typed text is a valid value, such as a recipient address, use [Autocomplete](/docs/components/autocomplete).
+* Use [RadioGroup](/docs/components/radio-group) or [ChoiceGroup](/docs/components/choice-group) for a few options that fit on screen.
+* Use [CheckboxGroup](/docs/components/checkbox-group) for several options from a short list.
+
+### Keep a Visible Label
+
+The placeholder disappears on input, so it can't name the field.
+
+**Do:** Label the field and show the selected asset's icon in `Combobox.Prefix`.
+
+```tsx
+/**
+ * Do example for "Keep a Visible Label" on the Combobox page.
+ * Label the field and show the selected asset's icon in `Combobox.Prefix`.
+ * @module
+ */
+import { Combobox, Field, style } from '@tempoxyz/ds'
+import usdce from '../../coins/USDCe.svg'
+
+const assets = ['pathUSD', 'USDC.e', 'USDT0']
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <Field.Label>Asset</Field.Label>
+      <Combobox.Root defaultValue="USDC.e" items={assets}>
+        <Combobox.InputGroup>
+          <Combobox.Prefix>
+            <img alt="" height={20} src={usdce} width={20} />
+          </Combobox.Prefix>
+          <Combobox.Input placeholder="Search assets" />
+          <Combobox.Trigger />
+        </Combobox.InputGroup>
+        <Combobox.Popup>
+          <Combobox.Empty>No assets found</Combobox.Empty>
+          <Combobox.List>
+            {(asset: string) => (
+              <Combobox.Item key={asset} value={asset}>
+                <Combobox.ItemText>{asset}</Combobox.ItemText>
+              </Combobox.Item>
+            )}
+          </Combobox.List>
+        </Combobox.Popup>
+      </Combobox.Root>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ width: '100% !custom' })
+}
+```
+
+**Don't:** Rely on the placeholder to say what the field is for.
+
+```tsx
+/**
+ * Don't example for "Keep a Visible Label" on the Combobox page.
+ * Don't rely on the placeholder to say what the field is for.
+ * @module
+ */
+import { Combobox, style } from '@tempoxyz/ds'
+import { Search } from '@tempoxyz/ds/icons'
+
+const assets = ['pathUSD', 'USDC.e', 'USDT0']
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Combobox.Root items={assets}>
+      <Combobox.InputGroup {...styles.group()}>
+        <Combobox.Prefix>
+          <Search />
+        </Combobox.Prefix>
+        <Combobox.Input aria-label="Asset" placeholder="Search assets" />
+        <Combobox.Trigger />
+      </Combobox.InputGroup>
+      <Combobox.Popup>
+        <Combobox.Empty>No assets found</Combobox.Empty>
+        <Combobox.List>
+          {(asset: string) => (
+            <Combobox.Item key={asset} value={asset}>
+              <Combobox.ItemText>{asset}</Combobox.ItemText>
+            </Combobox.Item>
+          )}
+        </Combobox.List>
+      </Combobox.Popup>
+    </Combobox.Root>
+  )
+}
+
+namespace styles {
+  export const group = style({ width: '100% !custom' })
+}
+```
+
+### Always Render Combobox.Empty
+
+`Combobox.Empty` shows its children when nothing matches and announces them in a polite status region.
+
+**Do:** Render a short, specific message, such as No assets found.
+
+```tsx
+/**
+ * Do example for "Always Render Combobox.Empty" on the Combobox page.
+ * Render a short, specific message, such as No assets found.
+ * @module
+ */
+import { Combobox, style } from '@tempoxyz/ds'
+
+const assets = ['pathUSD', 'USDC.e', 'USDT0']
+
+// The popup portals and opens on input, so a static copy shows it open.
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.column()}>
+      <Combobox.Root defaultInputValue="EURC" items={assets}>
+        <Combobox.InputGroup>
+          <Combobox.Input aria-label="Asset" />
+          <Combobox.Trigger />
+        </Combobox.InputGroup>
+      </Combobox.Root>
+      <div {...styles.popup()}>
+        <div {...styles.empty()}>No assets found</div>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const column = style({
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '8',
+    maxWidth: '16rem !custom',
+    width: '100% !custom',
+  })
+
+  export const empty = style({
+    color: 'content.secondary',
+    paddingBlock: '12',
+    paddingInline: '16',
+    typography: 'body.b2',
+  })
+
+  export const popup = style({
+    backgroundColor: 'background.elevated',
+    borderRadius: 'sm',
+    boxShadow: 'regular',
+    padding: '6px !custom',
+  })
+}
+```
+
+**Don't:** Leave it out. The popup opens blank and announces nothing.
+
+```tsx
+/**
+ * Don't example for "Always Render Combobox.Empty" on the Combobox page.
+ * Don't leave it out. The popup opens blank and announces nothing.
+ * @module
+ */
+import { Combobox, style } from '@tempoxyz/ds'
+
+const assets = ['pathUSD', 'USDC.e', 'USDT0']
+
+// The popup portals and opens on input, so a static copy shows it open.
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.column()}>
+      <Combobox.Root defaultInputValue="EURC" items={assets}>
+        <Combobox.InputGroup>
+          <Combobox.Input aria-label="Asset" />
+          <Combobox.Trigger />
+        </Combobox.InputGroup>
+      </Combobox.Root>
+      <div {...styles.popup()} />
+    </div>
+  )
+}
+
+namespace styles {
+  export const column = style({
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '8',
+    maxWidth: '16rem !custom',
+    width: '100% !custom',
+  })
+
+  export const popup = style({
+    backgroundColor: 'background.elevated',
+    borderRadius: 'sm',
+    boxShadow: 'regular',
+    padding: '6px !custom',
+  })
+}
+```
+
+### Show What Identifies Each Item
+
+* **`Combobox.ItemText`:** The searchable name, such as the symbol USDC.e.
+* **`Combobox.ItemPrefix`:** A token icon.
+* **`Combobox.ItemSuffix`:** Detail that informs the choice, such as a balance.
+
+**Do:** Show the symbol, its icon, and the balance.
+
+```tsx
+/**
+ * Do example for "Show What Identifies Each Item" on the Combobox page.
+ * Show the symbol, its icon, and the balance.
+ * @module
+ */
+import pathusd from '../../coins/PathUSD.svg'
+import usdce from '../../coins/USDCe.svg'
+import usdt0 from '../../coins/USDT0.svg'
+import { style } from '@tempoxyz/ds'
+
+const assets = [
+  { balance: '1,250.00', icon: usdce, symbol: 'USDC.e' },
+  { balance: '80.50', icon: pathusd, symbol: 'pathUSD' },
+  { balance: '0.00', icon: usdt0, symbol: 'USDT0' },
+]
+
+// A static copy of the open popup, since the real one portals and opens on input.
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.popup()}>
+      {assets.map((asset) => (
+        <div key={asset.symbol} {...styles.item()}>
+          <img alt="" height={20} src={asset.icon} width={20} />
+          {asset.symbol}
+          <span {...styles.suffix()}>{asset.balance}</span>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const item = style({
+    alignItems: 'center',
+    display: 'flex',
+    gap: '8',
+    minHeight: '40',
+    paddingInline: '16',
+    typography: 'body.b2Strong',
+  })
+
+  export const popup = style({
+    backgroundColor: 'background.elevated',
+    borderRadius: 'sm',
+    boxShadow: 'regular',
+    padding: '6px !custom',
+    width: '16rem !custom',
+  })
+
+  export const suffix = style({
+    color: 'content.secondary',
+    marginInlineStart: 'auto !custom',
+    typography: 'body.b3',
+  })
+}
+```
+
+**Don't:** List contract addresses as item text.
+
+```tsx
+/**
+ * Don't example for "Show What Identifies Each Item" on the Combobox page.
+ * Don't list contract addresses as item text.
+ * @module
+ */
+import { style } from '@tempoxyz/ds'
+
+const assets = ['0x20c0…0001', '0x20c0…0002', '0x20c0…0003']
+
+// A static copy of the open popup, since the real one portals and opens on input.
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.popup()}>
+      {assets.map((address) => (
+        <div key={address} {...styles.item()}>
+          {address}
+        </div>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const item = style({
+    alignItems: 'center',
+    display: 'flex',
+    gap: '8',
+    minHeight: '40',
+    paddingInline: '16',
+    typography: 'body.b2Strong',
+  })
+
+  export const popup = style({
+    backgroundColor: 'background.elevated',
+    borderRadius: 'sm',
+    boxShadow: 'regular',
+    padding: '6px !custom',
+    width: '16rem !custom',
+  })
+}
+```
+
+### Offer a Way to Browse
+
+`Combobox.Clear` mounts only while there is a value.
+
+**Do:** Add `Combobox.Trigger` to open the full list, and `Combobox.Clear` if the value can be emptied.
+
+```tsx
+/**
+ * Do example for "Offer a Way to Browse" on the Combobox page.
+ * Add `Combobox.Trigger` to open the full list, and `Combobox.Clear` if the value can be emptied.
+ * @module
+ */
+import { Combobox, Field, style } from '@tempoxyz/ds'
+
+const countries = ['Germany', 'Singapore', 'United States']
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <Field.Label>Country</Field.Label>
+      <Combobox.Root defaultValue="Singapore" items={countries}>
+        <Combobox.InputGroup>
+          <Combobox.Input placeholder="Search countries" />
+          <Combobox.Clear />
+          <Combobox.Trigger />
+        </Combobox.InputGroup>
+      </Combobox.Root>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ maxWidth: '16rem !custom', width: '100% !custom' })
+}
+```
+
+**Don't:** Make typing the only way to see the options.
+
+```tsx
+/**
+ * Don't example for "Offer a Way to Browse" on the Combobox page.
+ * Don't make typing the only way to see the options.
+ * @module
+ */
+import { Combobox, Field, style } from '@tempoxyz/ds'
+
+const countries = ['Germany', 'Singapore', 'United States']
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <Field.Label>Country</Field.Label>
+      <Combobox.Root defaultValue="Singapore" items={countries}>
+        <Combobox.InputGroup>
+          <Combobox.Input placeholder="Search countries" />
+        </Combobox.InputGroup>
+      </Combobox.Root>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ maxWidth: '16rem !custom', width: '100% !custom' })
+}
+```
+
+### Group Long Lists
+
+Name each `Combobox.Group` with a `Combobox.GroupLabel`, and divide groups with `Combobox.Separator`. Put the most-chosen items first.
+
+**Do:** Split a long list into named sections, such as Stablecoins.
+
+```tsx
+/**
+ * Do example for "Group Long Lists" on the Combobox page.
+ * Split a long list into named sections, such as Stablecoins.
+ * @module
+ */
+import { style } from '@tempoxyz/ds'
+
+// A static copy of the open popup, since the real one portals and opens on input.
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.popup()}>
+      <div {...styles.label()}>Stablecoins</div>
+      <div {...styles.item()}>pathUSD</div>
+      <div {...styles.item()}>USDC.e</div>
+      <div {...styles.separator()} />
+      <div {...styles.label()}>Other assets</div>
+      <div {...styles.item()}>cbBTC</div>
+      <div {...styles.item()}>ETH</div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const item = style({
+    alignItems: 'center',
+    display: 'flex',
+    minHeight: '40',
+    paddingInline: '16',
+    typography: 'body.b2Strong',
+  })
+
+  export const label = style({
+    color: 'content.secondary',
+    paddingBlock: '8',
+    paddingInline: '16',
+    typography: 'body.b3',
+  })
+
+  export const popup = style({
+    backgroundColor: 'background.elevated',
+    borderRadius: 'sm',
+    boxShadow: 'regular',
+    padding: '6px !custom',
+    width: '16rem !custom',
+  })
+
+  export const separator = style({
+    backgroundColor: 'container.strong',
+    height: '1',
+    marginBlock: '8',
+    marginInline: '16',
+  })
+}
+```
+
+**Don't:** Mix unrelated kinds of items in one flat list.
+
+```tsx
+/**
+ * Don't example for "Group Long Lists" on the Combobox page.
+ * Don't mix unrelated kinds of items in one flat list.
+ * @module
+ */
+import { style } from '@tempoxyz/ds'
+
+// A static copy of the open popup, since the real one portals and opens on input.
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.popup()}>
+      <div {...styles.item()}>cbBTC</div>
+      <div {...styles.item()}>pathUSD</div>
+      <div {...styles.item()}>ETH</div>
+      <div {...styles.item()}>USDC.e</div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const item = style({
+    alignItems: 'center',
+    display: 'flex',
+    minHeight: '40',
+    paddingInline: '16',
+    typography: 'body.b2Strong',
+  })
+
+  export const popup = style({
+    backgroundColor: 'background.elevated',
+    borderRadius: 'sm',
+    boxShadow: 'regular',
+    padding: '6px !custom',
+    width: '16rem !custom',
+  })
+}
+```
+
+### Expose Errors on the Input
+
+**Do:** Set `aria-invalid` on `Combobox.Input`, and explain the problem in a `Field.Error`.
+
+```tsx
+/**
+ * Do example for "Expose Errors on the TextInput" on the Combobox page.
+ * Set `aria-invalid` on `Combobox.Input`, and explain the problem in a `Field.Error`.
+ * @module
+ */
+import { Combobox, Field, style } from '@tempoxyz/ds'
+
+const assets = ['pathUSD', 'USDC.e', 'USDT0']
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root invalid {...styles.field()}>
+      <Field.Label>Asset</Field.Label>
+      <Combobox.Root items={assets}>
+        <Combobox.InputGroup invalid>
+          <Combobox.Input aria-invalid placeholder="Search assets" />
+          <Combobox.Trigger />
+        </Combobox.InputGroup>
+      </Combobox.Root>
+      <Field.Error match>Select an asset to send</Field.Error>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ maxWidth: '16rem !custom', width: '100% !custom' })
+}
+```
+
+**Don't:** Rely on `invalid` on `Combobox.InputGroup`. It only styles the frame.
+
+```tsx
+/**
+ * Don't example for "Expose Errors on the TextInput" on the Combobox page.
+ * Don't rely on `invalid` on `Combobox.InputGroup`. It only styles the frame.
+ * @module
+ */
+import { Combobox, Field, style } from '@tempoxyz/ds'
+
+const assets = ['pathUSD', 'USDC.e', 'USDT0']
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <Field.Label>Asset</Field.Label>
+      <Combobox.Root items={assets}>
+        <Combobox.InputGroup invalid>
+          <Combobox.Input placeholder="Search assets" />
+          <Combobox.Trigger />
+        </Combobox.InputGroup>
+      </Combobox.Root>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ maxWidth: '16rem !custom', width: '100% !custom' })
+}
+```
+
+## Content
+
+* **Label:** The noun the value names, such as Asset, Network, or Country.
+* **Placeholder:** What people can search by, such as Search by name or symbol.
+* **Items:** The names and symbols from the token list, with the same casing everywhere.
+
+## Accessibility
+
+Follows the [WAI-ARIA combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) with list autocomplete.
+
+### Semantics
+
+* **Combobox.Input (combobox):** A text input that announces an option list and whether it is open.
+* **Highlighted Option (aria-activedescendant):** Points to the highlighted option while focus stays in the input.
+* **Combobox.List and Combobox.Item (listbox):** Each item is an option with a check mark while selected.
+* **Combobox.Trigger and Combobox.Clear (button):** Named "Show options" and "Clear", both out of the tab order. Clear renders only with a value.
+* **Combobox.Chips (toolbar):** With `multiple`, arrow keys move between chips. Each remove button is named "Remove".
+
+### Keyboard
+
+* **Move Focus to the TextInput (Tab):** Moves focus to the input.
+* **Filter the Options (Typing):** Filters the options and opens the list.
+* **Open or Move Down (Down Arrow):** Opens the list, or highlights the next option.
+* **Move Up (Up Arrow):** Highlights the previous option.
+* **Select an Option (Enter):** Selects the highlighted option and closes the list. With `multiple`, toggles it instead.
+* **Close the List (Escape):** Closes the popup.
+* **Move to the Chips (Left Arrow):** With `multiple`, from the start of the input, focuses the last chip. Arrows move between chips.
+* **Remove a Chip (Backspace):** With `multiple`, removes the focused chip, or the last chip from an empty input.
+
+### Focus
+
+DOM focus stays on the input while the arrow keys move the highlight. Chips take focus only through the arrow keys, not Tab.
+
+### Announcements
+
+* **Highlighted Option (aria-activedescendant):** Screen readers announce each option on highlight.
+* **Empty Results (status):** Announces a query without matches.
+
+### Your Responsibilities
+
+* **Name Chips in Multiple Mode (aria-label):** Name the chips, such as "Selected assets", and each remove button by its value, such as "Remove USDC".
+* **Hide Item Icons (alt):** Leave item icon alt text empty. The item text names the item.
+
+## Related
+
+[Autocomplete](/docs/components/autocomplete)
+
+Use for free text with suggestions.
+
+[Select](/docs/components/select)
+
+Use for short lists.
+
+[Field](/docs/components/field)
+
+Use for the label and error.
+
+[TokenLogo](/docs/components/token-logo)
+
+Use for token icons in items.
+
+[Blockchain Values](/docs/patterns/blockchain-values)
+
+Covers showing assets and addresses.