@duro-app/ui 5.27.0 → 5.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duro-app/ui",
-  "version": "5.27.0",
+  "version": "5.29.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.27.0"
+    "@duro-app/tokens": "^5.29.0"
   },
   "devDependencies": {
     "@babel/preset-typescript": "^7.28.0",

package/src/components/List/List.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Vertical list of interactive items. Ideal for narrow spaces (detail panels, sidebars) where Table would truncate. Supports selection, descriptions, and action slots.',
+    'Vertical list of interactive items. Ideal for narrow spaces (detail panels, sidebars) where Table would truncate. Supports selection, descriptions, and action slots. An Item with onClick is pressable anywhere on its row, and its Content becomes a button: focusable, pressed with Enter or Space, announced with its text, disabled with the Item; the Actions stay beside it, so a Button there never nests in it.',
   whenToUse: [
     'Displaying items in a narrow container (< 480px)',
     'Detail panels, drawers, and sidebars',

package/src/components/List/List.stories.tsx

@@ -221,3 +221,57 @@ function DetailPanelDemo() {
 export const SingleSelection: Story = {
   render: () => <DetailPanelDemo />,
 }
+
+// --- Clickable items ---
+
+function ClickableDemo() {
+  const [picked, setPicked] = useState<string[]>([])
+  const turns = [
+    {
+      id: 't1',
+      text: 'Fix the login bug where a stale token logs the user out mid-session',
+      reply: 'Done',
+    },
+    {id: 't2', text: 'Add a test for it', reply: 'Added auth.test.ts'},
+    {id: 't3', text: 'Still sending', reply: null},
+  ]
+  return (
+    <html.div style={narrowContainer.box}>
+      <List.Root aria-label="Turns">
+        {turns.map((turn) => (
+          <List.Item
+            key={turn.id}
+            disabled={turn.reply === null}
+            onClick={() => setPicked((all) => [...all, turn.id])}
+          >
+            <List.Content>
+              <List.Text>{turn.text}</List.Text>
+              {turn.reply ? <List.Description>{turn.reply}</List.Description> : null}
+            </List.Content>
+            <List.Actions>
+              <Badge size="sm">Turn</Badge>
+            </List.Actions>
+          </List.Item>
+        ))}
+      </List.Root>
+      <html.p>Picked: {picked.join(', ')}</html.p>
+    </html.div>
+  )
+}
+
+export const ClickableItems: Story = {
+  render: () => <ClickableDemo />,
+  play: async ({canvas, userEvent}) => {
+    const buttons = canvas.getAllByRole('button')
+    await expect(buttons).toHaveLength(3)
+    // The keyboard reaches the item and presses it, once.
+    await userEvent.tab()
+    await expect(buttons[0]).toHaveFocus()
+    await userEvent.keyboard('{Enter}')
+    await expect(canvas.getByText('Picked: t1')).toBeInTheDocument()
+    // A press on the row outside the text is one press too.
+    await userEvent.click(canvas.getAllByText('Turn')[1])
+    await expect(canvas.getByText('Picked: t1, t2')).toBeInTheDocument()
+    await expect(buttons[2]).toBeDisabled()
+  },
+}

package/src/components/List/List.tsx

@@ -1,4 +1,4 @@
-import {type ReactNode, createContext, useContext} from 'react'
+import {type ReactNode, createContext, useContext, useMemo} from 'react'
 import {html} from 'react-strict-dom'
 import {styles} from './styles.css'
 
@@ -50,27 +50,65 @@ interface ItemProps {
   onClick?: () => void
 }
 
+// What a clickable Item hands its Content, which becomes the item's button.
+interface ItemActionValue {
+  onClick: () => void
+  disabled: boolean
+}
+
+const ItemActionContext = createContext<ItemActionValue | null>(null)
+
 function Item({children, selected, disabled, onClick}: ItemProps) {
   const {selectionMode} = useList()
   const isSelectable = selectionMode !== 'none'
+  const action = useMemo(
+    () => (onClick ? {onClick, disabled: disabled === true} : null),
+    [onClick, disabled],
+  )
 
   return (
-    <html.div
-      role="listitem"
-      aria-selected={isSelectable ? selected : undefined}
-      aria-disabled={disabled || undefined}
-      onClick={disabled ? undefined : onClick}
-      style={[styles.item, selected && styles.itemSelected, disabled && styles.itemDisabled]}
-    >
-      {children}
-    </html.div>
+    <ItemActionContext.Provider value={action}>
+      <html.div
+        role="listitem"
+        aria-selected={isSelectable ? selected : undefined}
+        aria-disabled={disabled || undefined}
+        // A press anywhere on the row; the Content's button is what keyboards and screen
+        // readers reach.
+        onClick={disabled ? undefined : onClick}
+        style={[
+          styles.item,
+          onClick != null && !disabled && styles.itemClickable,
+          selected && styles.itemSelected,
+          disabled && styles.itemDisabled,
+        ]}
+      >
+        {children}
+      </html.div>
+    </ItemActionContext.Provider>
   )
 }
 
 // --- Content: wraps primary text + description ---
 
 function Content({children}: {children: ReactNode}) {
-  return <html.div style={styles.content}>{children}</html.div>
+  const action = useContext(ItemActionContext)
+  if (!action) return <html.div style={styles.content}>{children}</html.div>
+  // In a clickable Item the Content is a real button: focusable, pressed with Enter or Space,
+  // announced with its text. The Actions stay beside it, never nested inside.
+  return (
+    <html.button
+      type="button"
+      disabled={action.disabled}
+      onClick={(event) => {
+        // The row handles a press too; this one has been answered.
+        event.stopPropagation()
+        action.onClick()
+      }}
+      style={[styles.content, styles.contentButton]}
+    >
+      {children}
+    </html.button>
+  )
 }
 
 // --- Text: primary label ---

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

@@ -1,6 +1,6 @@
 import {css} from 'react-strict-dom'
 import {colors} from '@duro-app/tokens/tokens/colors.css'
-import {microSpacing, spacing} from '@duro-app/tokens/tokens/spacing.css'
+import {microSpacing, radii, spacing} from '@duro-app/tokens/tokens/spacing.css'
 import {typography} from '@duro-app/tokens/tokens/typography.css'
 import {duration} from '@duro-app/tokens/tokens/motion.css'
 import {borders} from '@duro-app/tokens/tokens/borders.css'
@@ -40,6 +40,9 @@ export const styles = css.create({
       ':hover': colors.bgCardHover,
     },
   },
+  itemClickable: {
+    cursor: 'pointer',
+  },
   itemDisabled: {
     opacity: 0.5,
     pointerEvents: 'none',
@@ -57,6 +60,24 @@ export const styles = css.create({
     minWidth: 0,
   },
 
+  // The Content of a clickable Item: a button that reads as the row's text.
+  contentButton: {
+    alignItems: 'stretch',
+    textAlign: 'start',
+    backgroundColor: 'transparent',
+    borderWidth: 0,
+    padding: 0,
+    margin: 0,
+    font: 'inherit',
+    color: 'inherit',
+    cursor: 'inherit',
+    outlineWidth: {default: 0, ':focus-visible': borders.focusRing},
+    outlineStyle: {default: 'none', ':focus-visible': 'solid'},
+    outlineColor: {default: 'transparent', ':focus-visible': colors.accent},
+    outlineOffset: {default: 0, ':focus-visible': borders.focusOffset},
+    borderRadius: radii.xs,
+  },
+
   // --- Primary text ---
   text: {
     fontSize: typography.fontSizeSm,

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}

package/src/components/Select/SelectContext.ts

@@ -11,7 +11,7 @@ export interface SelectContextValue {
   listboxId: string
   highlightedId: string | null
   setHighlightedId: (id: string | null) => void
-  registerItem: (id: string, value: string, element: HTMLElement) => () => void
+  registerItem: (id: string, value: string, element: HTMLElement, disabled?: boolean) => () => void
   triggerRef: React.RefObject<HTMLButtonElement | null>
 }
 

package/src/components/Select/selectState.ts

@@ -1,4 +1,4 @@
-import {useCallback, useState} from 'react'
+import {useCallback, useEffect, useRef, useState} from 'react'
 import {useControllableValue} from '../../hooks/useControllableValue'
 
 export interface SelectStateOptions {
@@ -6,6 +6,12 @@ export interface SelectStateOptions {
   value?: string
   onValueChange?: (value: string | null) => void
   initialLabels?: Record<string, string>
+  /**
+   * Called when the list opens or closes, by any means (a press, a key, a pick,
+   * Escape, a press outside): for work that should start only once someone is
+   * choosing, such as checking which options are available.
+   */
+  onOpenChange?: (open: boolean) => void
 }
 
 /**
@@ -19,6 +25,7 @@ export function useSelectState({
   value: controlledValue,
   onValueChange,
   initialLabels,
+  onOpenChange,
 }: SelectStateOptions) {
   const [value, setValue] = useControllableValue<string | null>(
     controlledValue,
@@ -26,6 +33,15 @@ export function useSelectState({
     onValueChange,
   )
   const [open, setOpen] = useState(false)
+  // Reported after the change commits, once per transition; never for the first render.
+  const onOpenChangeRef = useRef(onOpenChange)
+  onOpenChangeRef.current = onOpenChange
+  const reportedOpenRef = useRef(open)
+  useEffect(() => {
+    if (reportedOpenRef.current === open) return
+    reportedOpenRef.current = open
+    onOpenChangeRef.current?.(open)
+  }, [open])
   const [labels, setLabels] = useState<Record<string, string>>(initialLabels ?? {})
 
   const registerLabel = useCallback((v: string, label: string) => {

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

@@ -121,6 +121,10 @@ export const styles = css.create({
   itemHighlighted: {
     backgroundColor: colors.bgCardHover,
   },
+  itemDisabled: {
+    color: colors.textDisabled,
+    cursor: 'not-allowed',
+  },
   hidden: {
     display: 'none',
   },

package/src/components/Select/useSelectRoot.ts

@@ -12,8 +12,15 @@ export function useSelectRoot(options: SelectStateOptions) {
   const listboxId = useId()
   const rootRef = useRef<HTMLDivElement>(null)
   const triggerRef = useRef<HTMLButtonElement | null>(null)
-  const itemsRef = useRef(new Map<string, {value: string; element: HTMLElement}>())
+  const itemsRef = useRef(
+    new Map<string, {value: string; element: HTMLElement; disabled: boolean}>(),
+  )
   const orderRef = useRef<string[]>([])
+  // What the keys move through: the options in document order, without the disabled ones.
+  const enabledOrder = useCallback(
+    () => orderRef.current.filter((id) => !itemsRef.current.get(id)?.disabled),
+    [],
+  )
 
   const close = useCallback(() => {
     setOpen(false)
@@ -25,7 +32,7 @@ export function useSelectRoot(options: SelectStateOptions) {
     setOpen((prev) => {
       if (!prev) {
         const items = itemsRef.current
-        const order = orderRef.current
+        const order = enabledOrder()
         let found: string | null = null
         for (const id of order) {
           const item = items.get(id)
@@ -40,24 +47,27 @@ export function useSelectRoot(options: SelectStateOptions) {
       }
       return !prev
     })
-  }, [value, setOpen])
+  }, [value, setOpen, enabledOrder])
 
-  const registerItem = useCallback((id: string, itemValue: string, element: HTMLElement) => {
-    itemsRef.current.set(id, {value: itemValue, element})
-    const map = itemsRef.current
-    const ids = [...map.keys()]
-    ids.sort((a, b) => {
-      const elA = map.get(a)?.element
-      const elB = map.get(b)?.element
-      if (!elA || !elB) return 0
-      return elA.compareDocumentPosition(elB) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1
-    })
-    orderRef.current = ids
-    return () => {
-      itemsRef.current.delete(id)
-      orderRef.current = orderRef.current.filter((i) => i !== id)
-    }
-  }, [])
+  const registerItem = useCallback(
+    (id: string, itemValue: string, element: HTMLElement, disabled = false) => {
+      itemsRef.current.set(id, {value: itemValue, element, disabled})
+      const map = itemsRef.current
+      const ids = [...map.keys()]
+      ids.sort((a, b) => {
+        const elA = map.get(a)?.element
+        const elB = map.get(b)?.element
+        if (!elA || !elB) return 0
+        return elA.compareDocumentPosition(elB) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1
+      })
+      orderRef.current = ids
+      return () => {
+        itemsRef.current.delete(id)
+        orderRef.current = orderRef.current.filter((i) => i !== id)
+      }
+    },
+    [],
+  )
 
   // Closed: ArrowDown/ArrowUp on the trigger open the listbox (the APG
   // select-only combobox), on the selected option or the first. In a Toolbar
@@ -82,7 +92,7 @@ export function useSelectRoot(options: SelectStateOptions) {
     if (!root || !open) return
 
     function handleKeyDown(e: KeyboardEvent) {
-      const order = orderRef.current
+      const order = enabledOrder()
       const items = itemsRef.current
       if (e.key === 'Escape') {
         e.preventDefault()
@@ -124,7 +134,7 @@ export function useSelectRoot(options: SelectStateOptions) {
           setHighlightedId((prev) => {
             if (prev) {
               const item = items.get(prev)
-              if (item) {
+              if (item && !item.disabled) {
                 setValue(item.value)
                 close()
               }
@@ -142,7 +152,7 @@ export function useSelectRoot(options: SelectStateOptions) {
 
     root.addEventListener('keydown', handleKeyDown)
     return () => root.removeEventListener('keydown', handleKeyDown)
-  }, [open, close, setValue])
+  }, [open, close, setValue, enabledOrder])
 
   const ctx: SelectContextValue = useMemo(
     () => ({