@duro-app/ui 5.23.0 → 5.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duro-app/ui",
-  "version": "5.23.0",
+  "version": "5.25.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.23.0"
+    "@duro-app/tokens": "^5.25.0"
   },
   "devDependencies": {
     "@babel/preset-typescript": "^7.28.0",

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 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.',
   whenToUse: [
     'User must pick one option from a predefined list',
     'Form field for country, category, role selection',

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

@@ -1,5 +1,6 @@
 import type {Meta, StoryObj} from '@storybook/react'
-import {expect, fn, screen} from 'storybook/test'
+import {expect, fn, screen, waitFor} from 'storybook/test'
+import {css, html} from 'react-strict-dom'
 import {Dialog} from '../Dialog/Dialog'
 import {Select} from './Select'
 
@@ -261,3 +262,38 @@ export const LabelledAndEmpty: StoryObj<LabelledArgs> = {
     await expect(screen.queryAllByRole('option')).toHaveLength(0)
   },
 }
+
+// A composer's mode Select sits at the bottom of the window: its list opens above
+// the trigger, as Menu and Popover do, instead of running off the screen.
+const bottom = css.create({
+  frame: {height: '100vh', display: 'flex', flexDirection: 'column', justifyContent: 'flex-end'},
+})
+
+export const OpensAboveNearTheBottomEdge: Story = {
+  parameters: {layout: 'fullscreen'},
+  render: () => (
+    <html.div style={bottom.frame}>
+      <Select.Root defaultValue="default">
+        <Select.Trigger aria-label="Permission mode">
+          <Select.Value />
+          <Select.Icon />
+        </Select.Trigger>
+        <Select.Popup label="Permission mode">
+          <Select.Item value="default">Default</Select.Item>
+          <Select.Item value="read-only">Read only</Select.Item>
+          <Select.Item value="auto">Auto</Select.Item>
+          <Select.Item value="yolo">YOLO</Select.Item>
+        </Select.Popup>
+      </Select.Root>
+    </html.div>
+  ),
+  play: async ({canvas, userEvent}) => {
+    const trigger = canvas.getByRole('combobox', {name: 'Permission mode'})
+    await userEvent.click(trigger)
+    const list = await screen.findByRole('listbox', {name: 'Permission mode'})
+    await waitFor(() => expect(list).toBeVisible())
+    const listBox = list.getBoundingClientRect()
+    await expect(listBox.bottom).toBeLessThanOrEqual(trigger.getBoundingClientRect().top)
+    await expect(listBox.top).toBeGreaterThanOrEqual(0)
+  },
+}

package/src/components/Select/Select.tsx

@@ -1,11 +1,13 @@
 import {Children, type ReactNode, useRef, useId, useEffect, useLayoutEffect, useState} from 'react'
 import {createPortal} from 'react-dom'
 import {html} from 'react-strict-dom'
+import {SPACING_PX} from '@duro-app/tokens/keys'
 import {styles} from './styles.css'
 import {SelectContext, useSelect} from './SelectContext'
 import {useSelectRoot} from './useSelectRoot'
 import {useFieldContext} from '../Field/FieldContext'
 import {usePortalMount} from '../ThemeProvider/ThemeProvider'
+import {computePopoverPosition} from '../Popover/position'
 import {usePopoverLayer} from '../Popover/PopoverLayerContext'
 import {useGroupedControl} from '../ButtonGroup/useGroupedControl'
 import {ControlContextBoundary} from '../Toolbar/ControlContextBoundary'
@@ -140,18 +142,32 @@ function Popup({children, label, empty}: PopupProps) {
   const {open, close, listboxId, triggerRef} = useSelect()
   const mount = usePortalMount()
   const [coords, setCoords] = useState<{top: number; left: number; width: number} | null>(null)
+  const listboxRef = useRef<HTMLDivElement>(null)
 
-  // Measure the trigger when the popup opens, and re-measure on scroll/resize so
-  // the dropdown follows it. Capture-phase scroll catches scroll on any ancestor
-  // (e.g. a Dialog body).
+  // Place the list against the trigger when it opens, below it unless it would
+  // overflow the viewport there and fits above (as Menu and Popover do), and
+  // re-place it on scroll/resize so it follows the trigger. Capture-phase scroll
+  // catches scroll on any ancestor (e.g. a Dialog body). The list is laid out,
+  // invisible, before its first placement so its height can be measured.
   useLayoutEffect(() => {
     if (!open) return
     const update = () => {
-      const el = triggerRef.current
-      if (!el) return
-      const rect = el.getBoundingClientRect()
-      // `xs` token = 4px gap below the trigger.
-      setCoords({top: rect.bottom + 4, left: rect.left, width: rect.width})
+      const rect = triggerRef.current?.getBoundingClientRect()
+      const list = listboxRef.current
+      if (!rect || !list) return
+      const next = computePopoverPosition({
+        anchor: {top: rect.top, left: rect.left, width: rect.width, height: rect.height},
+        popup: {width: Math.max(list.offsetWidth, rect.width), height: list.offsetHeight},
+        viewport: {width: window.innerWidth, height: window.innerHeight},
+        side: 'bottom',
+        align: 'start',
+        offset: SPACING_PX.xs,
+      })
+      setCoords((prev) =>
+        prev && prev.top === next.top && prev.left === next.left && prev.width === rect.width
+          ? prev
+          : {top: next.top, left: next.left, width: rect.width},
+      )
     }
     update()
     window.addEventListener('resize', update)
@@ -162,7 +178,6 @@ function Popup({children, label, empty}: PopupProps) {
     }
   }, [open, triggerRef])
 
-  const listboxRef = useRef<HTMLDivElement>(null)
   const backdropRef = useRef<HTMLDivElement>(null)
   usePopoverLayer(listboxRef, {active: open})
   usePopoverLayer(backdropRef, {active: open})
@@ -178,7 +193,8 @@ function Popup({children, label, empty}: PopupProps) {
         aria-hidden={!open}
         style={[
           styles.popup,
-          (!open || !coords) && styles.hidden,
+          !open && styles.hidden,
+          open && !coords && styles.measuring,
           coords && styles.popupPosition(coords.top, coords.left, coords.width),
         ]}
       >

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

@@ -124,6 +124,10 @@ export const styles = css.create({
   hidden: {
     display: 'none',
   },
+  // Open but not yet placed: laid out (so its height can be measured) and unseen.
+  measuring: {
+    visibility: 'hidden',
+  },
   // Popup's `empty`: no items to choose from.
   empty: {
     paddingTop: spacing.md,

package/src/components/SplitPane/SplitPane.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Two panes side by side with a resizable separator: the first Pane is sized by the Handle (pointer drag, arrow keys, Shift for larger steps, Home and End), the second takes the rest. Min, max and starting widths are size tokens. Below collapseBelow, measured on its own width, the panes stack in one column and the handle goes; on native they always stack. A controlled collapsed prop shrinks the first pane to a strip (the iconButton size) that shows collapsedContent, removes the Handle, and keeps the first pane’s own children mounted but inert and hidden (state kept, no tab stops, out of the accessibility tree); the prior width returns when it turns false. Native ignores both. The Handle is a hairline that thickens to the accent on hover, keyboard focus or drag.',
+    'Two panes side by side with a resizable separator: the first Pane is sized by the Handle (pointer drag, arrow keys, Shift for larger steps, Home and End), the second takes the rest. Min, max and starting widths are size tokens. onSizeChange reports every width while the handle moves; onSizeCommit reports the width once a resize ends (a released drag, each keyboard step), the moment to persist it. Below collapseBelow, measured on its own width, the panes stack in one column and the handle goes; on native they always stack. A controlled collapsed prop shrinks the first pane to a strip (the iconButton size) that shows collapsedContent, removes the Handle, and keeps the first pane’s own children mounted but inert and hidden (state kept, no tab stops, out of the accessibility tree); the prior width returns when it turns false. Native ignores both. The Handle is a hairline that thickens to the accent on hover, keyboard focus or drag.',
   whenToUse: [
     'A list beside its detail where people need more room on either side (a session list and its transcript)',
     'An editor beside its preview',

package/src/components/SplitPane/SplitPane.native.tsx

@@ -12,6 +12,8 @@ interface RootProps {
   size?: number
   /** Web only. */
   onSizeChange?: (px: number) => void
+  /** Web only: called once a resize ends (native always stacks). */
+  onSizeCommit?: (px: number) => void
   /** Web only. */
   minSize?: SizeToken
   /** Web only. */

package/src/components/SplitPane/SplitPane.stories.tsx

@@ -34,6 +34,7 @@ interface SplitArgs {
   maxSize: SizeToken
   collapseBelow: Breakpoint
   onSizeChange?: (px: number) => void
+  onSizeCommit?: (px: number) => void
   collapsed?: boolean
   collapsedContent?: ReactNode
 }
@@ -50,11 +51,19 @@ const PANE_SIZES: SizeToken[] = ['sidebarW', 'panelSm', 'panelMd', 'panelLg']
 
 /** The picked B0 direction (docs/mockups/split-pane/Hairline.dc.html). */
 function Split(props: Partial<SplitArgs>) {
-  const {defaultSize, minSize, maxSize, collapseBelow, onSizeChange, collapsed, collapsedContent} =
-    {
-      ...DEFAULT_ARGS,
-      ...props,
-    }
+  const {
+    defaultSize,
+    minSize,
+    maxSize,
+    collapseBelow,
+    onSizeChange,
+    onSizeCommit,
+    collapsed,
+    collapsedContent,
+  } = {
+    ...DEFAULT_ARGS,
+    ...props,
+  }
   return (
     <html.div style={frame.fill}>
       <SplitPane.Root
@@ -64,6 +73,7 @@ function Split(props: Partial<SplitArgs>) {
         maxSize={maxSize}
         collapseBelow={collapseBelow}
         onSizeChange={onSizeChange}
+        onSizeCommit={onSizeCommit}
         collapsed={collapsed}
         collapsedContent={collapsedContent}
       >
@@ -145,6 +155,38 @@ export const KeyboardMovesTheSeparator: Story = {
   },
 }
 
+// A drag reports every width while it moves and the final one once, on release;
+// a keyboard step is its own commit. An app persists the width on commit.
+export const ResizeCommitsOnceWhenItEnds: StoryObj<SplitArgs> = {
+  args: {onSizeChange: fn(), onSizeCommit: fn()},
+  render: (args) => <Split {...args} />,
+  beforeEach: async () => {
+    await setViewport(1200, 800)
+  },
+  play: async ({args}) => {
+    await waitFor(() => expect(separator()).not.toBeNull())
+    const handle = separator()!
+    const box = handle.getBoundingClientRect()
+    const x = box.left + box.width / 2
+    const y = box.top + box.height / 2
+    await userEvent.pointer([
+      {keys: '[MouseLeft>]', target: handle, coords: {clientX: x, clientY: y}},
+      {target: handle, coords: {clientX: x + 20, clientY: y}},
+      {target: handle, coords: {clientX: x + 40, clientY: y}},
+      {keys: '[/MouseLeft]', target: handle, coords: {clientX: x + 40, clientY: y}},
+    ])
+    // two widths while it moved, one commit when it was released
+    await expect(args.onSizeChange).toHaveBeenCalledTimes(2)
+    await expect(args.onSizeCommit).toHaveBeenCalledTimes(1)
+    await expect(args.onSizeCommit).toHaveBeenLastCalledWith(SIZES_PX.sidebarW + 40)
+
+    handle.focus()
+    await userEvent.keyboard('{ArrowLeft}')
+    await expect(args.onSizeCommit).toHaveBeenCalledTimes(2)
+    await expect(args.onSizeCommit).toHaveBeenLastCalledWith(SIZES_PX.sidebarW + 40 - SPACING_PX.md)
+  },
+}
+
 export const NarrowStacksInOneColumn: Story = {
   render: () => <Split />,
   beforeEach: async () => {

package/src/components/SplitPane/SplitPane.tsx

@@ -21,6 +21,7 @@ interface SplitPaneContextValue {
   min: number
   max: number
   setSize: (px: number) => void
+  commitSize: (px: number) => void
   stacked: boolean
   collapsed: boolean
   collapsedContent: ReactNode
@@ -53,6 +54,12 @@ interface RootProps {
   size?: number
   /** Called with the primary pane's new width while the handle moves */
   onSizeChange?: (px: number) => void
+  /**
+   * Called once a resize ends, with the width it ended at: when a drag is
+   * released (or cancelled) and after each keyboard step. Persist the width
+   * here rather than on every `onSizeChange`.
+   */
+  onSizeCommit?: (px: number) => void
   /** The primary pane's narrowest width, a size token. Default: `sidebarW` */
   minSize?: SizeToken
   /** The primary pane's widest width, a size token. Default: `panelLg` */
@@ -83,6 +90,7 @@ function Root({
   defaultSize = 'sidebarW',
   size: controlledSize,
   onSizeChange,
+  onSizeCommit,
   minSize = 'sidebarW',
   maxSize = 'panelLg',
   collapseBelow = 'sm',
@@ -102,6 +110,10 @@ function Root({
     },
     [controlledSize, onSizeChange, min, max],
   )
+  const commitSize = useCallback(
+    (px: number) => onSizeCommit?.(clamp(Math.round(px), min, max)),
+    [onSizeCommit, min, max],
+  )
   const rootRef = useRef<HTMLDivElement>(null)
   const stacked = useContainerBelow(rootRef, collapseBelow)
   const primaryId = useId()
@@ -117,7 +129,18 @@ function Root({
 
   return (
     <SplitPaneContext.Provider
-      value={{size, min, max, setSize, stacked, collapsed, collapsedContent, primaryId, label}}
+      value={{
+        size,
+        min,
+        max,
+        setSize,
+        commitSize,
+        stacked,
+        collapsed,
+        collapsedContent,
+        primaryId,
+        label,
+      }}
     >
       <html.div ref={rootRef} style={[styles.root, stacked && styles.rootStacked]}>
         {items}
@@ -171,7 +194,8 @@ function Pane({children}: {children: ReactNode}) {
 }
 
 function Handle() {
-  const {size, min, max, setSize, stacked, collapsed, primaryId, label} = useSplitPane('Handle')
+  const {size, min, max, setSize, commitSize, stacked, collapsed, primaryId, label} =
+    useSplitPane('Handle')
   const [hovered, setHovered] = useState(false)
   const [keyboardFocus, setKeyboardFocus] = useState(false)
   const [dragging, setDragging] = useState(false)
@@ -198,10 +222,11 @@ function Handle() {
       if (next === null) return
       e.preventDefault()
       setSize(next)
+      commitSize(next)
     }
     el.addEventListener('keydown', onKeyDown)
     return () => el.removeEventListener('keydown', onKeyDown)
-  }, [size, min, max, setSize, stacked, collapsed])
+  }, [size, min, max, setSize, commitSize, stacked, collapsed])
 
   if (stacked || collapsed) return null
   const active = hovered || keyboardFocus || dragging
@@ -240,12 +265,16 @@ function Handle() {
         setSize(drag.current.startSize + e.clientX - drag.current.startX)
       }}
       onPointerUp={() => {
+        if (!drag.current) return
         drag.current = null
         setDragging(false)
+        commitSize(size)
       }}
       onPointerCancel={() => {
+        if (!drag.current) return
         drag.current = null
         setDragging(false)
+        commitSize(size)
       }}
     >
       <html.span aria-hidden style={[styles.line, active && styles.lineActive]} />

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

@@ -2,7 +2,7 @@ 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. A click or Enter on a branch row with no href selects it and toggles it open or closed (a folder); a branch with href navigates, and its chevron toggles. An Item with href renders its row as a real link (cmd-click opens a tab) outside the tab order; Enter/Space follows it, through onNavigate(href, event) when given. Compound component — Root is required. On React Native each row is a pressable link (href) or button, and a branch has its own chevron control that expands it (named by the optional Root prop expandLabel(text), default the item text); selection, expansion and aria-level are the same, the keyboard model (arrows, Home/End, typeahead) is web only. On native onNavigate is required for in-app routes: without it a relative href goes to the system (Linking.openURL). On web a tree with more items than Root virtualizeThreshold (default 150, open or not) is windowed: only the rows in view mount, as flat treeitems with aria-level, aria-setsize and aria-posinset; maxHeight caps its scroll viewport. Items must be JSX descendants of Root (fragments and arrays are fine, an Item hidden inside another component is not seen by the window). Native renders every row.',
+    'Hierarchy of items with single selection and expandable branches (the WAI-ARIA tree pattern): one tab stop, arrow keys, Home/End, typeahead. A click or Enter on a branch row with no href selects it and toggles it open or closed (a folder); a branch with href navigates, and its chevron toggles. An Item with expandable is a branch before its children exist (a directory listed only when opened): it opens like any branch and onExpandedChange tells the app to load them. An Item with href renders its row as a real link (cmd-click opens a tab) outside the tab order; Enter/Space follows it, through onNavigate(href, event) when given. Compound component — Root is required. On React Native each row is a pressable link (href) or button, and a branch has its own chevron control that expands it (named by the optional Root prop expandLabel(text), default the item text); selection, expansion and aria-level are the same, the keyboard model (arrows, Home/End, typeahead) is web only. On native onNavigate is required for in-app routes: without it a relative href goes to the system (Linking.openURL). On web a tree with more items than Root virtualizeThreshold (default 150, open or not) is windowed: only the rows in view mount, as flat treeitems with aria-level, aria-setsize and aria-posinset; maxHeight caps its scroll viewport. Items must be JSX descendants of Root (fragments and arrays are fine, an Item hidden inside another component is not seen by the window). Native renders every row.',
   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',

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

@@ -616,3 +616,42 @@ export const BranchRowToggles: Story = {
     await expect(branch).toHaveAttribute('aria-expanded', 'false')
   },
 }
+
+/** A file tree that lists a directory only when it is opened (`expandable`). */
+function LazyFolders() {
+  const [expanded, setExpanded] = useState<string[]>([])
+  const [loaded, setLoaded] = useState<ReadonlySet<string>>(() => new Set())
+  return (
+    <Tree.Root
+      aria-label="Folders"
+      expanded={expanded}
+      onExpandedChange={(next) => {
+        setExpanded(next)
+        // The app lists a directory the first time it opens.
+        setLoaded((prev) => new Set([...prev, ...next]))
+      }}
+    >
+      <Tree.Item value="src" label="src" expandable>
+        {loaded.has('src') ? <Tree.Item value="app" label="app.ts" /> : null}
+      </Tree.Item>
+      <Tree.Item value="readme" label="README.md" />
+    </Tree.Root>
+  )
+}
+
+export const ExpandableBranchLoadsOnOpen: Story = {
+  name: 'Expandable branch loads on open',
+  render: () => <LazyFolders />,
+  play: async ({canvas, userEvent}) => {
+    const branch = canvas.getByRole('treeitem', {name: 'src'})
+    // A branch before its children exist: it can open, a leaf cannot.
+    await expect(branch).toHaveAttribute('aria-expanded', 'false')
+    await expect(canvas.getByRole('treeitem', {name: 'README.md'})).not.toHaveAttribute(
+      'aria-expanded',
+    )
+    branch.focus()
+    await userEvent.keyboard('{ArrowRight}')
+    await expect(branch).toHaveAttribute('aria-expanded', 'true')
+    await expect(await canvas.findByRole('treeitem', {name: 'app.ts'})).toBeVisible()
+  },
+}

package/src/components/Tree/Tree.tsx

@@ -164,10 +164,19 @@ function Root({
 
 // --- Item ---
 
-function Item({value, label, textValue, children, meta, href, onNavigate}: TreeItemProps) {
+function Item({
+  value,
+  label,
+  textValue,
+  children,
+  meta,
+  href,
+  onNavigate,
+  expandable,
+}: TreeItemProps) {
   const {isExpanded} = useTree()
   const level = useContext(TreeLevelContext)
-  const hasChildren = Children.count(children) > 0
+  const hasChildren = Children.count(children) > 0 || expandable === true
 
   return (
     <TreeItemRow

package/src/components/Tree/TreeRows.ts

@@ -9,8 +9,14 @@ export interface TreeItemProps {
   label: ReactNode
   /** plain text for typeahead when `label` isn't a string */
   textValue?: string
-  /** nested items: the branch's children (none = a leaf) */
+  /** nested items: the branch's children (none = a leaf, unless `expandable`) */
   children?: ReactNode
+  /**
+   * A branch before its children exist (a directory not listed yet): it shows the
+   * chevron and opens like any branch, and `onExpandedChange` tells the app to load
+   * them. Pass the children once they are there (or a loading row meanwhile).
+   */
+  expandable?: boolean
   /** trailing content on the row (a count, a status) */
   meta?: ReactNode
   /**
@@ -97,8 +103,17 @@ export function collectRows(
   const visit = (nodes: ReactNode, level: number, parent: string | null, visible: boolean) => {
     const items = itemsOf(nodes, isItem)
     items.forEach((item, index) => {
-      const {value, label, textValue, children: nested, meta, href, onNavigate} = item.props
-      const hasChildren = Children.count(nested) > 0
+      const {
+        value,
+        label,
+        textValue,
+        children: nested,
+        meta,
+        href,
+        onNavigate,
+        expandable,
+      } = item.props
+      const hasChildren = Children.count(nested) > 0 || expandable === true
       if (hasChildren && countLeaves(nested) !== itemsOf(nested, isItem).length) complete = false
       const open = hasChildren && isOpen(value)
       total += 1