@duro-app/ui 5.12.0 → 5.14.0

package/src/components/SplitPane/SplitPane.tsx

@@ -0,0 +1,218 @@
+import {
+  Children,
+  createContext,
+  isValidElement,
+  type ReactNode,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useRef,
+  useState,
+} from 'react'
+import {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 {useContainerBelow} from '../../hooks/useContainerBelow'
+import {styles} from './styles.css'
+
+interface SplitPaneContextValue {
+  size: number
+  min: number
+  max: number
+  setSize: (px: number) => void
+  stacked: boolean
+  primaryId: string
+  label: string
+}
+
+const SplitPaneContext = createContext<SplitPaneContextValue | null>(null)
+
+function useSplitPane(part: string) {
+  const ctx = useContext(SplitPaneContext)
+  if (!ctx) throw new Error(`SplitPane.${part} must be used within SplitPane.Root`)
+  return ctx
+}
+
+/** Which Pane this is, in order: the first is the one the handle sizes. */
+const PaneIndexContext = createContext(0)
+
+/** One arrow press moves the handle this far; with Shift, `STEP_LARGE`. */
+const STEP = SPACING_PX.md
+const STEP_LARGE = SPACING_PX.xxl
+
+const clamp = (px: number, min: number, max: number) => Math.min(max, Math.max(min, px))
+
+interface RootProps {
+  children: ReactNode
+  /** The primary (first) pane's starting width, a size token. Default: `sidebarW` */
+  defaultSize?: SizeToken
+  /** Controlled width of the primary pane, in px (from `onSizeChange`) */
+  size?: number
+  /** Called with the primary pane's new width while the handle moves */
+  onSizeChange?: (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` */
+  maxSize?: SizeToken
+  /** Below this breakpoint, measured on the split's own width, the panes stack. Default: `sm` */
+  collapseBelow?: Breakpoint
+  /** The handle's accessible name ("Resize list"). */
+  'aria-label': string
+}
+
+/**
+ * Two panes side by side with a resizable separator between them: a list
+ * and its detail, an editor and its preview. The first Pane is sized by the
+ * handle (pointer drag, arrow keys, Home and End); the second takes the rest.
+ * Below `collapseBelow` the panes stack in one column and the handle goes.
+ */
+function Root({
+  children,
+  defaultSize = 'sidebarW',
+  size: controlledSize,
+  onSizeChange,
+  minSize = 'sidebarW',
+  maxSize = 'panelLg',
+  collapseBelow = 'sm',
+  'aria-label': label,
+}: RootProps) {
+  const min = SIZES_PX[minSize]
+  const max = Math.max(min, SIZES_PX[maxSize])
+  const [inner, setInner] = useState(() => clamp(SIZES_PX[defaultSize], min, max))
+  const size = clamp(controlledSize ?? inner, min, max)
+  const setSize = useCallback(
+    (px: number) => {
+      const next = clamp(Math.round(px), min, max)
+      if (controlledSize === undefined) setInner(next)
+      onSizeChange?.(next)
+    },
+    [controlledSize, onSizeChange, min, max],
+  )
+  const rootRef = useRef<HTMLDivElement>(null)
+  const stacked = useContainerBelow(rootRef, collapseBelow)
+  const primaryId = useId()
+
+  let paneIndex = 0
+  const items = Children.map(children, (child) => {
+    if (isValidElement(child) && child.type === Pane) {
+      const index = paneIndex++
+      return <PaneIndexContext.Provider value={index}>{child}</PaneIndexContext.Provider>
+    }
+    return child
+  })
+
+  return (
+    <SplitPaneContext.Provider value={{size, min, max, setSize, stacked, primaryId, label}}>
+      <html.div ref={rootRef} style={[styles.root, stacked && styles.rootStacked]}>
+        {items}
+      </html.div>
+    </SplitPaneContext.Provider>
+  )
+}
+
+function Pane({children}: {children: ReactNode}) {
+  const {size, stacked, primaryId} = useSplitPane('Pane')
+  const primary = useContext(PaneIndexContext) === 0
+  return (
+    <html.div
+      id={primary ? primaryId : undefined}
+      style={[
+        primary ? [styles.primary, !stacked && styles.primarySize(size)] : styles.secondary,
+        stacked && styles.stackedPane,
+      ]}
+    >
+      {children}
+    </html.div>
+  )
+}
+
+function Handle() {
+  const {size, min, max, setSize, stacked, primaryId, label} = useSplitPane('Handle')
+  const [hovered, setHovered] = useState(false)
+  const [keyboardFocus, setKeyboardFocus] = useState(false)
+  const [dragging, setDragging] = useState(false)
+  const drag = useRef<{startX: number; startSize: number} | null>(null)
+  const handleRef = useRef<HTMLDivElement>(null)
+
+  // Arrow keys move the handle, Shift by larger steps; Home and End go to
+  // the bounds. A DOM listener, for the full KeyboardEvent.
+  useEffect(() => {
+    const el = handleRef.current
+    if (!el) return
+    function onKeyDown(e: KeyboardEvent) {
+      const step = e.shiftKey ? STEP_LARGE : STEP
+      const next =
+        e.key === 'ArrowLeft'
+          ? size - step
+          : e.key === 'ArrowRight'
+            ? size + step
+            : e.key === 'Home'
+              ? min
+              : e.key === 'End'
+                ? max
+                : null
+      if (next === null) return
+      e.preventDefault()
+      setSize(next)
+    }
+    el.addEventListener('keydown', onKeyDown)
+    return () => el.removeEventListener('keydown', onKeyDown)
+  }, [size, min, max, setSize, stacked])
+
+  if (stacked) return null
+  const active = hovered || keyboardFocus || dragging
+
+  return (
+    <html.div
+      ref={handleRef}
+      role="separator"
+      tabIndex={0}
+      aria-label={label}
+      aria-orientation="vertical"
+      aria-controls={primaryId}
+      aria-valuenow={size}
+      aria-valuemin={min}
+      aria-valuemax={max}
+      style={styles.handle}
+      onFocus={(e: {currentTarget: HTMLElement}) =>
+        setKeyboardFocus(e.currentTarget.matches(':focus-visible'))
+      }
+      onBlur={() => setKeyboardFocus(false)}
+      onPointerEnter={() => setHovered(true)}
+      onPointerLeave={() => setHovered(false)}
+      onPointerDown={(e: {
+        button: number
+        clientX: number
+        pointerId: number
+        currentTarget: HTMLElement
+      }) => {
+        if (e.button !== 0) return
+        e.currentTarget.setPointerCapture(e.pointerId)
+        drag.current = {startX: e.clientX, startSize: size}
+        setDragging(true)
+      }}
+      onPointerMove={(e: {clientX: number}) => {
+        if (!drag.current) return
+        setSize(drag.current.startSize + e.clientX - drag.current.startX)
+      }}
+      onPointerUp={() => {
+        drag.current = null
+        setDragging(false)
+      }}
+      onPointerCancel={() => {
+        drag.current = null
+        setDragging(false)
+      }}
+    >
+      <html.span aria-hidden style={[styles.line, active && styles.lineActive]} />
+      <html.span aria-hidden style={[styles.grip, active && styles.gripShown]} />
+    </html.div>
+  )
+}
+
+export const SplitPane = {
+  Root,
+  Pane,
+  Handle,
+}

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

@@ -0,0 +1,81 @@
+import {css} from 'react-strict-dom'
+import {colors} from '@duro-app/tokens/tokens/colors.css'
+import {spacing, radii} from '@duro-app/tokens/tokens/spacing.css'
+import {duration, easing} from '@duro-app/tokens/tokens/motion.css'
+import {borders} from '@duro-app/tokens/tokens/borders.css'
+
+/**
+ * SplitPane, the picked B0 direction (docs/mockups/split-pane/Hairline.dc.html):
+ * a hairline between the panes inside a wider hit area; hover, keyboard
+ * focus or a drag thicken it to the accent and show a grip.
+ */
+export const styles = css.create({
+  root: {
+    display: 'flex',
+    flexDirection: 'row',
+    alignItems: 'stretch',
+    minWidth: 0,
+    minHeight: 0,
+    height: '100%',
+  },
+  // Below `collapseBelow`: one column, the panes stacked, no handle.
+  rootStacked: {
+    flexDirection: 'column',
+    height: 'auto',
+  },
+  primary: {
+    flexShrink: 0,
+    minWidth: 0,
+    overflow: 'auto',
+  },
+  primarySize: (px: number) => ({width: px}),
+  secondary: {
+    flexGrow: 1,
+    flexBasis: 0,
+    minWidth: 0,
+    overflow: 'auto',
+  },
+  stackedPane: {
+    width: '100%',
+    overflow: 'visible',
+  },
+  handle: {
+    position: 'relative',
+    flexShrink: 0,
+    display: 'flex',
+    justifyContent: 'center',
+    width: spacing.sm,
+    cursor: 'col-resize',
+    touchAction: 'none',
+    userSelect: 'none',
+    outlineStyle: 'none',
+  },
+  line: {
+    width: borders.hairline,
+    height: '100%',
+    backgroundColor: colors.border,
+    transitionProperty: 'background-color, width',
+    transitionDuration: duration.fast,
+    transitionTimingFunction: easing.standard,
+  },
+  lineActive: {
+    width: borders.strong,
+    backgroundColor: colors.accent,
+  },
+  grip: {
+    position: 'absolute',
+    top: '50%',
+    left: '50%',
+    transform: 'translate(-50%, -50%)',
+    width: spacing.xs,
+    height: spacing.xl,
+    borderRadius: radii.full,
+    backgroundColor: colors.textMuted,
+    opacity: 0,
+    transitionProperty: 'opacity',
+    transitionDuration: duration.fast,
+  },
+  gripShown: {
+    opacity: 1,
+  },
+})

package/src/components/Tabs/TabLayout.native.tsx

@@ -0,0 +1,9 @@
+import type {ReactNode} from 'react'
+import {View} from 'react-native'
+import {useReportTabLayout} from './indicator'
+
+/** Native: reports the tab's box to its List, which places the sliding indicator. */
+export function TabLayout({value, children}: {value: string; children: ReactNode}) {
+  const report = useReportTabLayout()
+  return <View onLayout={(e) => report?.(value, e.nativeEvent.layout)}>{children}</View>
+}

package/src/components/Tabs/TabLayout.tsx

@@ -0,0 +1,6 @@
+import type {ReactNode} from 'react'
+
+/** Web: the tab itself; the List measures it in the DOM (TabLayout.native.tsx reports it). */
+export function TabLayout({children}: {value: string; children: ReactNode}) {
+  return children
+}

package/src/components/Tabs/Tabs.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Tabbed interface with keyboard navigation. Supports horizontal and vertical orientation. Compound component — Root is required.',
+    'Tabbed interface with keyboard navigation. Supports horizontal and vertical orientation. Compound component — Root is required. On React Native the indicator follows each tab layout; there is no arrow-key navigation there, each tab is its own screen-reader stop.',
   whenToUse: [
     'Switching between content panels in the same view',
     'Settings pages with multiple sections',

package/src/components/Tabs/Tabs.tsx

@@ -1,8 +1,13 @@
-import {type ReactNode, useRef, useId, useEffect, useLayoutEffect, useState} from 'react'
+import {type ReactNode, useRef, useId, useEffect} from 'react'
 import {html} from 'react-strict-dom'
 import {styles} from './styles.css'
+import {isNative} from '../../platform'
 import {TabsContext, useTabs} from './TabsContext'
 import {useTabsRoot} from './useTabsRoot'
+import {useTabIndicator} from './useTabIndicator'
+import {useTabKeys} from './useTabKeys'
+import {TabLayoutContext} from './indicator'
+import {TabLayout} from './TabLayout'
 
 // --- Root ---
 
@@ -41,120 +46,14 @@ interface ListProps {
 function List({children}: ListProps) {
   const {orientation, activeValue, onSelect, tabsRef, orderRef, setIndicatorActive} = useTabs()
   const listRef = useRef<HTMLDivElement>(null)
-  const [indicator, setIndicator] = useState<{offset: number; size: number} | null>(null)
 
-  // Measure the active tab and drive the sliding indicator. useLayoutEffect so
-  // the first position is set before paint (the indicator element mounts already
-  // in place — no slide-in from zero; only later tab changes animate). Observes
-  // the active tab (its own size, e.g. a changing "(3)" count) and the list
-  // (container resize / reflow). A non-active sibling resizing while you're on
-  // another tab is the one case not caught; it self-corrects on the next
-  // selection or resize.
-  useLayoutEffect(() => {
-    const list = listRef.current
-    if (!list || !activeValue) {
-      setIndicator(null)
-      setIndicatorActive(false)
-      return
-    }
-    const el = list.querySelector<HTMLElement>(`[data-tab-value="${CSS.escape(activeValue)}"]`)
-    if (!el) {
-      setIndicator(null)
-      setIndicatorActive(false)
-      return
-    }
-    const measure = () => {
-      setIndicator(
-        orientation === 'horizontal'
-          ? {offset: el.offsetLeft, size: el.offsetWidth}
-          : {offset: el.offsetTop, size: el.offsetHeight},
-      )
-      setIndicatorActive(true)
-    }
-    measure()
-    const ro = new ResizeObserver(measure)
-    ro.observe(el)
-    ro.observe(list)
-    return () => ro.disconnect()
-  }, [activeValue, orientation, setIndicatorActive])
-
-  useEffect(() => {
-    const el = listRef.current
-    if (!el) return
-    const listEl = el
-
-    function handleKeyDown(e: KeyboardEvent) {
-      const order = orderRef.current
-      const tabs = tabsRef.current
-      if (order.length === 0) return
-
-      const prevKey = orientation === 'horizontal' ? 'ArrowLeft' : 'ArrowUp'
-      const nextKey = orientation === 'horizontal' ? 'ArrowRight' : 'ArrowDown'
-
-      let targetValue: string | null = null
-
-      switch (e.key) {
-        case nextKey: {
-          e.preventDefault()
-          const currentIdx = activeValue ? order.indexOf(activeValue) : -1
-          for (let i = 1; i <= order.length; i++) {
-            const idx = (currentIdx + i) % order.length
-            const val = order[idx]
-            if (!tabs.get(val)) {
-              targetValue = val
-              break
-            }
-          }
-          break
-        }
-        case prevKey: {
-          e.preventDefault()
-          const currentIdx = activeValue ? order.indexOf(activeValue) : 0
-          for (let i = 1; i <= order.length; i++) {
-            const idx = (currentIdx - i + order.length) % order.length
-            const val = order[idx]
-            if (!tabs.get(val)) {
-              targetValue = val
-              break
-            }
-          }
-          break
-        }
-        case 'Home': {
-          e.preventDefault()
-          for (const val of order) {
-            if (!tabs.get(val)) {
-              targetValue = val
-              break
-            }
-          }
-          break
-        }
-        case 'End': {
-          e.preventDefault()
-          for (let i = order.length - 1; i >= 0; i--) {
-            if (!tabs.get(order[i])) {
-              targetValue = order[i]
-              break
-            }
-          }
-          break
-        }
-      }
-
-      if (targetValue) {
-        onSelect(targetValue)
-        // Focus the newly activated tab button
-        const tabEl = listEl.querySelector(
-          `[data-tab-value="${targetValue}"]`,
-        ) as HTMLElement | null
-        tabEl?.focus()
-      }
-    }
-
-    el.addEventListener('keydown', handleKeyDown)
-    return () => el.removeEventListener('keydown', handleKeyDown)
-  }, [orientation, activeValue, onSelect, tabsRef, orderRef])
+  const {indicator, reportTabLayout} = useTabIndicator({
+    listRef,
+    activeValue,
+    orientation,
+    setIndicatorActive,
+  })
+  useTabKeys({listRef, orientation, activeValue, onSelect, tabsRef, orderRef})
 
   return (
     <html.div
@@ -163,7 +62,7 @@ function List({children}: ListProps) {
       aria-orientation={orientation}
       style={[styles.list, orientation === 'vertical' && styles.listVertical]}
     >
-      {children}
+      <TabLayoutContext.Provider value={reportTabLayout}>{children}</TabLayoutContext.Provider>
       {indicator && (
         <html.div
           aria-hidden
@@ -205,27 +104,30 @@ function Tab({value, disabled = false, children}: TabProps) {
   }
 
   return (
-    <html.button
-      type="button"
-      role="tab"
-      id={tabId}
-      aria-selected={isActive}
-      aria-controls={panelId}
-      aria-disabled={disabled || undefined}
-      data-tab-value={value}
-      tabIndex={isActive ? 0 : -1}
-      onClick={handleClick}
-      style={[
-        styles.tab,
-        orientation === 'vertical' && styles.tabVertical,
-        isActive &&
-          (orientation === 'vertical' ? styles.tabActiveVertical : styles.tabActiveHorizontal),
-        isActive && indicatorActive && styles.tabIndicatorActive,
-        disabled && styles.tabDisabled,
-      ]}
-    >
-      {children}
-    </html.button>
+    <TabLayout value={value}>
+      <html.button
+        type="button"
+        role="tab"
+        id={tabId}
+        aria-selected={isActive}
+        aria-controls={panelId}
+        aria-disabled={disabled || undefined}
+        data-tab-value={value}
+        tabIndex={isActive ? 0 : -1}
+        onClick={handleClick}
+        style={[
+          styles.tab,
+          isNative && styles.nativeFlex,
+          orientation === 'vertical' && styles.tabVertical,
+          isActive &&
+            (orientation === 'vertical' ? styles.tabActiveVertical : styles.tabActiveHorizontal),
+          isActive && indicatorActive && styles.tabIndicatorActive,
+          disabled && styles.tabDisabled,
+        ]}
+      >
+        {children}
+      </html.button>
+    </TabLayout>
   )
 }
 

package/src/components/Tabs/indicator.ts

@@ -0,0 +1,36 @@
+import {createContext, useContext} from 'react'
+import type {Orientation} from '../../shared/types'
+
+/** Where the sliding indicator sits along the list, in px. */
+export interface IndicatorBox {
+  offset: number
+  size: number
+}
+
+/** A tab's box inside its list, as native `onLayout` reports it. */
+export interface TabBox {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+/** Native: each Tab reports its box here, so the List places the indicator. */
+export const TabLayoutContext = createContext<((value: string, box: TabBox) => void) | null>(null)
+
+export function useReportTabLayout() {
+  return useContext(TabLayoutContext)
+}
+
+export interface TabIndicatorInput {
+  listRef: React.RefObject<HTMLDivElement | null>
+  activeValue: string | null
+  orientation: Orientation
+  setIndicatorActive: (active: boolean) => void
+}
+
+export interface TabIndicator {
+  indicator: IndicatorBox | null
+  /** Native only: what the Tabs report their layout to. */
+  reportTabLayout: ((value: string, box: TabBox) => void) | null
+}

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

@@ -32,6 +32,13 @@ export const styles = css.create({
     borderRightColor: colors.border,
     gap: 0,
   },
+  // RSD on native lays out only display: flex, not the web's inline-flex,
+  // and its Animated colour transition ends on a near-black colour: native
+  // tabs transition nothing that changes (colour and underline switch at once).
+  nativeFlex: {
+    display: 'flex',
+    transitionProperty: 'opacity',
+  },
   tab: {
     display: 'inline-flex',
     alignItems: 'center',

package/src/components/Tabs/useTabIndicator.native.ts

@@ -0,0 +1,35 @@
+import {useCallback, useEffect, useState} from 'react'
+import type {TabBox, TabIndicator, TabIndicatorInput} from './indicator'
+
+/** Native: the indicator follows the active tab's `onLayout` box. */
+export function useTabIndicator({
+  activeValue,
+  orientation,
+  setIndicatorActive,
+}: TabIndicatorInput): TabIndicator {
+  const [boxes, setBoxes] = useState<ReadonlyMap<string, TabBox>>(() => new Map())
+  const reportTabLayout = useCallback((value: string, box: TabBox) => {
+    setBoxes((prev) => {
+      const old = prev.get(value)
+      if (
+        old &&
+        old.x === box.x &&
+        old.y === box.y &&
+        old.width === box.width &&
+        old.height === box.height
+      ) {
+        return prev
+      }
+      return new Map(prev).set(value, box)
+    })
+  }, [])
+  const box = activeValue ? boxes.get(activeValue) : undefined
+  const indicator = box
+    ? orientation === 'horizontal'
+      ? {offset: box.x, size: box.width}
+      : {offset: box.y, size: box.height}
+    : null
+  const active = indicator !== null
+  useEffect(() => setIndicatorActive(active), [active, setIndicatorActive])
+  return {indicator, reportTabLayout}
+}

package/src/components/Tabs/useTabIndicator.ts

@@ -0,0 +1,49 @@
+import {useLayoutEffect, useState} from 'react'
+import type {IndicatorBox, TabIndicator, TabIndicatorInput} from './indicator'
+
+/** Web: the active tab measured in the DOM, kept current by a ResizeObserver. */
+export function useTabIndicator({
+  listRef,
+  activeValue,
+  orientation,
+  setIndicatorActive,
+}: TabIndicatorInput): TabIndicator {
+  const [indicator, setIndicator] = useState<IndicatorBox | null>(null)
+
+  // Measure the active tab and drive the sliding indicator. useLayoutEffect so
+  // the first position is set before paint (the indicator element mounts already
+  // in place — no slide-in from zero; only later tab changes animate). Observes
+  // the active tab (its own size, e.g. a changing "(3)" count) and the list
+  // (container resize / reflow). A non-active sibling resizing while you're on
+  // another tab is the one case not caught; it self-corrects on the next
+  // selection or resize.
+  useLayoutEffect(() => {
+    const list = listRef.current
+    if (!list || !activeValue) {
+      setIndicator(null)
+      setIndicatorActive(false)
+      return
+    }
+    const el = list.querySelector<HTMLElement>(`[data-tab-value="${CSS.escape(activeValue)}"]`)
+    if (!el) {
+      setIndicator(null)
+      setIndicatorActive(false)
+      return
+    }
+    const measure = () => {
+      setIndicator(
+        orientation === 'horizontal'
+          ? {offset: el.offsetLeft, size: el.offsetWidth}
+          : {offset: el.offsetTop, size: el.offsetHeight},
+      )
+      setIndicatorActive(true)
+    }
+    measure()
+    const ro = new ResizeObserver(measure)
+    ro.observe(el)
+    ro.observe(list)
+    return () => ro.disconnect()
+  }, [listRef, activeValue, orientation, setIndicatorActive])
+
+  return {indicator, reportTabLayout: null}
+}

package/src/components/Tabs/useTabKeys.native.ts

@@ -0,0 +1,2 @@
+/** Native has no arrow-key navigation (plan N0, Decision 6): each tab is its own stop. */
+export function useTabKeys(_input: unknown) {}