@duro-app/ui 5.0.0 → 5.2.0

package/src/components/Dialog/Dialog.tsx

@@ -14,9 +14,13 @@ import {html} from 'react-strict-dom'
 import {DURATION_MS, type DurationToken} from '@duro-app/tokens/keys'
 import {styles} from './styles.css'
 import {usePortalMount} from '../ThemeProvider/ThemeProvider'
+import {devWarnOnce} from '../../shared/devWarnOnce'
 
 // --- Types ---
 
+const FOCUSABLE =
+  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+
 export type DialogSize = 'sm' | 'md' | 'lg'
 
 const closeDurationMap = {
@@ -41,6 +45,8 @@ interface DialogContextValue {
   titleId: string
   descriptionId: string
   popupRef: RefObject<HTMLDivElement | null>
+  /** Dialog.Close parts currently rendered (for the closeOnEscape dev warning). */
+  registerClose: () => () => void
 }
 
 const DialogContext = createContext<DialogContextValue | null>(null)
@@ -61,8 +67,16 @@ interface RootProps {
   defaultOpen?: boolean
   /** Called when dialog open state changes */
   onOpenChange?: (open: boolean) => void
-  /** Whether clicking backdrop closes the dialog. Default: true */
+  /** Whether clicking the backdrop closes the dialog. Default: true */
   dismissable?: boolean
+  /**
+   * Whether Escape closes the dialog. Default: true, also when `dismissable`
+   * is false. Turning it off leaves the keyboard no way out but a
+   * Dialog.Close, so render one.
+   */
+  closeOnEscape?: boolean
+  /** Element to focus on open. Default: the first focusable element, else the dialog itself. */
+  initialFocus?: RefObject<HTMLElement | null>
   /** Motion token for the close animation. Default: 'fast' (150ms) */
   closeAnimationDuration?: DurationToken
 }
@@ -73,6 +87,8 @@ function Root({
   defaultOpen = false,
   onOpenChange,
   dismissable = true,
+  closeOnEscape = true,
+  initialFocus,
   closeAnimationDuration = 'fast',
 }: RootProps) {
   const isControlled = controlledOpen !== undefined
@@ -120,20 +136,55 @@ function Root({
     }
   }, [])
 
-  // Handle Escape key
+  // Handle Escape key. A layer inside the dialog (a Menu, a Select) that
+  // already handled it marks the event, and the dialog stays open.
   useEffect(() => {
     if (!isOpen && !closing) return
-    if (!dismissable) return
+    if (!closeOnEscape) return
 
     function onKeyDown(e: KeyboardEvent) {
-      if (e.key === 'Escape') {
-        e.stopPropagation()
-        requestClose()
-      }
+      if (e.key !== 'Escape' || e.defaultPrevented) return
+      e.stopPropagation()
+      requestClose()
     }
     document.addEventListener('keydown', onKeyDown)
     return () => document.removeEventListener('keydown', onKeyDown)
-  }, [isOpen, closing, dismissable, requestClose])
+  }, [isOpen, closing, closeOnEscape, requestClose])
+
+  // Focus: into the dialog on open (initialFocus, else the first focusable
+  // element, else the dialog itself), back to what had it on close. The
+  // Portal is a descendant, so its popup is mounted when this effect runs.
+  const closeCountRef = useRef(0)
+  const registerClose = useCallback(() => {
+    closeCountRef.current += 1
+    return () => {
+      closeCountRef.current -= 1
+    }
+  }, [])
+  const previousFocusRef = useRef<HTMLElement | null>(null)
+  const wasOpenRef = useRef(false)
+  useEffect(() => {
+    if (isOpen && !wasOpenRef.current) {
+      previousFocusRef.current = document.activeElement as HTMLElement | null
+      const popup = popupRef.current
+      if (popup) {
+        const target = initialFocus?.current ?? popup.querySelector<HTMLElement>(FOCUSABLE) ?? popup
+        target.focus({preventScroll: true})
+      }
+      if (!closeOnEscape && closeCountRef.current === 0) {
+        devWarnOnce(
+          'Dialog',
+          'no-escape-no-close',
+          'Dialog.Root has closeOnEscape={false} and no Dialog.Close: a keyboard user cannot leave this dialog. Render a Dialog.Close, or keep Escape.',
+        )
+      }
+    } else if (!isOpen && !closing && wasOpenRef.current) {
+      const target = previousFocusRef.current
+      previousFocusRef.current = null
+      if (target?.isConnected) target.focus({preventScroll: true})
+    }
+    wasOpenRef.current = isOpen || closing
+  }, [isOpen, closing, initialFocus, closeOnEscape])
 
   // Lock body scroll when open
   useEffect(() => {
@@ -158,6 +209,7 @@ function Root({
         titleId,
         descriptionId,
         popupRef,
+        registerClose,
       }}
     >
       {children}
@@ -229,6 +281,7 @@ function Portal({children, size = 'md'}: PortalProps) {
           ref={popupRef}
           role="dialog"
           aria-modal={true}
+          tabIndex={-1}
           aria-labelledby={titleId}
           aria-describedby={descriptionId}
           style={[
@@ -301,7 +354,8 @@ interface CloseProps {
 }
 
 function Close({children, 'aria-label': ariaLabel = 'Close'}: CloseProps) {
-  const {requestClose} = useDialog()
+  const {requestClose, registerClose} = useDialog()
+  useEffect(() => registerClose(), [registerClose])
 
   if (children) {
     return (

package/src/components/Dialog/styles.css.ts

@@ -64,6 +64,8 @@ export const styles = css.create({
     flexDirection: 'column',
     overflow: 'hidden',
     pointerEvents: 'auto',
+    // Focused only as the fallback when it holds nothing focusable.
+    outlineStyle: 'none',
     borderWidth: borders.hairline,
     borderStyle: 'solid',
     borderColor: colors.border,

package/src/components/DragDrop/styles.css.ts

@@ -2,6 +2,8 @@ import {css} from 'react-strict-dom'
 import {colors} from '@duro-app/tokens/tokens/colors.css'
 import {radii} from '@duro-app/tokens/tokens/spacing.css'
 import {duration, easing} from '@duro-app/tokens/tokens/motion.css'
+import {shadows} from '@duro-app/tokens/tokens/shadows.css'
+import {borders} from '@duro-app/tokens/tokens/borders.css'
 
 export const styles = css.create({
   // The item is the drag handle: no browser panning starts on it, so a touch
@@ -30,13 +32,24 @@ export const styles = css.create({
     transitionTimingFunction: easing.standard,
   },
   // Every zone shows it can receive while something is in the air; the one
-  // under the pointer lights up.
+  // under the pointer lights up. Drop-target rings, not focus: keyboard focus
+  // stays on outlines, which survive forced-colors mode.
+  // Forced-colors mode drops box-shadows and fills; the transparent outline
+  // is what it paints instead (in a system colour), so the rings survive.
   zoneReady: {
-    boxShadow: `inset 0 0 0 1px ${colors.border}`,
+    boxShadow: shadows.dropReady,
+    outlineStyle: 'solid',
+    outlineWidth: borders.hairline,
+    outlineColor: 'transparent',
+    outlineOffset: `calc(-1 * ${borders.hairline})`,
   },
   zoneOver: {
-    boxShadow: `inset 0 0 0 2px ${colors.accent}`,
+    boxShadow: shadows.dropOver,
     backgroundColor: colors.infoBg,
+    outlineStyle: 'solid',
+    outlineWidth: borders.strong,
+    outlineColor: 'transparent',
+    outlineOffset: `calc(-1 * ${borders.strong})`,
   },
   ghost: {
     position: 'fixed',

package/src/components/Grid/Grid.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Grid layout. Columns are a count (1-6), a list of weights ([1, 2] for one-third / two-thirds), responsive auto-fit via minColumnWidth, or a named split layout (list/detail, nav/content) that collapses to one column on the width of its own container, so it is safe to nest and to place beside a DetailPanel. Weights rather than CSS template strings, so the same props render as CSS grid on web and as a wrapping flex row on native.',
+    "Grid layout. Columns are a count (1-6), a list of weights ([1, 2] for one-third / two-thirds), responsive auto-fit via minColumnWidth, or a named split layout (list/detail, nav/content) that collapses to one column on the width of its own container, so it is safe to nest and to place beside a DetailPanel. Weights rather than CSS template strings, so the same props render as CSS grid on web and as a wrapping flex row on native. For a fixed track beside fractions (content + a 320px aside), tracks takes a token track list — tracks={['1fr', 'asideW']} — web only, equal columns on native.",
   whenToUse: [
     'Card grids, dashboard layouts, multi-column forms',
     'Responsive layouts that should auto-adjust column count',

package/src/components/Grid/Grid.stories.tsx

@@ -5,7 +5,8 @@ import {Grid} from './Grid'
 import {Stack} from '../Stack/Stack'
 import {colors} from '@duro-app/tokens/tokens/colors.css'
 import {spacing, radii} from '@duro-app/tokens/tokens/spacing.css'
-import {SPACING_KEYS} from '@duro-app/tokens/keys'
+import {SIZES_PX, SPACING_KEYS} from '@duro-app/tokens/keys'
+import {sizes} from '@duro-app/tokens/tokens/sizes.css'
 import {useContainerQuery} from '../../hooks/useContainerQuery'
 import {typography} from '@duro-app/tokens/tokens/typography.css'
 import {borders} from '@duro-app/tokens/tokens/borders.css'
@@ -209,3 +210,54 @@ export const WithContainerQuery: Story = {
     )
   },
 }
+
+// A track list with a fixed aside: the content column takes the rest, the
+// aside is sizes.asideW.
+export const TracksWithAside: Story = {
+  render: () => (
+    <html.div style={trackStyles.frame}>
+      <Grid tracks={['1fr', 'asideW']} gap="md">
+        <html.div role="region" aria-label="Content" style={trackStyles.cell}>
+          Content
+        </html.div>
+        <html.div role="region" aria-label="Aside" style={trackStyles.cell}>
+          Aside
+        </html.div>
+      </Grid>
+    </html.div>
+  ),
+  play: async ({canvas}) => {
+    const aside = canvas.getByRole('region', {name: 'Aside'})
+    await expect(aside.getBoundingClientRect().width).toBe(SIZES_PX.asideW)
+    const content = canvas.getByRole('region', {name: 'Content'})
+    await expect(content.getBoundingClientRect().width).toBeGreaterThan(SIZES_PX.asideW)
+  },
+}
+
+export const TracksWithMinmax: Story = {
+  render: () => (
+    <html.div style={trackStyles.frame}>
+      <Grid tracks={['minmax(gridColXs, 1fr)', 'minmax(gridColXs, 1fr)', 'minmax(gridColXs, 1fr)']}>
+        <html.div style={trackStyles.cell}>One</html.div>
+        <html.div style={trackStyles.cell}>Two</html.div>
+        <html.div role="region" aria-label="Three" style={trackStyles.cell}>
+          Three
+        </html.div>
+      </Grid>
+    </html.div>
+  ),
+  play: async ({canvas}) => {
+    const third = canvas.getByRole('region', {name: 'Three'})
+    await expect(third.getBoundingClientRect().width).toBeGreaterThanOrEqual(SIZES_PX.gridColXs)
+  },
+}
+
+const trackStyles = css.create({
+  frame: {
+    width: sizes.pageMd,
+  },
+  cell: {
+    padding: spacing.sm,
+    backgroundColor: colors.bgCard,
+  },
+})

package/src/components/Grid/Grid.tsx

@@ -4,7 +4,7 @@ import {styles} from './styles.css'
 import {isNative} from '../../platform'
 import {cellBasis, cellPosition, columnWeights, gridTemplate, type GridColumns} from './columns'
 import type {SpacingToken} from '@duro-app/tokens/keys'
-import {resolveLength, type Length} from '../../shared/length'
+import {resolveLength, resolveTrack, type GridTrack, type Length} from '../../shared/length'
 
 export type GridLayout = 'split' | 'split-wide'
 
@@ -28,6 +28,15 @@ interface GridProps {
    * rather than when the window does. Wins over `columns` / `minColumnWidth`.
    */
   layout?: GridLayout
+  /**
+   * An explicit track list, for columns that are not all fractions: a size
+   * token for a fixed track (`['1fr', 'asideW']`), or `minmax()` /
+   * `fit-content()` of tokens and fractions (`'minmax(gridColXs, 1fr)'`).
+   * A px is a type error. Web only — on native it falls back to equal
+   * columns, one per track. Wins over `columns` / `minColumnWidth`; `layout`
+   * wins over it.
+   */
+  tracks?: readonly GridTrack[]
   children: ReactNode
 }
 
@@ -87,13 +96,14 @@ const cellGapTopMap = {
   xxxl: styles.cellGapTopXxxl,
 } as const satisfies Record<SpacingToken, unknown>
 
-export function Grid({gap = 'md', columns, minColumnWidth, layout, children}: GridProps) {
+export function Grid({gap = 'md', columns, minColumnWidth, layout, tracks, children}: GridProps) {
+  const hasTracks = tracks !== undefined && tracks.length > 0
   if (isNative) {
     return (
       <NativeGrid
         gap={gap}
-        columns={layout ? layoutWeights[layout] : columns}
-        minColumnWidth={layout ? undefined : minColumnWidth}
+        columns={layout ? layoutWeights[layout] : hasTracks ? tracks.map(() => 1) : columns}
+        minColumnWidth={layout || hasTracks ? undefined : minColumnWidth}
       >
         {children}
       </NativeGrid>
@@ -102,13 +112,15 @@ export function Grid({gap = 'md', columns, minColumnWidth, layout, children}: Gr
 
   const columnStyle = layout
     ? layoutMap[layout]
-    : minColumnWidth
-      ? styles.autoFit(resolveLength(minColumnWidth))
-      : typeof columns === 'number'
-        ? columnsMap[columns]
-        : columns
-          ? styles.template(gridTemplate(columnWeights(columns) ?? [1]))
-          : undefined
+    : hasTracks
+      ? styles.template(tracks.map((track) => String(resolveTrack(track))).join(' '))
+      : minColumnWidth
+        ? styles.autoFit(resolveLength(minColumnWidth))
+        : typeof columns === 'number'
+          ? columnsMap[columns]
+          : columns
+            ? styles.template(gridTemplate(columnWeights(columns) ?? [1]))
+            : undefined
 
   const grid = <html.div style={[styles.base, gapMap[gap], columnStyle]}>{children}</html.div>
   // A named layout answers its container query from a wrapper: an element

package/src/components/Grid/styles.css.ts

@@ -1,6 +1,7 @@
 import {css} from 'react-strict-dom'
 import {spacing} from '@duro-app/tokens/tokens/spacing.css'
 import {breakpoints} from '@duro-app/tokens/tokens/breakpoints.css'
+import {sizes} from '@duro-app/tokens/tokens/sizes.css'
 
 // Where a split collapses to one column — measured on the split's OWN
 // container, not the viewport. A split nested in another split (a list/detail
@@ -40,13 +41,13 @@ export const styles = css.create({
   split: {
     gridTemplateColumns: {
       default: '1fr',
-      [`@container (min-width: ${SPLIT_BP})`]: 'minmax(240px, 1fr) minmax(0, 2fr)',
+      [`@container (min-width: ${SPLIT_BP})`]: `minmax(${sizes.gridColSm}, 1fr) minmax(0, 2fr)`,
     },
   },
   splitWide: {
     gridTemplateColumns: {
       default: '1fr',
-      [`@container (min-width: ${SPLIT_WIDE_BP})`]: 'minmax(280px, 1fr) minmax(0, 3fr)',
+      [`@container (min-width: ${SPLIT_WIDE_BP})`]: `minmax(${sizes.gridColMd}, 1fr) minmax(0, 3fr)`,
     },
   },
   // Weighted columns: `[1, 2]` → `1fr 2fr` (see columns.ts).

package/src/components/Input/Input.meta.ts

@@ -2,9 +2,16 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Text input with automatic Field/Form integration. Variant auto-switches to error when inside an invalid Field.',
-  whenToUse: ['Single-line text entry (text, email, password, url, tel, number, search)'],
-  whenNotToUse: ['Multi-line text — use Textarea', 'Picking from predefined options — use Select'],
+    'Text input with automatic Field/Form integration. Variant auto-switches to error when inside an invalid Field. variant="ghost" reads as text until hovered (hairline border) or focused (accent border and ring): only for inline edit where a visible Field.Label names it; it shows the error state when the Field is invalid.',
+  whenToUse: [
+    'Single-line text entry (text, email, password, url, tel, number, search)',
+    'Inline edit of a labelled value in place (a ticket title) — variant="ghost"',
+  ],
+  whenNotToUse: [
+    'Multi-line text — use Textarea',
+    'Picking from predefined options — use Select',
+    'A ghost field without a visible label — it reads as plain text, so the label is what says it is editable',
+  ],
   relatedTo: [
     {component: 'Field', kind: 'composition', relationship: 'Wrap in Field.Root for label + error'},
     {

package/src/components/Input/Input.stories.tsx

@@ -1,7 +1,9 @@
 import type {Meta, StoryObj} from '@storybook/react'
-import {expect, fn} from 'storybook/test'
+import {expect, fn, waitFor} from 'storybook/test'
 import {css, html} from 'react-strict-dom'
 import {Input} from './Input'
+import {Field} from '../Field/Field'
+import {Stack} from '../Stack/Stack'
 import {spacing} from '@duro-app/tokens/tokens/spacing.css'
 import {sizes} from '@duro-app/tokens/tokens/sizes.css'
 
@@ -14,7 +16,7 @@ const meta: Meta<typeof Input> = {
   argTypes: {
     variant: {
       control: 'select',
-      options: ['default', 'error'],
+      options: ['default', 'error', 'ghost'],
     },
     type: {
       control: 'select',
@@ -105,3 +107,51 @@ export const AllVariants: Story = {
     await expect(disabled).toBeDisabled()
   },
 }
+
+// --- Ghost (5.2, direction OutlineOnHover) ---
+
+export const GhostInlineEdit: Story = {
+  render: () => (
+    <html.div style={layoutStyles.narrow}>
+      <Stack gap="md">
+        <Field.Root>
+          <Field.Label>Title</Field.Label>
+          <Input variant="ghost" defaultValue="Printer on floor 3 is jammed" />
+        </Field.Root>
+        <Field.Root invalid>
+          <Field.Label>Assignee</Field.Label>
+          <Input variant="ghost" defaultValue="" />
+          <Field.Error>Assignee is required</Field.Error>
+        </Field.Root>
+        <Field.Root disabled>
+          <Field.Label>Due</Field.Label>
+          <Input variant="ghost" defaultValue="Friday" />
+        </Field.Root>
+      </Stack>
+    </html.div>
+  ),
+  play: async ({canvas, userEvent}) => {
+    const title = canvas.getByRole('textbox', {name: 'Title'})
+    // Reads as text at rest: no border colour, no fill.
+    await expect(getComputedStyle(title).borderTopColor).toBe('rgba(0, 0, 0, 0)')
+    await userEvent.click(title)
+    await userEvent.keyboard('{Shift>}{Tab}{/Shift}{Tab}')
+    await expect(title).toHaveFocus()
+    await expect(getComputedStyle(title).outlineStyle).toBe('solid')
+    // The border colour transitions in (duration.fast).
+    await waitFor(() => expect(getComputedStyle(title).borderTopColor).not.toBe('rgba(0, 0, 0, 0)'))
+
+    const assignee = canvas.getByRole('textbox', {name: 'Assignee'})
+    await expect(assignee).toHaveAttribute('aria-invalid', 'true')
+    await expect(getComputedStyle(assignee).backgroundColor).not.toBe('rgba(0, 0, 0, 0)')
+
+    await expect(canvas.getByRole('textbox', {name: 'Due'})).toBeDisabled()
+  },
+}
+
+const layoutStyles = css.create({
+  narrow: {
+    maxWidth: sizes.panelSm,
+    padding: spacing.md,
+  },
+})

package/src/components/Input/Input.tsx

@@ -6,9 +6,14 @@ import {styles} from './styles.css'
 type StrictInputProps = React.ComponentProps<typeof html.input>
 export type InputType = NonNullable<StrictInputProps['type']>
 
-export type InputVariant = 'default' | 'error'
+export type InputVariant = 'default' | 'error' | 'ghost'
 
 interface InputProps {
+  /**
+   * `ghost` reads as text until hovered or focused — only for inline edit
+   * where a visible label names the field (Field.Label). It shows the error
+   * state when the Field is invalid.
+   */
   variant?: InputVariant
   /** Orthogonal to variant — `mono` keeps the error border but uses the
    *  monospace family (slugs, identifiers, hashes). */
@@ -100,7 +105,9 @@ export function Input({
   const effectiveOnBlur = onBlur ?? fieldCtx?.onBlur
   const effectiveRef = ref ?? fieldCtx?.ref
   const effectiveDisabled = disabled ?? ctx?.disabled
-  const effectiveVariant = ctx?.invalid ? 'error' : variant
+  const invalid = Boolean(ctx?.invalid) || variant === 'error'
+  const ghost = variant === 'ghost'
+  const effectiveVariant = ghost ? 'ghost' : ctx?.invalid ? 'error' : variant
   // Field context owns describedby (description + error); fall back to the
   // explicit prop only when standalone.
   const describedBy = ctx
@@ -134,7 +141,7 @@ export function Input({
       defaultValue={defaultValue}
       disabled={effectiveDisabled}
       aria-describedby={describedBy || undefined}
-      aria-invalid={ctx?.invalid || variant === 'error' || undefined}
+      aria-invalid={invalid || undefined}
       onChange={effectiveOnChange as StrictInputProps['onChange']}
       onBlur={effectiveOnBlur as StrictInputProps['onBlur']}
       onFocus={onFocus as StrictInputProps['onFocus']}
@@ -144,6 +151,8 @@ export function Input({
       style={[
         styles.base,
         styles[effectiveVariant],
+        ghost && invalid && styles.ghostError,
+        ghost && effectiveDisabled && styles.ghostDisabled,
         font === 'mono' && styles.mono,
         groupCtx?.inGroup && styles.inGroup,
       ]}

package/src/components/Input/styles.css.ts

@@ -53,6 +53,35 @@ export const styles = css.create({
       ':focus': colors.error,
     },
   },
+  // Direction OutlineOnHover (docs/mockups/input-ghost/OutlineOnHover.dc.html):
+  // reads as text at rest; hover draws the field's hairline border, focus
+  // turns it accent and adds the ring. For inline edit with a visible label.
+  ghost: {
+    backgroundColor: 'transparent',
+    paddingTop: spacing.xs,
+    paddingBottom: spacing.xs,
+    paddingLeft: spacing.sm,
+    paddingRight: spacing.sm,
+    // The text lines up with its label above.
+    marginLeft: `calc(-1 * ${spacing.sm})`,
+    borderColor: {
+      default: 'transparent',
+      ':hover': colors.border,
+      ':focus': colors.accent,
+    },
+  },
+  ghostError: {
+    backgroundColor: colors.errorBg,
+    borderColor: {
+      default: colors.errorBorder,
+      ':focus': colors.error,
+    },
+  },
+  ghostDisabled: {
+    color: colors.textMuted,
+    cursor: 'not-allowed',
+    borderColor: 'transparent',
+  },
   inGroup: {
     borderWidth: 0,
     borderRadius: 0,

package/src/components/InputGroup/InputGroup.stories.tsx

@@ -140,3 +140,23 @@ export const AllVariants: Story = {
     </html.div>
   ),
 }
+
+const onSearch = fn()
+
+// An icon-only clickable addon is a button: aria-label gives it its name.
+export const IconAddonNamed: Story = {
+  render: () => (
+    <html.div style={layoutStyles.container}>
+      <InputGroup.Root>
+        <Input placeholder="Search tickets" aria-label="Search tickets" />
+        <InputGroup.Addon onClick={onSearch} aria-label="Run search">
+          <Icon name="search" size="sm" />
+        </InputGroup.Addon>
+      </InputGroup.Root>
+    </html.div>
+  ),
+  play: async ({canvas, userEvent}) => {
+    await userEvent.click(canvas.getByRole('button', {name: 'Run search'}))
+    await expect(onSearch).toHaveBeenCalled()
+  },
+}

package/src/components/InputGroup/InputGroup.tsx

@@ -33,10 +33,22 @@ interface AddonProps {
   /** Optional minimum width to prevent layout shift (e.g. Copy → Copied!): a
    *  size token key or a relative length. */
   minWidth?: Length
+  /**
+   * Accessible name of a clickable addon (it renders a button). Required when
+   * its content is an icon (copy, reveal): without it the button has no name.
+   */
+  'aria-label'?: string
   children: ReactNode
 }
 
-function Addon({position = 'end', onClick, disabled, minWidth, children}: AddonProps) {
+function Addon({
+  position = 'end',
+  onClick,
+  disabled,
+  minWidth,
+  'aria-label': ariaLabel,
+  children,
+}: AddonProps) {
   const positionStyle = position === 'start' ? styles.addonStart : styles.addonEnd
   const style = [
     styles.addon,
@@ -49,7 +61,13 @@ function Addon({position = 'end', onClick, disabled, minWidth, children}: AddonP
 
   if (onClick) {
     return (
-      <html.button type="button" onClick={onClick} disabled={disabled} style={style}>
+      <html.button
+        type="button"
+        onClick={onClick}
+        disabled={disabled}
+        aria-label={ariaLabel}
+        style={style}
+      >
         {children}
       </html.button>
     )

package/src/components/Listbox/Listbox.meta.ts

@@ -0,0 +1,52 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Popup list of options for an input that keeps focus — an editor typeahead (mentions, slash commands) or a custom combobox. The anchor owns focus and the keyboard: it sets the controlled highlightedId and spreads Listbox.getAnchorProps() for aria-controls / aria-expanded / aria-activedescendant. A press on an option never takes focus from the anchor. Portalled and placed against anchor() (an input rect or a caret rect), capped at a size-token maxHeight (default listMaxH).',
+  whenToUse: [
+    'Typeahead inside a rich-text editor, where focus must stay in the editor',
+    'A custom combobox whose input is not Combobox.Input',
+  ],
+  whenNotToUse: [
+    'Picking a value from a filterable list in a form — use Combobox (built on Listbox)',
+    'A short fixed list — use Select',
+    'Actions — use Menu',
+  ],
+  anatomy: {
+    required: ['Root', 'Option'],
+    optional: ['Empty'],
+  },
+  relatedTo: [
+    {
+      component: 'Combobox',
+      kind: 'contrast',
+      relationship:
+        'Combobox is a ready-made input + Listbox; Listbox alone serves an anchor you own (an editor)',
+    },
+    {
+      component: 'Menu',
+      kind: 'contrast',
+      relationship:
+        'Menu takes focus and triggers actions; Listbox leaves focus on its anchor and offers values',
+    },
+  ],
+  example: `const id = useId()
+const [highlightedId, setHighlightedId] = useState<string | null>(null)
+const optionId = (value: string) => \`\${id}-\${value}\`
+// On the editor root: Object.entries(Listbox.getAnchorProps({id, open, highlightedId}))
+<Listbox.Root
+  id={id}
+  open={open}
+  anchor={() => caretRect()}
+  highlightedId={highlightedId}
+  onHighlight={setHighlightedId}
+  onSelect={(value) => insertMention(value)}
+  getOptionId={optionId}
+  aria-label="Mentions"
+>
+  {people.map((p) => (
+    <Listbox.Option key={p.id} value={p.id}>{p.name}</Listbox.Option>
+  ))}
+  {people.length === 0 && <Listbox.Empty>No match</Listbox.Empty>}
+</Listbox.Root>`,
+}