@duro-app/ui 5.26.0 → 5.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duro-app/ui",
-  "version": "5.26.0",
+  "version": "5.28.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -92,7 +92,7 @@
   "dependencies": {
     "@tanstack/react-virtual": "^3.14.13",
     "qrcode": "^1.5.4",
-    "@duro-app/tokens": "^5.26.0"
+    "@duro-app/tokens": "^5.28.0"
   },
   "devDependencies": {
     "@babel/preset-typescript": "^7.28.0",

package/src/components/CodeBlock/CodeBlock.meta.ts

@@ -2,10 +2,11 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'A block of code with a copy button: a pre that scrolls sideways when a line is long, and a Button that copies its text, shows the copied label for copiedDuration ms and announces it through a polite LiveRegion. Labels come from props. With language="diff", added, removed and hunk lines are coloured from tokens. On native the text is selectable and scrolls sideways; there is no copy button.',
+    'A block of code with a copy button: a pre that scrolls sideways when a line is long, and a Button that copies its text, shows the copied label for copiedDuration ms and announces it through a polite LiveRegion. Labels come from props. With language="diff", added, removed and hunk lines are coloured from tokens. On native the text is selectable and scrolls sideways; there is no copy button. A diff can carry a lineAction (a button beside each line inside a hunk, one tab stop, Up and Down between them; the line handed over has its old and new line numbers) and renderAfterLine (content under a line, full width: a review comment, an editor); the copied text stays the diff.',
   whenToUse: [
     'Code or a command the reader is likely to paste: a docs page, an install step',
     "A Markdown renderer's pre, inside Prose",
+    'A diff people comment on line by line (lineAction, renderAfterLine)',
   ],
   whenNotToUse: [
     'A short identifier in running text — use inline code (Prose styles it)',

package/src/components/CodeBlock/CodeBlock.native.tsx

@@ -2,6 +2,7 @@ import {ScrollView} from 'react-native'
 import {html} from 'react-strict-dom'
 import {typePresets} from '@duro-app/tokens/tokens/type-presets.css'
 import {DiffLines} from './DiffLines'
+import {DiffRows} from './DiffRows'
 import {textOf} from './diffRoles'
 import {styles} from './styles.css'
 import type {CodeBlockProps} from './types'
@@ -12,9 +13,19 @@ export type {CodeBlockProps} from './types'
  * Native CodeBlock: selectable monospace text that scrolls sideways, with the
  * same diff line roles as the web. The copy button is web only: a phone
  * copies by selecting the text, so the labels and `onCopyError` are unused.
+ * With a line action or content under lines, the diff is rows: each line's
+ * button and content as on the web (no arrow-key roving on a phone).
  */
-export function CodeBlock({children, language}: CodeBlockProps) {
+export function CodeBlock({children, language, lineAction, renderAfterLine}: CodeBlockProps) {
   const text = textOf(children)
+  if (language === 'diff' && (lineAction !== undefined || renderAfterLine !== undefined)) {
+    // Content under a line can hold its own controls, so the rows do not scroll sideways as one text.
+    return (
+      <html.div style={[styles.root, typePresets.code, styles.rows]}>
+        <DiffRows text={text} lineAction={lineAction} renderAfterLine={renderAfterLine} />
+      </html.div>
+    )
+  }
   return (
     <html.div style={styles.root}>
       <ScrollView horizontal>

package/src/components/CodeBlock/CodeBlock.stories.tsx

@@ -2,6 +2,9 @@ import type {Meta, StoryObj} from '@storybook/react'
 import {expect, fn, spyOn, waitFor} from 'storybook/test'
 import {css, html} from 'react-strict-dom'
 import {CodeBlock} from './CodeBlock'
+import type {DiffLineInfo} from './diffRoles'
+import {Card} from '../Card/Card'
+import {Text} from '../Text/Text'
 import {onThemeSurface} from '../../docs/themedSurface'
 import {withCoarsePointer, withFinePointer} from '../../docs/coarsePointer'
 import {SIZES_PX} from '@duro-app/tokens/keys'
@@ -244,3 +247,98 @@ export const DiffChecks: Story = {
     }
   },
 }
+
+const REVIEW_DIFF = `@@ -10,3 +10,4 @@
+ export function guard(req, res) {
+-  const token = req.headers.authorization
++  const token = readBearer(req.headers.authorization)
++  if (!token) return unauthorized(res, 'missing_token')
+`
+
+// A removed line exists only in the old file: its name says so, so no two buttons share one.
+const commentOn = (line: DiffLineInfo) =>
+  line.role === 'removed'
+    ? `Comment on old line ${line.oldLine}`
+    : `Comment on line ${line.newLine}`
+
+/**
+ * `lineAction` puts a button beside each line inside a hunk (a review
+ * comment, say), and `renderAfterLine` shows content under a line, full
+ * width. The gutter is one tab stop: Up and Down move between its buttons.
+ */
+export const DiffLineActions: Story = {
+  args: {code: REVIEW_DIFF},
+  render: ({code, ...args}) => (
+    <CodeBlock
+      {...args}
+      language="diff"
+      lineAction={{label: commentOn, onAction: fn()}}
+      renderAfterLine={(line) =>
+        line.newLine === 11 ? (
+          <Card variant="outlined" size="compact">
+            <Text variant="bodySm">Keep the 401 status text: clients read it.</Text>
+          </Card>
+        ) : null
+      }
+    >
+      <html.code>{code}</html.code>
+    </CodeBlock>
+  ),
+}
+
+/** DiffLineActions' checks: one tab stop, arrows move, the line handed over is numbered, copy keeps the diff. */
+export const DiffLineActionsChecks: Story = {
+  ...DiffLineActions,
+  tags: TEST_ONLY,
+  args: {code: REVIEW_DIFF, onCopyError: fn()},
+  render: ({code, ...args}) => {
+    const onAction = onLineAction
+    return (
+      <CodeBlock
+        {...args}
+        language="diff"
+        lineAction={{label: commentOn, onAction}}
+        renderAfterLine={(line) =>
+          line.newLine === 11 ? <Text variant="bodySm">Saved comment</Text> : null
+        }
+      >
+        <html.code>{code}</html.code>
+      </CodeBlock>
+    )
+  },
+  play: async ({args, canvas, canvasElement, userEvent}) => {
+    onLineAction.mockClear()
+    const lineButtons = canvas.getAllByRole('button', {name: /^Comment on/})
+    // The hunk header has no line number, so no button: four lines, four buttons.
+    await expect(lineButtons).toHaveLength(4)
+    await expect(lineButtons.filter((button) => button.tabIndex === 0)).toHaveLength(1)
+
+    lineButtons[0].focus()
+    await userEvent.keyboard('{ArrowDown}')
+    await expect(canvas.getByRole('button', {name: 'Comment on old line 11'})).toHaveFocus()
+    await userEvent.keyboard('{Enter}')
+    await expect(onLineAction).toHaveBeenCalledWith(
+      expect.objectContaining({role: 'removed', oldLine: 11, newLine: null}),
+    )
+
+    await userEvent.click(canvas.getByRole('button', {name: 'Comment on line 12'}))
+    await expect(onLineAction).toHaveBeenLastCalledWith(
+      expect.objectContaining({role: 'added', oldLine: null, newLine: 12}),
+    )
+
+    // Content under a line comes right after that line's row.
+    const saved = canvas.getByText('Saved comment')
+    const row = canvasElement.querySelector('[data-diff-line="added"]')!
+    await expect(row.compareDocumentPosition(saved) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy()
+
+    const write = spyOn(navigator.clipboard, 'writeText').mockResolvedValue(undefined)
+    try {
+      await userEvent.click(canvas.getByRole('button', {name: args.copyLabel}))
+      await expect(write).toHaveBeenCalledWith(args.code)
+    } finally {
+      write.mockRestore()
+    }
+  },
+}
+
+const onLineAction = fn()

package/src/components/CodeBlock/CodeBlock.tsx

@@ -6,6 +6,7 @@ import {typePresets} from '@duro-app/tokens/tokens/type-presets.css'
 import {styles} from './styles.css'
 import type {CodeBlockProps} from './types'
 import {DiffLines} from './DiffLines'
+import {DiffRows} from './DiffRows'
 import {textOf} from './diffRoles'
 
 export type {CodeBlockProps} from './types'
@@ -24,7 +25,11 @@ export function CodeBlock({
   copiedLabel,
   copiedDuration = 2000,
   onCopyError,
+  lineAction,
+  renderAfterLine,
 }: CodeBlockProps) {
+  // Lines that carry an action or content under them are rows, not text in a pre.
+  const asRows = language === 'diff' && (lineAction !== undefined || renderAfterLine !== undefined)
   const preRef = useRef<HTMLPreElement | null>(null)
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
   const [copied, setCopied] = useState(false)
@@ -51,7 +56,10 @@ export function CodeBlock({
 
   const copy = useCallback(async () => {
     try {
-      await navigator.clipboard.writeText(preRef.current?.textContent ?? '')
+      // Rows hold buttons and comments: what is copied is still the diff text.
+      await navigator.clipboard.writeText(
+        asRows ? textOf(children) : (preRef.current?.textContent ?? ''),
+      )
     } catch (error) {
       // Never dropped: without a handler the failure still reaches the console.
       if (onCopyError) onCopyError(error)
@@ -64,7 +72,7 @@ export function CodeBlock({
       timerRef.current = null
       setCopied(false)
     }, copiedDuration)
-  }, [copiedDuration, onCopyError])
+  }, [asRows, children, copiedDuration, onCopyError])
 
   return (
     <html.div style={styles.root}>
@@ -73,14 +81,24 @@ export function CodeBlock({
           {copied ? copiedLabel : copyLabel}
         </Button>
       </html.div>
-      <html.pre
-        ref={preRef}
-        tabIndex={scrollable ? 0 : undefined}
-        data-language={language}
-        style={[typePresets.code, styles.pre]}
-      >
-        {language === 'diff' ? <DiffLines text={textOf(children)} /> : children}
-      </html.pre>
+      {asRows ? (
+        <html.div data-language={language} style={[typePresets.code, styles.rows]}>
+          <DiffRows
+            text={textOf(children)}
+            lineAction={lineAction}
+            renderAfterLine={renderAfterLine}
+          />
+        </html.div>
+      ) : (
+        <html.pre
+          ref={preRef}
+          tabIndex={scrollable ? 0 : undefined}
+          data-language={language}
+          style={[typePresets.code, styles.pre]}
+        >
+          {language === 'diff' ? <DiffLines text={textOf(children)} /> : children}
+        </html.pre>
+      )}
       <LiveRegion visuallyHidden>{copied ? copiedLabel : ''}</LiveRegion>
     </html.div>
   )

package/src/components/CodeBlock/DiffRows.tsx

@@ -0,0 +1,101 @@
+import {
+  Fragment,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentProps,
+  type KeyboardEvent,
+  type ReactNode,
+} from 'react'
+import {html} from 'react-strict-dom'
+import {numberDiffLines, splitDiffLines, type DiffLineInfo, type DiffLineRole} from './diffRoles'
+import {styles} from './styles.css'
+import type {CodeBlockLineAction} from './types'
+
+const roleStyle = {
+  added: styles.added,
+  removed: styles.removed,
+  hunk: styles.hunk,
+  context: undefined,
+} as const satisfies Record<DiffLineRole, unknown>
+
+const inHunk = (line: DiffLineInfo) => line.oldLine !== null || line.newLine !== null
+
+/**
+ * A diff as rows rather than one `pre`, for when lines carry an action or
+ * content under them (a pre holds text only). Each row is a gutter and the
+ * line; content after a line spans the row. The gutter is one tab stop: the
+ * active line's button takes Tab, Up and Down move between the buttons.
+ */
+export function DiffRows({
+  text,
+  lineAction,
+  renderAfterLine,
+}: {
+  text: string
+  lineAction?: CodeBlockLineAction
+  renderAfterLine?: (line: DiffLineInfo) => ReactNode
+}) {
+  const lines = useMemo(() => numberDiffLines(splitDiffLines(text)), [text])
+  const available = lineAction?.available ?? inHunk
+  const actionable = useMemo(
+    () => (lineAction ? lines.filter((line) => available(line)).map((line) => line.index) : []),
+    [available, lineAction, lines],
+  )
+  const [activeIndex, setActiveIndex] = useState<number | null>(null)
+  const active =
+    activeIndex !== null && actionable.includes(activeIndex) ? activeIndex : (actionable[0] ?? null)
+  // Structural, so the native build (no DOM lib) types it too; focus exists only on the web.
+  const buttons = useRef(new Map<number, {focus?: () => void}>())
+
+  const move = (from: number, step: 1 | -1) => {
+    const position = actionable.indexOf(from) + step
+    const next = actionable[position]
+    if (next === undefined) return
+    setActiveIndex(next)
+    buttons.current.get(next)?.focus?.()
+  }
+  const onKeyDown = (line: DiffLineInfo) => (event: KeyboardEvent<HTMLButtonElement>) => {
+    if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp') return
+    event.preventDefault()
+    move(line.index, event.key === 'ArrowDown' ? 1 : -1)
+  }
+
+  return (
+    <Fragment>
+      {lines.map((line) => {
+        const after = renderAfterLine?.(line)
+        const offered = lineAction !== undefined && actionable.includes(line.index)
+        return (
+          <Fragment key={line.index}>
+            <html.div data-diff-line={line.role} style={[styles.row, roleStyle[line.role]]}>
+              {lineAction ? (
+                <html.span style={styles.gutter}>
+                  {offered ? (
+                    <html.button
+                      type="button"
+                      ref={(node: {focus?: () => void} | null) => {
+                        if (node) buttons.current.set(line.index, node)
+                        else buttons.current.delete(line.index)
+                      }}
+                      aria-label={lineAction.label(line)}
+                      tabIndex={line.index === active ? 0 : -1}
+                      onFocus={() => setActiveIndex(line.index)}
+                      onKeyDown={onKeyDown(line) as ComponentProps<typeof html.button>['onKeyDown']}
+                      onClick={() => lineAction.onAction(line)}
+                      style={styles.lineAction}
+                    >
+                      +
+                    </html.button>
+                  ) : null}
+                </html.span>
+              ) : null}
+              <html.span style={styles.rowText}>{line.text}</html.span>
+            </html.div>
+            {after ? <html.div style={styles.after}>{after}</html.div> : null}
+          </Fragment>
+        )
+      })}
+    </Fragment>
+  )
+}

package/src/components/CodeBlock/diffRoles.ts

@@ -38,3 +38,45 @@ export function textOf(node: ReactNode): string {
   }
   return ''
 }
+
+/** One line of a diff as a line action or after-line content sees it. */
+export interface DiffLineInfo {
+  /** The line's position in the diff text, from 0. */
+  index: number
+  role: DiffLineRole
+  /** The line without its newline. */
+  text: string
+  /** Its line number in the old file: removed and context lines inside a hunk, else null. */
+  oldLine: number | null
+  /** Its line number in the new file: added and context lines inside a hunk, else null. */
+  newLine: number | null
+}
+
+const HUNK_HEADER = /^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/
+
+/**
+ * Numbers a diff's lines from its hunk headers (`@@ -12,4 +12,6 @@`). Lines
+ * before the first hunk (file headers) and the headers themselves have no
+ * line numbers.
+ */
+export function numberDiffLines(lines: readonly DiffLine[]): DiffLineInfo[] {
+  let oldNext: number | null = null
+  let newNext: number | null = null
+  return lines.map((line, index) => {
+    const text = line.text.endsWith('\n') ? line.text.slice(0, -1) : line.text
+    if (line.role === 'hunk') {
+      const match = HUNK_HEADER.exec(text)
+      oldNext = match ? Number(match[1]) : null
+      newNext = match ? Number(match[2]) : null
+      return {index, role: line.role, text, oldLine: null, newLine: null}
+    }
+    if (oldNext === null || newNext === null) {
+      return {index, role: line.role, text, oldLine: null, newLine: null}
+    }
+    const oldLine = line.role === 'added' ? null : oldNext
+    const newLine = line.role === 'removed' ? null : newNext
+    if (oldLine !== null) oldNext += 1
+    if (newLine !== null) newNext += 1
+    return {index, role: line.role, text, oldLine, newLine}
+  })
+}

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

@@ -2,6 +2,7 @@ import {css} from 'react-strict-dom'
 import {colors} from '@duro-app/tokens/tokens/colors.css'
 import {radii, spacing} from '@duro-app/tokens/tokens/spacing.css'
 import {borders} from '@duro-app/tokens/tokens/borders.css'
+import {sizes} from '@duro-app/tokens/tokens/sizes.css'
 
 export const styles = css.create({
   // One bordered block: a row for the copy button, then the code. The button
@@ -50,6 +51,46 @@ export const styles = css.create({
   added: {backgroundColor: colors.successBg},
   removed: {backgroundColor: colors.errorBg},
   hunk: {backgroundColor: colors.infoBg, color: colors.infoText},
+  // Diff rows (a line action or content under lines): the block scrolls
+  // sideways as a whole, each row as wide as the longest line so its tint
+  // bands the full width.
+  rows: {
+    display: 'flex',
+    flexDirection: 'column',
+    paddingTop: spacing.xs,
+    paddingBottom: spacing.md,
+    overflowX: 'auto',
+    color: colors.text,
+  },
+  row: {display: 'flex', alignItems: 'center', minWidth: 'max-content'},
+  gutter: {
+    display: 'flex',
+    justifyContent: 'center',
+    flexShrink: 0,
+    width: sizes.iconButtonSm,
+  },
+  rowText: {whiteSpace: 'pre', paddingRight: spacing.md},
+  lineAction: {
+    width: sizes.chip,
+    height: sizes.chip,
+    padding: 0,
+    borderWidth: 0,
+    borderRadius: radii.xs,
+    backgroundColor: {default: 'transparent', ':hover': colors.bgCardHover},
+    color: colors.textMuted,
+    font: 'inherit',
+    cursor: 'pointer',
+    outlineWidth: {default: 0, ':focus-visible': borders.focusRing},
+    outlineStyle: {default: 'none', ':focus-visible': 'solid'},
+    outlineColor: {default: 'transparent', ':focus-visible': colors.accent},
+  },
+  // Content under a line spans the block, indented past the gutter.
+  after: {
+    paddingTop: spacing.xs,
+    paddingBottom: spacing.sm,
+    paddingLeft: sizes.iconButtonSm,
+    paddingRight: spacing.md,
+  },
   // Native: the code scrolls sideways inside the block.
   scroll: {
     paddingTop: spacing.xs,

package/src/components/CodeBlock/types.ts

@@ -1,4 +1,16 @@
 import type {ReactNode} from 'react'
+import type {DiffLineInfo} from './diffRoles'
+
+export type {DiffLineInfo} from './diffRoles'
+
+/** An action offered on diff lines (comment on a line, link to it). */
+export interface CodeBlockLineAction {
+  /** The button's accessible name for a line ("Comment on line 12"), from your text catalog. */
+  label: (line: DiffLineInfo) => string
+  onAction: (line: DiffLineInfo) => void
+  /** Which lines offer it. Default: every line inside a hunk (one with a line number). */
+  available?: (line: DiffLineInfo) => boolean
+}
 
 export interface CodeBlockProps {
   /**
@@ -26,4 +38,16 @@ export interface CodeBlockProps {
   copiedDuration?: number
   /** Called when the clipboard refuses the write (an insecure context, a denied permission). */
   onCopyError?: (error: unknown) => void
+  /**
+   * With `language="diff"`: a button in a gutter beside each line it is
+   * available on. The gutter is one tab stop; Up and Down move between its
+   * buttons.
+   */
+  lineAction?: CodeBlockLineAction
+  /**
+   * With `language="diff"`: content shown under a line, full width (a comment
+   * thread, an editor). Return null for lines with nothing under them. What
+   * is copied stays the diff text.
+   */
+  renderAfterLine?: (line: DiffLineInfo) => ReactNode
 }

package/src/components/Select/Select.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Dropdown select for choosing one value from a list. Compound component — Root is required (throws without it). Select.Trigger takes size="small" to match small Toggles and Buttons in a toolbar. Select.Popup takes label (the list\'s accessible name) and empty (shown in place of the list when it has no items). On the web the list opens below the trigger, or above it when it would overflow the viewport below and fits above. On React Native the trigger opens a bottom sheet (a Drawer at the medium and large detents) titled by label, with a Cancel text button (cancelLabel); the chosen option is filled with a trailing check, and a press picks an option and closes the sheet. Native has no arrow keys: each option is its own screen-reader stop.',
+    'Dropdown select for choosing one value from a list. Compound component — Root is required (throws without it). Select.Trigger takes size="small" to match small Toggles and Buttons in a toolbar. Select.Popup takes label (the list\'s accessible name) and empty (shown in place of the list when it has no items). On the web the list opens below the trigger, or above it when it would overflow the viewport below and fits above. On React Native the trigger opens a bottom sheet (a Drawer at the medium and large detents) titled by label, with a Cancel text button (cancelLabel); the chosen option is filled with a trailing check, and a press picks an option and closes the sheet. Native has no arrow keys: each option is its own screen-reader stop. An Item can be disabled (shown, skipped by the keys, inert to a press, announced as disabled), and onOpenChange on Root reports the list opening and closing, so work such as checking which options are available starts only once someone is choosing.',
   whenToUse: [
     'User must pick one option from a predefined list',
     'Form field for country, category, role selection',

package/src/components/Select/Select.native.tsx

@@ -57,6 +57,8 @@ interface RootProps {
   value?: string
   onValueChange?: (value: string | null) => void
   initialLabels?: Record<string, string>
+  /** Called when the sheet opens or closes. */
+  onOpenChange?: (open: boolean) => void
   children: ReactNode
 }
 
@@ -66,8 +68,15 @@ interface RootProps {
  * one and closes the sheet (C0 direction A, "Check"). The screen reader's
  * focus returns to the trigger.
  */
-function Root({defaultValue, value, onValueChange, initialLabels, children}: RootProps) {
-  const state = useSelectState({defaultValue, value, onValueChange, initialLabels})
+function Root({
+  defaultValue,
+  value,
+  onValueChange,
+  initialLabels,
+  onOpenChange,
+  children,
+}: RootProps) {
+  const state = useSelectState({defaultValue, value, onValueChange, initialLabels, onOpenChange})
   const {open, setOpen, setValue} = state
   const listboxId = useId()
   const triggerRef = useRef<unknown>(null)
@@ -191,10 +200,12 @@ function Popup({children, label, cancelLabel = 'Cancel', empty}: PopupProps) {
 
 interface ItemProps {
   value: string
+  /** Shown but not choosable. */
+  disabled?: boolean
   children: ReactNode
 }
 
-function Item({value: itemValue, children}: ItemProps) {
+function Item({value: itemValue, disabled = false, children}: ItemProps) {
   const collecting = useContext(CollectContext)
   const {value, registerLabel} = useSelect()
   const label = textOf(children)
@@ -203,7 +214,7 @@ function Item({value: itemValue, children}: ItemProps) {
   }, [collecting, itemValue, label, registerLabel])
   if (collecting) return null
   return (
-    <Listbox.Option value={itemValue} selected={value === itemValue}>
+    <Listbox.Option value={itemValue} selected={value === itemValue} disabled={disabled}>
       {children}
     </Listbox.Option>
   )

package/src/components/Select/Select.stories.tsx

@@ -297,3 +297,55 @@ export const OpensAboveNearTheBottomEdge: Story = {
     await expect(listBox.top).toBeGreaterThanOrEqual(0)
   },
 }
+
+const onAgentOpenChange = fn()
+
+/**
+ * An option can be `disabled` (shown, not choosable: an agent that cannot take
+ * over), and `onOpenChange` reports the list opening and closing, so work such
+ * as checking which options are available starts only once someone is choosing.
+ */
+export const DisabledOptionAndOpenChange: Story = {
+  render: () => (
+    <Select.Root defaultValue="claude" onOpenChange={onAgentOpenChange}>
+      <Select.Trigger aria-label="Agent">
+        <Select.Value />
+        <Select.Icon />
+      </Select.Trigger>
+      <Select.Popup label="Agent">
+        <Select.Item value="claude">Claude</Select.Item>
+        <Select.Item value="gemini" disabled>
+          Gemini
+        </Select.Item>
+        <Select.Item value="codex">Codex</Select.Item>
+      </Select.Popup>
+    </Select.Root>
+  ),
+  play: async ({canvas, userEvent}) => {
+    onAgentOpenChange.mockClear()
+    const trigger = canvas.getByRole('combobox')
+    await userEvent.click(trigger)
+    await waitFor(() => expect(onAgentOpenChange).toHaveBeenCalledWith(true))
+    const gemini = screen.getByRole('option', {name: 'Gemini'})
+    await expect(gemini).toHaveAttribute('aria-disabled', 'true')
+
+    // The keys step over it: from Claude, Down lands on Codex.
+    await userEvent.keyboard('{ArrowDown}')
+    await waitFor(() =>
+      expect(trigger).toHaveAttribute(
+        'aria-activedescendant',
+        screen.getByRole('option', {name: 'Codex'}).id,
+      ),
+    )
+
+    // A press does nothing: the value stays and the list stays open.
+    await userEvent.click(gemini)
+    await expect(trigger).toHaveTextContent(/Claude/)
+    await expect(trigger).toHaveAttribute('aria-expanded', 'true')
+
+    // Escape from the trigger closes it, and the close is reported too.
+    trigger.focus()
+    await userEvent.keyboard('{Escape}')
+    await waitFor(() => expect(onAgentOpenChange).toHaveBeenLastCalledWith(false))
+  },
+}

package/src/components/Select/Select.tsx

@@ -21,11 +21,27 @@ interface RootProps {
   value?: string
   onValueChange?: (value: string | null) => void
   initialLabels?: Record<string, string>
+  /** Called when the list opens or closes (to start work only once someone is choosing). */
+  onOpenChange?: (open: boolean) => void
   children: ReactNode
 }
 
-function Root({name, defaultValue, value, onValueChange, initialLabels, children}: RootProps) {
-  const {ctx, rootRef} = useSelectRoot({defaultValue, value, onValueChange, initialLabels})
+function Root({
+  name,
+  defaultValue,
+  value,
+  onValueChange,
+  initialLabels,
+  onOpenChange,
+  children,
+}: RootProps) {
+  const {ctx, rootRef} = useSelectRoot({
+    defaultValue,
+    value,
+    onValueChange,
+    initialLabels,
+    onOpenChange,
+  })
 
   return (
     <SelectContext.Provider value={ctx}>
@@ -217,10 +233,12 @@ function Popup({children, label, empty}: PopupProps) {
 // --- Item ---
 interface ItemProps {
   value: string
+  /** Shown but not choosable: skipped by the arrow keys, inert to a press, announced as disabled. */
+  disabled?: boolean
   children: ReactNode
 }
 
-function Item({value: itemValue, children}: ItemProps) {
+function Item({value: itemValue, disabled = false, children}: ItemProps) {
   const {
     value: selectedValue,
     setValue,
@@ -246,10 +264,11 @@ function Item({value: itemValue, children}: ItemProps) {
   useEffect(() => {
     const el = ref.current
     if (!el) return
-    return registerItem(id, itemValue, el)
-  }, [id, itemValue, registerItem])
+    return registerItem(id, itemValue, el, disabled)
+  }, [disabled, id, itemValue, registerItem])
 
   const handleClick = () => {
+    if (disabled) return
     setValue(itemValue)
     close()
   }
@@ -260,12 +279,14 @@ function Item({value: itemValue, children}: ItemProps) {
       id={id}
       role="option"
       aria-selected={isSelected}
+      aria-disabled={disabled || undefined}
       onClick={handleClick}
-      onPointerEnter={() => setHighlightedId(id)}
+      onPointerEnter={disabled ? undefined : () => setHighlightedId(id)}
       style={[
         styles.item,
         isSelected && styles.itemSelected,
         isHighlighted && styles.itemHighlighted,
+        disabled && styles.itemDisabled,
       ]}
     >
       {children}