@duro-app/ui 5.12.0 → 5.13.0

package/src/components/Menu/useMenuRoot.ts

@@ -1,12 +1,9 @@
 import {useState, useCallback, useRef, useId, useEffect, useLayoutEffect} from 'react'
 import type {MenuContextValue} from './MenuContext'
 import {isOutsidePress} from '../Popover/outside'
+import {useMenuOpen, type MenuOpenOptions} from './useMenuOpen'
 
-export interface MenuRootOptions {
-  open?: boolean
-  defaultOpen?: boolean
-  onOpenChange?: (open: boolean) => void
-}
+export type MenuRootOptions = MenuOpenOptions
 
 /**
  * The menu-button pattern (WAI-ARIA APG): on open, focus moves to the
@@ -16,10 +13,8 @@ export interface MenuRootOptions {
  * elsewhere (an editor) are never intercepted, and Escape stops there so an
  * enclosing Popover or Dialog stays open.
  */
-export function useMenuRoot({open: openProp, defaultOpen = false, onOpenChange}: MenuRootOptions) {
-  const [inner, setInner] = useState(defaultOpen)
-  const controlled = openProp !== undefined
-  const open = controlled ? openProp : inner
+export function useMenuRoot(options: MenuRootOptions) {
+  const {open, openRef, setOpen} = useMenuOpen(options)
   const [highlightedId, setHighlightedId] = useState<string | null>(null)
   // Read by the keydown handler, so activating an item is not a side effect
   // inside a state updater (React may run updaters twice).
@@ -34,38 +29,24 @@ export function useMenuRoot({open: openProp, defaultOpen = false, onOpenChange}:
   const popupRef = useRef<HTMLDivElement | null>(null)
   const itemsRef = useRef(new Map<string, HTMLElement>())
   const orderRef = useRef<string[]>([])
-  const openRef = useRef(open)
-  openRef.current = open
-  const onOpenChangeRef = useRef(onOpenChange)
-  onOpenChangeRef.current = onOpenChange
-
-  const setOpen = useCallback(
-    (next: boolean) => {
-      if (next === openRef.current) return
-      if (!controlled) setInner(next)
-      onOpenChangeRef.current?.(next)
-    },
-    [controlled],
-  )
-
   // Closes and leaves focus where it is (a press elsewhere put it there).
   const dismiss = useCallback(() => {
     if (!openRef.current) return
     setOpen(false)
     setHighlightedId(null)
-  }, [setOpen])
+  }, [openRef, setOpen])
 
   // Closes and puts focus back on the trigger.
   const close = useCallback(() => {
     if (!openRef.current) return
     dismiss()
     triggerRef.current?.focus()
-  }, [dismiss])
+  }, [openRef, dismiss])
 
   const toggle = useCallback(() => {
     if (openRef.current) close()
     else setOpen(true)
-  }, [close, setOpen])
+  }, [openRef, close, setOpen])
 
   // On open: focus the menu and highlight the first item. Child effects (item
   // registration) run before this parent effect, so orderRef is populated.

package/src/components/Popover/Popover.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Non-modal anchored overlay for small interactive content. Compound component — Root is required (throws without it). Anchored to Popover.Trigger, or to a virtual anchor (a () => DOMRect) when there is no Trigger; call reposition() through a ref when the anchor moves. Popover.Trigger takes size="small" beside small Toggles. Popover.Popup raised draws it over another floating surface (floatingRaised, popoverRaised in a modal), never over a modal.',
+    'Non-modal anchored overlay for small interactive content. Compound component — Root is required (throws without it). Anchored to Popover.Trigger, or to a virtual anchor (a () => DOMRect) when there is no Trigger; call reposition() through a ref when the anchor moves. Popover.Trigger takes size="small" beside small Toggles. Popover.Popup raised draws it over another floating surface (floatingRaised, popoverRaised in a modal), never over a modal. On React Native the popup is modal: it is placed against Popover.Trigger in an overlay, a press outside or the Android back button closes it, and screen-reader focus moves in on open and back to the trigger on close; anchor, ignore and raised are web only.',
   whenToUse: [
     'A small form or controls tied to one element that stay open while you work in them',
     'Anchoring to a spot that is not a button (a canvas point, a text selection) with a virtual anchor',

package/src/components/Popover/Popover.native.tsx

@@ -0,0 +1,205 @@
+import {
+  createContext,
+  type ReactNode,
+  type Ref,
+  type RefObject,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useImperativeHandle,
+  useRef,
+  useState,
+} from 'react'
+import {Pressable} from 'react-native'
+import {html} from 'react-strict-dom'
+import {styles} from './styles.css'
+import {nativeStyles} from './native.css'
+import type {PopoverAlign, PopoverSide} from './position'
+import {AnchoredOverlay} from '../../shared/portal/AnchoredOverlay'
+import {focusForAccessibility} from '../../shared/accessibilityFocus'
+import {mergeRefs} from '../../shared/mergeRefs'
+import {ModalContext} from '../../shared/ModalContext'
+import type {ControlSize} from '../../shared/types'
+import {useTooltipHint} from '../Tooltip/TooltipHint'
+import {ControlContextBoundary} from '../Toolbar/ControlContextBoundary'
+
+interface PopoverContextValue {
+  open: boolean
+  setOpen: (open: boolean) => void
+  popoverId: string
+  side: PopoverSide
+  align: PopoverAlign
+  triggerRef: RefObject<unknown>
+  /** Bumped by `reposition()`: the popup measures its trigger again */
+  placement: number
+}
+
+const PopoverContext = createContext<PopoverContextValue | null>(null)
+
+function usePopover(part: string) {
+  const ctx = useContext(PopoverContext)
+  if (!ctx) throw new Error(`Popover.${part} must be used within Popover.Root`)
+  return ctx
+}
+
+export interface PopoverHandle {
+  /** Place the popup against its trigger again. */
+  reposition: () => void
+}
+
+interface RootProps {
+  children: ReactNode
+  open?: boolean
+  defaultOpen?: boolean
+  onOpenChange?: (open: boolean) => void
+  side?: PopoverSide
+  align?: PopoverAlign
+  /** Web only: native places the popup against Popover.Trigger. */
+  anchor?: () => DOMRect
+  /** Web only: on native the popup is modal, so nothing outside it is pressed. */
+  ignore?: ReadonlyArray<unknown>
+  ref?: Ref<PopoverHandle>
+}
+
+/**
+ * Native Popover (plan N0, Slice B): the popup is placed against the trigger
+ * in an OverlayModal, so it is modal on native where the web's is not. A
+ * press outside or Android's back button closes it; the screen reader's
+ * focus moves into it on open and back to the trigger on close.
+ */
+function Root({
+  children,
+  open: openProp,
+  defaultOpen = false,
+  onOpenChange,
+  side = 'bottom',
+  align = 'start',
+  ref,
+}: RootProps) {
+  const [inner, setInner] = useState(defaultOpen)
+  const controlled = openProp !== undefined
+  const open = controlled ? openProp : inner
+  const popoverId = useId()
+  const triggerRef = useRef<unknown>(null)
+  const [placement, setPlacement] = useState(0)
+  const openRef = useRef(open)
+  openRef.current = open
+
+  const setOpen = useCallback(
+    (next: boolean) => {
+      if (!controlled) setInner(next)
+      if (next !== openRef.current) onOpenChange?.(next)
+    },
+    [controlled, onOpenChange],
+  )
+
+  useImperativeHandle(ref, () => ({reposition: () => setPlacement((n) => n + 1)}), [])
+
+  const wasOpen = useRef(open)
+  useEffect(() => {
+    if (wasOpen.current && !open) focusForAccessibility(triggerRef.current, 'Popover')
+    wasOpen.current = open
+  }, [open])
+
+  return (
+    <PopoverContext.Provider value={{open, setOpen, popoverId, side, align, triggerRef, placement}}>
+      {children}
+    </PopoverContext.Provider>
+  )
+}
+
+interface TriggerProps {
+  children: ReactNode
+  /** Accessible name: required when the label is an icon only. */
+  'aria-label'?: string
+  /** `small` matches a small Toggle or Button beside it. Default: `default`. */
+  size?: ControlSize
+  /** The trigger's host, e.g. to measure it. */
+  ref?: Ref<unknown>
+}
+
+/**
+ * An RN Pressable host, so it carries an enclosing Tooltip's text as its hint.
+ *
+ * holds-until: react-strict-dom maps aria-description to accessibilityHint
+ * (https://github.com/react/react-strict-dom/issues/524).
+ */
+function Trigger({children, 'aria-label': ariaLabel, size = 'default', ref}: TriggerProps) {
+  const {open, setOpen, triggerRef} = usePopover('Trigger')
+  const hint = useTooltipHint()
+  return (
+    <Pressable
+      ref={mergeRefs(triggerRef, ref) as Ref<never>}
+      onPress={() => setOpen(!open)}
+      accessibilityRole="button"
+      accessibilityLabel={ariaLabel}
+      accessibilityHint={hint}
+      accessibilityState={{expanded: open}}
+    >
+      <html.div
+        style={[styles.trigger, nativeStyles.nativeFlex, size === 'small' && styles.triggerSmall]}
+      >
+        {children}
+      </html.div>
+    </Pressable>
+  )
+}
+
+interface PopupProps {
+  children: ReactNode
+  /** Accessible name for the dialog. */
+  label: string
+  /** Web only: on native every popup is its own Modal, above what opened it. */
+  raised?: boolean
+}
+
+function Popup({children, label}: PopupProps) {
+  const {open, setOpen, popoverId, side, align, triggerRef, placement} = usePopover('Popup')
+  const popupRef = useRef<HTMLDivElement>(null)
+  return (
+    <AnchoredOverlay
+      key={placement}
+      visible={open}
+      anchorRef={triggerRef}
+      side={side}
+      align={align}
+      onRequestClose={() => setOpen(false)}
+      onShow={() => focusForAccessibility(popupRef.current, 'Popover')}
+    >
+      <html.div
+        ref={popupRef}
+        id={popoverId}
+        role="dialog"
+        aria-modal
+        aria-label={label}
+        style={[styles.popup, nativeStyles.popupInPlace]}
+      >
+        {/* Modal on native: a Popover or Menu opened inside it stacks above it. */}
+        <ModalContext.Provider value={true}>
+          <ControlContextBoundary>{children}</ControlContextBoundary>
+        </ModalContext.Provider>
+      </html.div>
+    </AnchoredOverlay>
+  )
+}
+
+function Close({children}: {children: ReactNode}) {
+  const {setOpen} = usePopover('Close')
+  return (
+    <html.button
+      type="button"
+      onClick={() => setOpen(false)}
+      style={[styles.close, nativeStyles.nativeFlex]}
+    >
+      {children}
+    </html.button>
+  )
+}
+
+export const Popover = {
+  Root,
+  Trigger,
+  Popup,
+  Close,
+}

package/src/components/Popover/native.css.ts

@@ -0,0 +1,13 @@
+import {css} from 'react-strict-dom'
+
+/** Native Popover additions to the shared styles. */
+export const nativeStyles = css.create({
+  // The AnchoredOverlay's view places the popup; it flows inside it.
+  // RSD on native lays out only display: flex, not the web's inline-flex.
+  nativeFlex: {
+    display: 'flex',
+  },
+  popupInPlace: {
+    position: 'relative',
+  },
+})

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,
+}