@duro-app/ui 3.5.0 → 3.7.0

package/dist/shared/devWarnOnce.d.ts

@@ -0,0 +1,3 @@
+/** Warn once, outside production, as `[duro-app/ui <scope>] <message>`. */
+export declare function devWarnOnce(scope: string, code: string, message: string): void;
+//# sourceMappingURL=devWarnOnce.d.ts.map

package/dist/shared/devWarnOnce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"devWarnOnce.d.ts","sourceRoot":"","sources":["../../src/shared/devWarnOnce.ts"],"names":[],"mappings":"AAOA,2EAA2E;AAC3E,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAM9E"}

package/dist/table.js

@@ -1,4 +1,4 @@
-import { c as H, m as p, d as b, M as F, s as xt, R as rt, H as kt, a as pt, B as bt, e as ft, C as mt, b as ht, f as yt } from "./Table-P-UHkEqJ.js";
+import { c as H, m as p, d as b, M as F, s as xt, R as rt, H as kt, a as pt, B as bt, e as ft, C as mt, b as ht, f as yt } from "./Table-Cgr5VDEZ.js";
 import { jsx as u, jsxs as B } from "react/jsx-runtime";
 import { flexRender as E, useReactTable as it, getPaginationRowModel as St, getFilteredRowModel as Tt, getSortedRowModel as at, getCoreRowModel as st } from "@tanstack/react-table";
 import { useState as G, useCallback as Ct, useRef as K, useEffect as Z, useLayoutEffect as wt } from "react";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duro-app/ui",
-  "version": "3.5.0",
+  "version": "3.7.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -64,7 +64,7 @@
   },
   "dependencies": {
     "@tanstack/react-virtual": "^3.14.6",
-    "@duro-app/tokens": "^3.5.0"
+    "@duro-app/tokens": "^3.7.0"
   },
   "devDependencies": {
     "@babel/preset-typescript": "^7.28.0",

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

@@ -39,6 +39,22 @@ export const Default: Story = {
   },
 }
 
+export const KeyboardEvents: Story = {
+  args: {placeholder: 'Search commands', onFocus: fn(), onKeyDown: fn(), onKeyUp: fn()},
+  play: async ({args, canvas, userEvent}) => {
+    const input = canvas.getByPlaceholderText('Search commands')
+    await userEvent.click(input)
+    await expect(args.onFocus).toHaveBeenCalledTimes(1)
+
+    await userEvent.keyboard('{ArrowDown}{Enter}{Escape}')
+    const keys = (args.onKeyDown as ReturnType<typeof fn>).mock.calls.map(
+      ([e]) => (e as React.KeyboardEvent).key,
+    )
+    await expect(keys).toEqual(['ArrowDown', 'Enter', 'Escape'])
+    await expect(args.onKeyUp).toHaveBeenCalledTimes(3)
+  },
+}
+
 export const Error: Story = {
   args: {variant: 'error', placeholder: 'Invalid input'},
   play: async ({canvas}) => {

package/src/components/Input/Input.tsx

@@ -51,6 +51,11 @@ interface InputProps {
   'aria-describedby'?: string
   onChange?: (e: React.ChangeEvent<HTMLInputElement>) => void
   onBlur?: () => void
+  onFocus?: (e: React.FocusEvent<HTMLInputElement>) => void
+  /** Keyboard handlers — e.g. Enter to commit, Escape to cancel, arrow-key
+   *  navigation of a list driven by this field. */
+  onKeyDown?: (e: React.KeyboardEvent<HTMLInputElement>) => void
+  onKeyUp?: (e: React.KeyboardEvent<HTMLInputElement>) => void
   ref?: React.Ref<HTMLInputElement>
 }
 
@@ -80,6 +85,9 @@ export function Input({
   'aria-describedby': ariaDescribedby,
   onChange,
   onBlur,
+  onFocus,
+  onKeyDown,
+  onKeyUp,
   ref,
 }: InputProps) {
   const ctx = useFieldContext()
@@ -129,6 +137,9 @@ export function Input({
       aria-invalid={ctx?.invalid || variant === 'error' || undefined}
       onChange={effectiveOnChange as StrictInputProps['onChange']}
       onBlur={effectiveOnBlur as StrictInputProps['onBlur']}
+      onFocus={onFocus as StrictInputProps['onFocus']}
+      onKeyDown={onKeyDown as StrictInputProps['onKeyDown']}
+      onKeyUp={onKeyUp as StrictInputProps['onKeyUp']}
       ref={effectiveRef as React.Ref<HTMLInputElement>}
       style={[
         styles.base,

package/src/components/Menu/Menu.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Dropdown action menu. Triggers actions (not value selection). Compound component — Root is required (throws without it).',
+    'Dropdown action menu. Triggers actions (not value selection). Compound component — Root is required (throws without it). Menu.Trigger renders the button itself: give it the label (text, an Icon), never a Button.',
   whenToUse: [
     'Context menu or "more actions" dropdown',
     'Navigation links in a dropdown',
@@ -19,12 +19,15 @@ export const meta: ComponentMeta = {
       kind: 'contrast',
       relationship: 'Select picks values; Menu triggers actions',
     },
-    {component: 'Button', kind: 'composition', relationship: 'Often used as Menu.Trigger content'},
+    {
+      component: 'Button',
+      kind: 'contrast',
+      relationship:
+        'Button runs one action; Menu opens a list of them. Menu.Trigger is already a button — never put a Button inside it',
+    },
   ],
   example: `<Menu.Root>
-  <Menu.Trigger>
-    <Button variant="secondary">Actions</Button>
-  </Menu.Trigger>
+  <Menu.Trigger>Actions</Menu.Trigger>
   <Menu.Popup>
     <Menu.Item onClick={() => console.log('edit')}>Edit</Menu.Item>
     <Menu.Item onClick={() => console.log('duplicate')}>Duplicate</Menu.Item>

package/src/components/Menu/Menu.stories.tsx

@@ -1,6 +1,7 @@
 import type {Meta, StoryObj} from '@storybook/react'
-import {expect, fn} from 'storybook/test'
+import {expect, fn, spyOn} from 'storybook/test'
 import {Menu} from './Menu'
+import {Button} from '../Button/Button'
 
 const meta: Meta = {
   title: 'Components/Menu',
@@ -144,3 +145,28 @@ export const WithLinks: Story = {
     await expect(items[0]).toHaveAttribute('href', '#admin')
   },
 }
+
+// Misuse on purpose, so it runs as a test but stays out of the sidebar:
+// Menu.Trigger is the button, and a Button inside it earns a dev warning.
+export const NestedControlWarns: Story = {
+  tags: ['!dev', '!autodocs'],
+  beforeEach: () => {
+    const warn = spyOn(console, 'warn').mockImplementation(() => {})
+    return () => warn.mockRestore()
+  },
+  render: () => (
+    <Menu.Root>
+      <Menu.Trigger>
+        <Button variant="secondary">Nested</Button>
+      </Menu.Trigger>
+      <Menu.Popup>
+        <Menu.Item>Edit</Menu.Item>
+      </Menu.Popup>
+    </Menu.Root>
+  ),
+  play: async () => {
+    await expect(console.warn).toHaveBeenCalledWith(
+      expect.stringContaining('Menu.Trigger is itself the button'),
+    )
+  },
+}

package/src/components/Menu/Menu.tsx

@@ -3,6 +3,7 @@ import {html} from 'react-strict-dom'
 import {styles} from './styles.css'
 import {MenuContext, useMenu} from './MenuContext'
 import {useMenuRoot} from './useMenuRoot'
+import {devWarnOnce} from '../../shared/devWarnOnce'
 
 // --- Root ---
 interface RootProps {
@@ -22,6 +23,11 @@ function Root({children}: RootProps) {
 }
 
 // --- Trigger ---
+// Trigger IS the button: aria-haspopup / aria-expanded / aria-controls have to
+// sit on the focusable element, so it cannot be a wrapper like Dialog.Trigger.
+// Its children are the label (text, an Icon) — never a Button or other control.
+const NESTED_CONTROL = 'button, a[href], input, select, textarea, [role="button"]'
+
 function Trigger({children}: {children: ReactNode}) {
   const {open, toggle, menuId, triggerRef} = useMenu()
   const localRef = useRef<HTMLButtonElement>(null)
@@ -31,6 +37,17 @@ function Trigger({children}: {children: ReactNode}) {
     triggerRef.current = localRef.current
   })
 
+  // TypeScript can't stop a <Button> child; the DOM can tell.
+  useEffect(() => {
+    if (localRef.current?.querySelector(NESTED_CONTROL)) {
+      devWarnOnce(
+        'Menu',
+        'trigger-nested-control',
+        'Menu.Trigger is itself the button — give it the label (text, an Icon), not a Button, link or other control. A control inside a <button> is invalid HTML: it breaks hydration and hands assistive tech a button inside a button.',
+      )
+    }
+  }, [])
+
   return (
     <html.button
       ref={localRef}

package/src/components/Table/Table.tsx

@@ -12,6 +12,7 @@ import {
 } from 'react'
 import {html} from 'react-strict-dom'
 import {styles} from './styles.css'
+import {devWarnOnce} from '../../shared/devWarnOnce'
 
 // --- Types ---
 
@@ -43,19 +44,6 @@ function useTable() {
 
 const HeaderContext = createContext(false)
 
-// --- Dev-only warn registry ---
-//
-// One-shot per warning code per process: long-running dev sessions
-// shouldn't drown the console on every re-render of a misconfigured table.
-const _IS_PROD = typeof process !== 'undefined' && process.env?.NODE_ENV === 'production'
-const _devWarned = new Set<string>()
-function devWarnOnce(code: string, message: string) {
-  if (_IS_PROD || _devWarned.has(code)) return
-  _devWarned.add(code)
-
-  console.warn(`[duro-app/ui Table] ${message}`)
-}
-
 // --- Container — owns the @container query target ---
 //
 // @deprecated Root sets up its own container query and accepts `sortChip`
@@ -148,6 +136,7 @@ function extractColumnMeta(
           // Children are JSX with no string content — stack mode will render
           // an unlabeled cell. Tell the developer once.
           devWarnOnce(
+            'Table',
             'headerCell-missing-label',
             'Table.HeaderCell with JSX children must set `label` for stack-mode rendering.',
           )

package/src/components/Textarea/Textarea.stories.tsx

@@ -36,6 +36,22 @@ export const Default: Story = {
   },
 }
 
+export const KeyboardEvents: Story = {
+  args: {placeholder: 'Edit note', onFocus: fn(), onKeyDown: fn(), onKeyUp: fn()},
+  play: async ({args, canvas, userEvent}) => {
+    const textarea = canvas.getByPlaceholderText('Edit note')
+    await userEvent.click(textarea)
+    await expect(args.onFocus).toHaveBeenCalledTimes(1)
+
+    await userEvent.keyboard('{ArrowDown}{Enter}{Escape}')
+    const keys = (args.onKeyDown as ReturnType<typeof fn>).mock.calls.map(
+      ([e]) => (e as React.KeyboardEvent).key,
+    )
+    await expect(keys).toEqual(['ArrowDown', 'Enter', 'Escape'])
+    await expect(args.onKeyUp).toHaveBeenCalledTimes(3)
+  },
+}
+
 export const Error: Story = {
   args: {variant: 'error', placeholder: 'Invalid content'},
   play: async ({canvas}) => {

package/src/components/Textarea/Textarea.tsx

@@ -18,6 +18,11 @@ interface TextareaProps {
   autoFocus?: boolean
   onChange?: (e: React.ChangeEvent<HTMLTextAreaElement>) => void
   onBlur?: () => void
+  onFocus?: (e: React.FocusEvent<HTMLTextAreaElement>) => void
+  /** Keyboard handlers — e.g. Enter to commit, Escape to cancel, arrow-key
+   *  navigation of a list driven by this field. */
+  onKeyDown?: (e: React.KeyboardEvent<HTMLTextAreaElement>) => void
+  onKeyUp?: (e: React.KeyboardEvent<HTMLTextAreaElement>) => void
   ref?: React.Ref<HTMLTextAreaElement>
 }
 
@@ -33,6 +38,9 @@ export function Textarea({
   autoFocus,
   onChange,
   onBlur,
+  onFocus,
+  onKeyDown,
+  onKeyUp,
   ref,
 }: TextareaProps) {
   const ctx = useFieldContext()
@@ -65,6 +73,9 @@ export function Textarea({
       aria-invalid={ctx?.invalid || variant === 'error' || undefined}
       onChange={effectiveOnChange as StrictTextareaProps['onChange']}
       onBlur={effectiveOnBlur as StrictTextareaProps['onBlur']}
+      onFocus={onFocus as StrictTextareaProps['onFocus']}
+      onKeyDown={onKeyDown as StrictTextareaProps['onKeyDown']}
+      onKeyUp={onKeyUp as StrictTextareaProps['onKeyUp']}
       ref={effectiveRef as React.Ref<HTMLTextAreaElement>}
       style={[styles.base, styles[effectiveVariant]]}
       {...extraProps}

package/src/components/Tree/Tree.meta.ts

@@ -0,0 +1,41 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Hierarchy of items with single selection and expandable branches (the WAI-ARIA tree pattern): one tab stop, arrow keys, Home/End, typeahead. Compound component — Root is required.',
+  whenToUse: [
+    'Browsing data that nests to any depth — a file tree, zones › services › capabilities, namespace › resource',
+    'Picking one node of a hierarchy to show its details beside the tree',
+  ],
+  whenNotToUse: [
+    'Site or app navigation — use SideNav (a rail advertises destinations; a tree browses data)',
+    'A flat list of choices — use List or RadioGroup',
+    'Choosing several nodes at once — not supported (single selection)',
+  ],
+  anatomy: {
+    required: ['Root', 'Item'],
+  },
+  relatedTo: [
+    {
+      component: 'SideNav',
+      kind: 'contrast',
+      relationship:
+        'SideNav is navigation between pages; Tree browses arbitrary-depth data. Never nest SideNav to fake a tree',
+    },
+    {
+      component: 'split-pane',
+      kind: 'composition',
+      relationship:
+        'A Tree in the list column of the split-pane recipe, the selection’s details beside it',
+    },
+  ],
+  example: `<Tree.Root aria-label="Blocs" defaultExpanded={['energy']} onValueChange={setSelected}>
+  <Tree.Item value="energy" label="Core business — Energy">
+    <Tree.Item value="generation" label="Generation" meta="4 apps" />
+    <Tree.Item value="network" label="Network operations">
+      <Tree.Item value="scada" label="SCADA supervision" />
+    </Tree.Item>
+  </Tree.Item>
+  <Tree.Item value="finance" label="Finance & steering" />
+</Tree.Root>`,
+}

package/src/components/Tree/Tree.stories.tsx

@@ -0,0 +1,151 @@
+import {useState} from 'react'
+import {html} from 'react-strict-dom'
+import type {Meta, StoryObj} from '@storybook/react'
+import {expect} from 'storybook/test'
+import {Tree} from './Tree'
+
+const meta: Meta = {
+  title: 'Components/Tree',
+}
+
+export default meta
+type Story = StoryObj
+
+function Landscape(props: {
+  defaultExpanded?: string[]
+  onValueChange?: (v: string) => void
+  value?: string | null
+}) {
+  return (
+    <Tree.Root
+      aria-label="Blocs"
+      defaultExpanded={props.defaultExpanded}
+      onValueChange={props.onValueChange}
+      value={props.value}
+    >
+      <Tree.Item value="energy" label="Core business — Energy" meta="3 zones">
+        <Tree.Item value="generation" label="Generation" meta="4 apps" />
+        <Tree.Item value="network" label="Network operations">
+          <Tree.Item value="scada" label="SCADA supervision" />
+          <Tree.Item value="outage" label="Outage management" />
+        </Tree.Item>
+        <Tree.Item value="metering" label="Metering & data" />
+      </Tree.Item>
+      <Tree.Item value="market" label="Market & field">
+        <Tree.Item value="trading" label="Trading" />
+      </Tree.Item>
+      <Tree.Item value="finance" label="Finance & steering" />
+    </Tree.Root>
+  )
+}
+
+export const Default: Story = {
+  render: () => <Landscape defaultExpanded={['energy']} />,
+  play: async ({canvas, userEvent}) => {
+    const tree = canvas.getByRole('tree', {name: 'Blocs'})
+    await expect(tree).toBeInTheDocument()
+
+    const energy = canvas.getByRole('treeitem', {name: /Core business/})
+    await expect(energy).toHaveAttribute('aria-expanded', 'true')
+    await expect(energy).toHaveAttribute('aria-level', '1')
+    const generation = canvas.getByRole('treeitem', {name: /Generation/})
+    await expect(generation).toHaveAttribute('aria-level', '2')
+    // a leaf has no expanded state at all
+    await expect(generation).not.toHaveAttribute('aria-expanded')
+    // a closed branch renders no children
+    await expect(canvas.queryByRole('treeitem', {name: /SCADA/})).toBeNull()
+
+    // one tab stop: the first item
+    await expect(energy).toHaveAttribute('tabindex', '0')
+    await expect(generation).toHaveAttribute('tabindex', '-1')
+
+    // a click selects the row
+    await userEvent.click(canvas.getByText('Generation'))
+    await expect(generation).toHaveAttribute('aria-selected', 'true')
+    await expect(energy).toHaveAttribute('aria-selected', 'false')
+  },
+}
+
+export const KeyboardNavigation: Story = {
+  render: () => <Landscape />,
+  play: async ({canvas, userEvent}) => {
+    const item = (name: RegExp) => canvas.getByRole('treeitem', {name})
+    await userEvent.tab()
+    await expect(item(/Core business/)).toHaveFocus()
+
+    // → opens the branch, → again goes to its first child
+    await userEvent.keyboard('{ArrowRight}')
+    await expect(item(/Core business/)).toHaveAttribute('aria-expanded', 'true')
+    await expect(item(/Core business/)).toHaveFocus()
+    await userEvent.keyboard('{ArrowRight}')
+    await expect(item(/Generation/)).toHaveFocus()
+
+    // ↓ walks the visible items; ↓ onto a closed branch, → opens it
+    await userEvent.keyboard('{ArrowDown}')
+    await expect(item(/Network operations/)).toHaveFocus()
+    await userEvent.keyboard('{ArrowRight}{ArrowDown}')
+    await expect(item(/SCADA/)).toHaveFocus()
+    await expect(item(/SCADA/)).toHaveAttribute('aria-level', '3')
+
+    // ← on a leaf goes to the parent; ← on an open branch closes it
+    await userEvent.keyboard('{ArrowLeft}')
+    await expect(item(/Network operations/)).toHaveFocus()
+    await userEvent.keyboard('{ArrowLeft}')
+    await expect(item(/Network operations/)).toHaveAttribute('aria-expanded', 'false')
+    await expect(canvas.queryByRole('treeitem', {name: /SCADA/})).toBeNull()
+
+    // Home / End
+    await userEvent.keyboard('{End}')
+    await expect(item(/Finance/)).toHaveFocus()
+    await userEvent.keyboard('{Home}')
+    await expect(item(/Core business/)).toHaveFocus()
+
+    // Enter selects; the tab stop follows focus
+    await userEvent.keyboard('{ArrowDown}{Enter}')
+    await expect(item(/Generation/)).toHaveAttribute('aria-selected', 'true')
+    await expect(item(/Generation/)).toHaveAttribute('tabindex', '0')
+    await expect(item(/Core business/)).toHaveAttribute('tabindex', '-1')
+  },
+}
+
+export const Typeahead: Story = {
+  render: () => <Landscape defaultExpanded={['energy']} />,
+  play: async ({canvas, userEvent}) => {
+    const item = (name: RegExp) => canvas.getByRole('treeitem', {name})
+    await userEvent.tab()
+    // a letter jumps to the next visible item starting with it
+    await userEvent.keyboard('m')
+    await expect(item(/Metering/)).toHaveFocus()
+    // the same letter again cycles to the next match
+    await userEvent.keyboard('m')
+    await expect(item(/Market/)).toHaveFocus()
+    // a pause starts a new search; a prefix typed in one go narrows
+    await new Promise((r) => setTimeout(r, 600))
+    await userEvent.keyboard('fi')
+    await expect(item(/Finance/)).toHaveFocus()
+  },
+}
+
+function ControlledTree() {
+  const [value, setValue] = useState<string | null>('trading')
+  return (
+    <>
+      <Landscape defaultExpanded={['market']} value={value} onValueChange={setValue} />
+      <html.span role="status" aria-label="Selected">
+        {value}
+      </html.span>
+    </>
+  )
+}
+
+export const Controlled: Story = {
+  render: () => <ControlledTree />,
+  play: async ({canvas, userEvent}) => {
+    const trading = canvas.getByRole('treeitem', {name: /Trading/})
+    await expect(trading).toHaveAttribute('aria-selected', 'true')
+    // the selection holds the tab stop
+    await expect(trading).toHaveAttribute('tabindex', '0')
+    await userEvent.click(canvas.getByText('Finance & steering'))
+    await expect(canvas.getByLabelText('Selected')).toHaveTextContent('finance')
+  },
+}