@duro-app/ui 5.12.0 → 5.13.0

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

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>
   )
 }