@duro-app/ui 5.12.0 → 5.14.0

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

@@ -124,4 +124,15 @@ export const styles = css.create({
   hidden: {
     display: 'none',
   },
+  // Popup's `empty`: no items to choose from.
+  empty: {
+    paddingTop: spacing.md,
+    paddingBottom: spacing.md,
+    paddingLeft: spacing.md,
+    paddingRight: spacing.md,
+    fontFamily: typography.fontFamily,
+    fontSize: typography.fontSizeSm,
+    color: colors.textMuted,
+    textAlign: 'center',
+  },
 })

package/src/components/Select/useSelectRoot.ts

@@ -1,27 +1,13 @@
 import {useState, useCallback, useMemo, useRef, useId, useEffect} from 'react'
-import {useControllableValue} from '../../hooks/useControllableValue'
 import type {SelectContextValue} from './SelectContext'
+import {useSelectState, type SelectStateOptions} from './selectState'
 
-interface UseSelectRootOptions {
-  defaultValue?: string
-  value?: string
-  onValueChange?: (value: string | null) => void
-  initialLabels?: Record<string, string>
-}
-
-export function useSelectRoot({
-  defaultValue,
-  value: controlledValue,
-  onValueChange,
-  initialLabels,
-}: UseSelectRootOptions) {
-  const [value, setValue] = useControllableValue<string | null>(
-    controlledValue,
-    defaultValue ?? null,
-    onValueChange,
-  )
-  const [open, setOpen] = useState(false)
-  const [labels, setLabels] = useState<Record<string, string>>(initialLabels ?? {})
+/**
+ * The web adapter over the shared Select state: the highlighted option,
+ * document order, keys and DOM focus (the WAI-ARIA select-only combobox).
+ */
+export function useSelectRoot(options: SelectStateOptions) {
+  const {value, setValue, open, setOpen, labels, registerLabel} = useSelectState(options)
   const [highlightedId, setHighlightedId] = useState<string | null>(null)
   const listboxId = useId()
   const rootRef = useRef<HTMLDivElement>(null)
@@ -33,7 +19,7 @@ export function useSelectRoot({
     setOpen(false)
     setHighlightedId(null)
     triggerRef.current?.focus()
-  }, [])
+  }, [setOpen])
 
   const toggle = useCallback(() => {
     setOpen((prev) => {
@@ -54,14 +40,7 @@ export function useSelectRoot({
       }
       return !prev
     })
-  }, [value])
-
-  const registerLabel = useCallback((v: string, label: string) => {
-    setLabels((prev) => {
-      if (prev[v] === label) return prev
-      return {...prev, [v]: label}
-    })
-  }, [])
+  }, [value, setOpen])
 
   const registerItem = useCallback((id: string, itemValue: string, element: HTMLElement) => {
     itemsRef.current.set(id, {value: itemValue, element})

package/src/components/SideNav/Chevron.native.tsx

@@ -0,0 +1,20 @@
+import Svg, {Path} from 'react-native-svg'
+import {SIZES_PX} from '@duro-app/tokens/keys'
+import {useResolvedColors} from '../ThemeProvider/ThemeProvider'
+import type {ChevronProps} from './types'
+
+/** The web's chevron, drawn with react-native-svg in the trigger's resolved colour. */
+export function Chevron({color}: ChevronProps) {
+  const stroke = useResolvedColors()[color]
+  return (
+    <Svg width={SIZES_PX.glyphXs} height={SIZES_PX.glyphXs} viewBox="0 0 24 24" fill="none">
+      <Path
+        d="M9 18l6-6-6-6"
+        stroke={stroke}
+        strokeWidth={2.5}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </Svg>
+  )
+}

package/src/components/SideNav/Chevron.tsx

@@ -0,0 +1,20 @@
+import {SIZES_PX} from '@duro-app/tokens/keys'
+import type {ChevronProps} from './types'
+
+/** The group disclosure's chevron, drawn in the trigger's text colour. */
+export function Chevron(_props: ChevronProps) {
+  return (
+    <svg
+      width={SIZES_PX.glyphXs}
+      height={SIZES_PX.glyphXs}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="M9 18l6-6-6-6" />
+    </svg>
+  )
+}

package/src/components/SideNav/SideNav.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Vertical side navigation. `Section` is a labelled block that is always open — the default for primary navigation. `Group` is the same block behind a chevron (a disclosure) — reach for it only for a rare/advanced region, an unbounded data-driven list, or a rail long enough that flat stops reading as an overview; mixing the two in one rail is the healthy shape. `Item`s take an optional `icon` and show an active left-marker. Supports controlled and uncontrolled active item. Compound component — Root is required.',
+    'Vertical side navigation. `Section` is a labelled block that is always open — the default for primary navigation. `Group` is the same block behind a chevron (a disclosure) — reach for it only for a rare/advanced region, an unbounded data-driven list, or a rail long enough that flat stops reading as an overview; mixing the two in one rail is the healthy shape. `Item`s take an optional `icon` and show an active left-marker. Supports controlled and uncontrolled active item. Compound component — Root is required. On React Native the same parts render, and a Group knows whether it holds the active item from its Items, not from the DOM.',
   whenToUse: [
     'App-level sidebar navigation — flat `Section`s, every destination visible',
     'Settings navigation with labelled regions',

package/src/components/SideNav/SideNav.tsx

@@ -1,8 +1,22 @@
-import {type ReactNode, useState, useCallback, useRef, useEffect, useId} from 'react'
+import {
+  type ReactNode,
+  createContext,
+  useContext,
+  useState,
+  useCallback,
+  useRef,
+  useEffect,
+  useId,
+} from 'react'
 import {html} from 'react-strict-dom'
 import {styles} from './styles.css'
 import {useControllableValue} from '../../hooks/useControllableValue'
 import {SideNavContext, useSideNav} from './SideNavContext'
+import {isNative} from '../../platform'
+import {Chevron} from './Chevron'
+
+/** A Group's own items: each Item inside it registers its value here. */
+const GroupItemsContext = createContext<((value: string) => () => void) | null>(null)
 
 /**
  * SideNav has two ways to chunk a rail, and they are NOT interchangeable.
@@ -130,39 +144,40 @@ function Group({children, label, groupKey, defaultExpanded}: GroupProps) {
   const key = groupKey ?? label
   const {expandedGroups, toggleGroup, expandGroup, activeValue} = useSideNav()
   const isExpanded = expandedGroups.has(key)
-  const groupRef = useRef<HTMLDivElement>(null)
   const triggerId = useId()
   const panelId = useId()
+  // The values of the Items inside, from props and state rather than a DOM
+  // query, so both platforms know whether the active item is in here.
+  const [values, setValues] = useState<ReadonlySet<string>>(() => new Set())
+  const registerValue = useCallback((value: string) => {
+    setValues((prev) => (prev.has(value) ? prev : new Set(prev).add(value)))
+    return () =>
+      setValues((prev) => {
+        if (!prev.has(value)) return prev
+        const next = new Set(prev)
+        next.delete(value)
+        return next
+      })
+  }, [])
+  const hasActiveChild = activeValue !== null && values.has(activeValue)
 
   // Auto-expand if this group contains the active item. Uses expandGroup (not
   // toggleGroup) so it never races the defaultExpanded effect into a closed
   // state when the active item lives in a defaultExpanded group.
   useEffect(() => {
-    if (!activeValue || expandedGroups.has(key)) return
-    const el = groupRef.current
-    if (!el) return
-    const activeBtn = el.querySelector(`[data-nav-value="${activeValue}"]`)
-    if (activeBtn) {
-      expandGroup(key)
-    }
-  }, [activeValue, key, expandedGroups, expandGroup])
+    if (hasActiveChild && !expandedGroups.has(key)) expandGroup(key)
+  }, [hasActiveChild, key, expandedGroups, expandGroup])
 
-  // Expand on first render if defaultExpanded (idempotent add, not a toggle).
+  // Expand once, on mount, if defaultExpanded (idempotent add, not a toggle).
+  const appliedDefault = useRef(false)
   useEffect(() => {
-    if (defaultExpanded) {
-      expandGroup(key)
-    }
-    // Only run on mount
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [])
-
-  const hasActiveChild = (() => {
-    if (!activeValue || !groupRef.current) return false
-    return !!groupRef.current.querySelector(`[data-nav-value="${activeValue}"]`)
-  })()
+    if (appliedDefault.current) return
+    appliedDefault.current = true
+    if (defaultExpanded) expandGroup(key)
+  }, [defaultExpanded, expandGroup, key])
 
   return (
-    <html.div ref={groupRef} style={styles.group}>
+    <html.div style={styles.group}>
       <html.button
         type="button"
         id={triggerId}
@@ -171,27 +186,26 @@ function Group({children, label, groupKey, defaultExpanded}: GroupProps) {
         aria-expanded={isExpanded}
         aria-controls={isExpanded ? panelId : undefined}
       >
-        <html.span style={[styles.chevron, isExpanded && styles.chevronOpen]}>
-          <svg
-            width={10}
-            height={10}
-            viewBox="0 0 24 24"
-            fill="none"
-            stroke="currentColor"
-            strokeWidth={2.5}
-            strokeLinecap="round"
-            strokeLinejoin="round"
-          >
-            <path d="M9 18l6-6-6-6" />
-          </svg>
+        <html.span
+          style={[styles.chevron, isNative && styles.nativeFlex, isExpanded && styles.chevronOpen]}
+        >
+          <Chevron color={hasActiveChild ? 'text' : 'textMuted'} />
         </html.span>
-        {label}
+        {/* Native refuses bare text beside the chevron's view; the web keeps it bare. */}
+        {isNative ? <html.span>{label}</html.span> : label}
       </html.button>
-      {isExpanded ? (
-        <html.div id={panelId} role="group" aria-labelledby={triggerId} style={styles.items}>
+      {/* Kept mounted while collapsed, so its Items stay registered with the group. */}
+      <GroupItemsContext.Provider value={registerValue}>
+        <html.div
+          id={panelId}
+          role="group"
+          aria-labelledby={triggerId}
+          hidden={isExpanded ? undefined : true}
+          style={[styles.items, !isExpanded && styles.itemsHidden]}
+        >
           {children}
         </html.div>
-      ) : null}
+      </GroupItemsContext.Provider>
     </html.div>
   )
 }
@@ -239,11 +253,13 @@ interface ItemProps {
 
 function Item({value, children, icon}: ItemProps) {
   const {activeValue, onSelect, registerItem} = useSideNav()
+  const registerInGroup = useContext(GroupItemsContext)
   const isActive = activeValue === value
 
   useEffect(() => {
     return registerItem(value)
   }, [value, registerItem])
+  useEffect(() => registerInGroup?.(value), [value, registerInGroup])
 
   return (
     <html.button
@@ -255,7 +271,7 @@ function Item({value, children, icon}: ItemProps) {
     >
       <html.span aria-hidden style={[styles.marker, isActive && styles.markerActive]} />
       {icon ? (
-        <html.span aria-hidden style={styles.itemIcon}>
+        <html.span aria-hidden style={[styles.itemIcon, isNative && styles.nativeFlex]}>
           {icon}
         </html.span>
       ) : null}

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

@@ -137,6 +137,14 @@ export const styles = css.create({
     transitionDuration: duration.fast,
     transitionTimingFunction: easing.standard,
   },
+  // A collapsed group's items stay mounted (they tell the group what it holds), unseen.
+  itemsHidden: {
+    display: 'none',
+  },
+  // RSD on native lays out only display: flex, not the web's inline-flex.
+  nativeFlex: {
+    display: 'flex',
+  },
   markerActive: {
     height: sizes.navMarkerH,
   },

package/src/components/SideNav/types.ts

@@ -0,0 +1,6 @@
+import type {ColorToken} from '@duro-app/tokens/keys'
+
+export interface ChevronProps {
+  /** Native only: the web inherits the trigger's text colour. */
+  color: ColorToken
+}

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

@@ -0,0 +1,40 @@
+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. 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',
+  ],
+  whenNotToUse: [
+    'A fixed list/detail layout nobody resizes — use Grid layout="split"',
+    'Navigation beside content — use AppShell or the page-with-sidenav recipe',
+    'A short-lived inspection over a list — use DetailPanel',
+  ],
+  anatomy: {
+    required: ['Root', 'Pane'],
+    optional: ['Handle'],
+  },
+  relatedTo: [
+    {
+      component: 'Grid',
+      kind: 'contrast',
+      relationship: 'Grid layout="split" is a fixed split; SplitPane lets people resize it',
+    },
+    {
+      component: 'DetailPanel',
+      kind: 'contrast',
+      relationship: 'DetailPanel overlays the list; SplitPane keeps both side by side',
+    },
+  ],
+  example: `<SplitPane.Root aria-label="Resize the session list" minSize="sidebarW" maxSize="panelLg">
+  <SplitPane.Pane>
+    <List.Root aria-label="Sessions">…</List.Root>
+  </SplitPane.Pane>
+  <SplitPane.Handle />
+  <SplitPane.Pane>
+    <Panel.Root>…</Panel.Root>
+  </SplitPane.Pane>
+</SplitPane.Root>`,
+}

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

@@ -0,0 +1,47 @@
+import type {ReactNode} from 'react'
+import {html} from 'react-strict-dom'
+import type {SizeToken} from '@duro-app/tokens/keys'
+import type {Breakpoint} from '@duro-app/tokens/tokens/breakpoints.css'
+import {styles} from './styles.css'
+
+interface RootProps {
+  children: ReactNode
+  /** Web only: on a phone the panes stack. */
+  defaultSize?: SizeToken
+  /** Web only. */
+  size?: number
+  /** Web only. */
+  onSizeChange?: (px: number) => void
+  /** Web only. */
+  minSize?: SizeToken
+  /** Web only. */
+  maxSize?: SizeToken
+  /** Web only: a phone is below every breakpoint, so native always stacks. */
+  collapseBelow?: Breakpoint
+  /** The handle's accessible name (web only: native has no handle). */
+  'aria-label': string
+}
+
+/**
+ * Native SplitPane (plan N0, Slice B): a phone shows one pane at a time's
+ * worth of width, so the panes stack in one column and there is no handle —
+ * the shape the web takes below `collapseBelow`.
+ */
+function Root({children}: RootProps) {
+  return <html.div style={[styles.root, styles.rootStacked]}>{children}</html.div>
+}
+
+function Pane({children}: {children: ReactNode}) {
+  return <html.div style={styles.stackedPane}>{children}</html.div>
+}
+
+/** No handle on native. */
+function Handle() {
+  return null
+}
+
+export const SplitPane = {
+  Root,
+  Pane,
+  Handle,
+}

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

@@ -0,0 +1,148 @@
+import type {Meta, StoryObj} from '@storybook/react'
+import {expect, fn, userEvent, waitFor} from 'storybook/test'
+import {css, html} from 'react-strict-dom'
+import {SIZES_PX, SPACING_PX, type SizeToken} from '@duro-app/tokens/keys'
+import type {Breakpoint} from '@duro-app/tokens/tokens/breakpoints.css'
+import {SplitPane} from './SplitPane'
+import {setViewport} from '../Drawer/touchInput'
+import {List} from '../List/List'
+import {Panel} from '../Panel/Panel'
+import {Heading} from '../Heading/Heading'
+import {Text} from '../Text/Text'
+
+const meta: Meta = {
+  title: 'Components/SplitPane',
+  parameters: {layout: 'fullscreen'},
+}
+
+export default meta
+type Story = StoryObj
+
+const SESSIONS = ['Refactor auth', 'Flaky e2e', 'Release notes', 'Docs pass', 'Perf trace']
+
+// A SplitPane fills its parent: the story gives it the viewport's height.
+const frame = css.create({fill: {height: '100vh'}})
+
+interface SplitArgs {
+  defaultSize: SizeToken
+  minSize: SizeToken
+  maxSize: SizeToken
+  collapseBelow: Breakpoint
+  onSizeChange?: (px: number) => void
+}
+
+const DEFAULT_ARGS: SplitArgs = {
+  defaultSize: 'sidebarW',
+  minSize: 'sidebarW',
+  maxSize: 'panelLg',
+  collapseBelow: 'sm',
+}
+
+// Width tokens that make sense for a pane, smallest first.
+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} = {...DEFAULT_ARGS, ...props}
+  return (
+    <html.div style={frame.fill}>
+      <SplitPane.Root
+        aria-label="Resize the session list"
+        defaultSize={defaultSize}
+        minSize={minSize}
+        maxSize={maxSize}
+        collapseBelow={collapseBelow}
+        onSizeChange={onSizeChange}
+      >
+        <SplitPane.Pane>
+          <List.Root aria-label="Sessions">
+            {SESSIONS.map((s) => (
+              <List.Item key={s}>
+                <List.Text>{s}</List.Text>
+              </List.Item>
+            ))}
+          </List.Root>
+        </SplitPane.Pane>
+        <SplitPane.Handle />
+        <SplitPane.Pane>
+          <Panel.Root>
+            <Panel.Header>
+              <Heading level={2}>Refactor auth</Heading>
+            </Panel.Header>
+            <Panel.Body>
+              <Text>The transcript of the selected session.</Text>
+            </Panel.Body>
+          </Panel.Root>
+        </SplitPane.Pane>
+      </SplitPane.Root>
+    </html.div>
+  )
+}
+
+export const Default: StoryObj<SplitArgs> = {
+  args: {...DEFAULT_ARGS, onSizeChange: fn()},
+  argTypes: {
+    defaultSize: {
+      control: 'select',
+      options: PANE_SIZES,
+      description: 'Starting width of the first pane',
+    },
+    minSize: {control: 'select', options: PANE_SIZES, description: 'Narrowest the first pane goes'},
+    maxSize: {control: 'select', options: PANE_SIZES, description: 'Widest the first pane goes'},
+    collapseBelow: {
+      control: 'select',
+      options: ['xs', 'sm', 'md', 'lg', 'xl'],
+      description: "Below this breakpoint (the split's own width) the panes stack",
+    },
+  },
+  // Keyed by the starting width: it seeds state on mount, so a change remounts the split.
+  render: (args) => <Split key={args.defaultSize} {...args} />,
+}
+
+const separator = () => document.querySelector<HTMLElement>('[role="separator"]')
+
+export const KeyboardMovesTheSeparator: Story = {
+  render: () => <Split />,
+  beforeEach: async () => {
+    await setViewport(1200, 800)
+  },
+  play: async () => {
+    await waitFor(() => expect(separator()).not.toBeNull())
+    const handle = separator()!
+    const primary = document.getElementById(handle.getAttribute('aria-controls')!)!
+    await expect(handle).toHaveAttribute('aria-valuenow', String(SIZES_PX.sidebarW))
+    await expect(handle).toHaveAttribute('aria-valuemin', String(SIZES_PX.sidebarW))
+    await expect(handle).toHaveAttribute('aria-valuemax', String(SIZES_PX.panelLg))
+
+    handle.focus()
+    await userEvent.keyboard('{ArrowRight}')
+    const after = SIZES_PX.sidebarW + SPACING_PX.md
+    await expect(handle).toHaveAttribute('aria-valuenow', String(after))
+    await waitFor(() => expect(primary.getBoundingClientRect().width).toBeCloseTo(after, 0))
+
+    await userEvent.keyboard('{End}')
+    await expect(handle).toHaveAttribute('aria-valuenow', String(SIZES_PX.panelLg))
+    // the bound holds
+    await userEvent.keyboard('{ArrowRight}')
+    await expect(handle).toHaveAttribute('aria-valuenow', String(SIZES_PX.panelLg))
+
+    await userEvent.keyboard('{Home}')
+    await expect(handle).toHaveAttribute('aria-valuenow', String(SIZES_PX.sidebarW))
+  },
+}
+
+export const NarrowStacksInOneColumn: Story = {
+  render: () => <Split />,
+  beforeEach: async () => {
+    await setViewport(390, 844)
+  },
+  play: async ({canvas}) => {
+    await waitFor(() => expect(separator()).toBeNull())
+    const list = canvas.getByRole('list', {name: 'Sessions'})
+    const heading = canvas.getByRole('heading', {name: 'Refactor auth'})
+    // one column: the detail sits below the list
+    await expect(heading.getBoundingClientRect().top).toBeGreaterThan(
+      list.getBoundingClientRect().bottom - 1,
+    )
+  },
+}