@duro-app/ui 5.12.0 → 5.13.0

package/src/components/Tree/Tree.tsx

@@ -1,17 +1,10 @@
-import {
-  Children,
-  type ReactNode,
-  useCallback,
-  useContext,
-  useEffect,
-  useId,
-  useLayoutEffect,
-  useRef,
-  useState,
-} from 'react'
+import {Children, type ReactNode, useCallback, useContext, useId, useRef, useState} from 'react'
 import {html} from 'react-strict-dom'
+import {SPACING_PX} from '@duro-app/tokens/keys'
 import {styles} from './styles.css'
+import {isNative} from '../../platform'
 import {TreeContext, TreeLevelContext, useTree} from './TreeContext'
+import {useTreeKeyboard} from './useTreeKeyboard'
 import {isPlainClick, type LinkClickEvent, type OnNavigate} from '../../shared/navigate'
 
 /* Tree — a hierarchy of items (the WAI-ARIA tree pattern): single selection,
@@ -43,8 +36,6 @@ interface RootProps {
   onExpandedChange?: (expanded: string[]) => void
 }
 
-const TYPEAHEAD_RESET_MS = 500
-
 function Root({
   children,
   'aria-label': ariaLabel,
@@ -86,126 +77,16 @@ function Root({
   const isExpanded = useCallback((v: string) => open.includes(v), [open])
   const toggle = useCallback((v: string) => setExpanded(v, !open.includes(v)), [open, setExpanded])
 
-  // Exactly one item is tabbable: the focus holder, else the selection, else
-  // the first item — re-checked when an item appears, closes or goes away.
-  useLayoutEffect(() => {
-    const root = rootRef.current
-    if (!root) return
-    const tabbable = root.querySelector('[role="treeitem"][tabindex="0"]')
-    if (tabbable) return
-    const first = root.querySelector<HTMLElement>('[role="treeitem"]')
-    const next = first?.dataset.treeValue ?? null
-    if (next !== focusValue) setFocusValue(next)
-  }, [focusValue, open, children])
-
-  // Keyboard: DOM order over the rendered items IS the visible order (a
-  // closed branch renders no children), so navigation reads it directly.
-  const typeahead = useRef({text: '', at: 0})
-  useEffect(() => {
-    const root = rootRef.current
-    if (!root) return
-    const rootEl = root
-    const items = () => Array.from(rootEl.querySelectorAll<HTMLElement>('[role="treeitem"]'))
-    const focusItem = (el: HTMLElement | null | undefined) => {
-      if (!el) return
-      el.focus()
-    }
-    function onKeyDown(e: KeyboardEvent) {
-      const current = (e.target as HTMLElement).closest<HTMLElement>('[role="treeitem"]')
-      if (!current || !rootEl.contains(current)) return
-      const list = items()
-      const i = list.indexOf(current)
-      const val = current.dataset.treeValue ?? ''
-      const isOpen = current.getAttribute('aria-expanded')
-      switch (e.key) {
-        case 'ArrowDown':
-          e.preventDefault()
-          focusItem(list[i + 1])
-          return
-        case 'ArrowUp':
-          e.preventDefault()
-          focusItem(list[i - 1])
-          return
-        case 'ArrowRight':
-          e.preventDefault()
-          if (isOpen === 'false') setExpanded(val, true)
-          else if (isOpen === 'true') focusItem(list[i + 1])
-          return
-        case 'ArrowLeft': {
-          e.preventDefault()
-          if (isOpen === 'true') {
-            setExpanded(val, false)
-            return
-          }
-          const parent = current.parentElement?.closest<HTMLElement>('[role="treeitem"]')
-          if (parent && rootEl.contains(parent)) focusItem(parent)
-          return
-        }
-        case 'Home':
-          e.preventDefault()
-          focusItem(list[0])
-          return
-        case 'End':
-          e.preventDefault()
-          focusItem(list[list.length - 1])
-          return
-        case 'Enter':
-        case ' ': {
-          e.preventDefault()
-          // an item with href: follow its link (the click selects it and
-          // runs onNavigate, or the browser navigates)
-          const link = current.querySelector<HTMLElement>(':scope > [data-tree-link]')
-          if (link) link.click()
-          else onSelect(val)
-          return
-        }
-      }
-      // typeahead: a printable character, no modifier
-      if (e.key.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey) {
-        const now = Date.now()
-        const t = typeahead.current
-        t.text = now - t.at > TYPEAHEAD_RESET_MS ? e.key : t.text + e.key
-        t.at = now
-        // the same letter typed again cycles through the items it starts;
-        // a real prefix ("fi") narrows, and may match the current item
-        const typed = t.text.toLocaleLowerCase()
-        const repeat = [...typed].every((c) => c === typed[0])
-        const needle = repeat ? typed[0] : typed
-        const start = repeat ? i + 1 : i
-        for (let k = 0; k < list.length; k++) {
-          const el = list[(start + k) % list.length]
-          if ((el.dataset.treeText ?? '').toLocaleLowerCase().startsWith(needle)) {
-            focusItem(el)
-            break
-          }
-        }
-      }
-    }
-    // the roving tab stop follows focus, however it moved (keys or pointer)
-    function onFocusIn(e: FocusEvent) {
-      const item = (e.target as HTMLElement).closest<HTMLElement>('[role="treeitem"]')
-      const v = item?.dataset.treeValue
-      if (v) setFocusValue(v)
-      setKeyboardFocus(item?.matches(':focus-visible') ?? false)
-    }
-    function onFocusOut(e: FocusEvent) {
-      if (!rootEl.contains(e.relatedTarget as Node | null)) setKeyboardFocus(false)
-    }
-    const onPointerDown = () => setKeyboardFocus(false)
-    const onKey = () => setKeyboardFocus(true)
-    root.addEventListener('keydown', onKeyDown)
-    root.addEventListener('keydown', onKey)
-    root.addEventListener('focusin', onFocusIn)
-    root.addEventListener('focusout', onFocusOut)
-    root.addEventListener('pointerdown', onPointerDown)
-    return () => {
-      root.removeEventListener('keydown', onKeyDown)
-      root.removeEventListener('keydown', onKey)
-      root.removeEventListener('focusin', onFocusIn)
-      root.removeEventListener('focusout', onFocusOut)
-      root.removeEventListener('pointerdown', onPointerDown)
-    }
-  }, [onSelect, setExpanded])
+  useTreeKeyboard({
+    rootRef,
+    focusValue,
+    setFocusValue,
+    setKeyboardFocus,
+    open,
+    children,
+    onSelect,
+    setExpanded,
+  })
 
   return (
     <TreeContext.Provider
@@ -272,7 +153,9 @@ function Item({value, label, textValue, children, meta, href, onNavigate}: ItemP
   // and a name computed from content would read the whole subtree
   const labelId = useId()
   const rowStyles = [
-    styles.indent(level),
+    isNative
+      ? styles.indentPx(SPACING_PX.sm + Math.max(0, level - 1) * SPACING_PX.lg)
+      : styles.indent(level),
     selected && styles.rowSelected,
     keyboardFocus && focusValue === value && styles.rowFocused,
   ]
@@ -287,7 +170,12 @@ function Item({value, label, textValue, children, meta, href, onNavigate}: ItemP
           e.preventDefault()
           toggle(value)
         }}
-        style={[styles.chevron, open && styles.chevronOpen, !hasChildren && styles.chevronLeaf]}
+        style={[
+          styles.chevron,
+          isNative && styles.nativeFlex,
+          open && styles.chevronOpen,
+          !hasChildren && styles.chevronLeaf,
+        ]}
       >
         ▸
       </html.span>

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

@@ -56,6 +56,8 @@ export const styles = css.create({
     outlineWidth: 0,
     outlineStyle: 'none',
   },
+  // Native has no calc(): the same steps, in px from the spacing scale.
+  indentPx: (px: number) => ({paddingLeft: px}),
   // one indent step per level below the top
   indent: (level: number) => ({
     paddingLeft: `calc(${spacing.sm} + ${Math.max(0, level - 1)} * ${spacing.lg})`,
@@ -71,6 +73,10 @@ export const styles = css.create({
     fontWeight: typography.fontWeightMedium,
     backgroundColor: colors.bgCardHover,
   },
+  // RSD on native lays out only display: flex, not the web's inline-flex.
+  nativeFlex: {
+    display: 'flex',
+  },
   chevron: {
     display: 'inline-flex',
     alignItems: 'center',

package/src/components/Tree/useTreeKeyboard.native.ts

@@ -0,0 +1,5 @@
+/**
+ * Native has no hardware-keyboard tree navigation (plan N0, Decision 6):
+ * each item is a screen-reader stop with its role, level and expanded state.
+ */
+export function useTreeKeyboard(_input: unknown) {}

package/src/components/Tree/useTreeKeyboard.ts

@@ -0,0 +1,152 @@
+import {type ReactNode, useEffect, useLayoutEffect, useRef} from 'react'
+
+/** Typed characters within this many ms build one typeahead prefix. */
+const TYPEAHEAD_RESET_MS = 500
+
+interface TreeKeyboardInput {
+  rootRef: React.RefObject<HTMLUListElement | null>
+  focusValue: string | null
+  setFocusValue: (value: string | null) => void
+  setKeyboardFocus: (on: boolean) => void
+  open: ReadonlyArray<string>
+  children: ReactNode
+  onSelect: (value: string) => void
+  setExpanded: (value: string, open: boolean) => void
+}
+
+/**
+ * Web: the tree's roving tab stop, arrow keys, Home/End, Enter and typeahead
+ * (WAI-ARIA tree pattern), read from the rendered DOM. Native has none of
+ * them (plan N0, Decision 6): useTreeKeyboard.native.ts.
+ */
+export function useTreeKeyboard({
+  rootRef,
+  focusValue,
+  setFocusValue,
+  setKeyboardFocus,
+  open,
+  children,
+  onSelect,
+  setExpanded,
+}: TreeKeyboardInput) {
+  // Exactly one item is tabbable: the focus holder, else the selection, else
+  // the first item — re-checked when an item appears, closes or goes away.
+  useLayoutEffect(() => {
+    const root = rootRef.current
+    if (!root) return
+    const tabbable = root.querySelector('[role="treeitem"][tabindex="0"]')
+    if (tabbable) return
+    const first = root.querySelector<HTMLElement>('[role="treeitem"]')
+    const next = first?.dataset.treeValue ?? null
+    if (next !== focusValue) setFocusValue(next)
+  }, [rootRef, focusValue, setFocusValue, open, children])
+
+  // Keyboard: DOM order over the rendered items IS the visible order (a
+  // closed branch renders no children), so navigation reads it directly.
+  const typeahead = useRef({text: '', at: 0})
+  useEffect(() => {
+    const root = rootRef.current
+    if (!root) return
+    const rootEl = root
+    const items = () => Array.from(rootEl.querySelectorAll<HTMLElement>('[role="treeitem"]'))
+    const focusItem = (el: HTMLElement | null | undefined) => {
+      if (!el) return
+      el.focus()
+    }
+    function onKeyDown(e: KeyboardEvent) {
+      const current = (e.target as HTMLElement).closest<HTMLElement>('[role="treeitem"]')
+      if (!current || !rootEl.contains(current)) return
+      const list = items()
+      const i = list.indexOf(current)
+      const val = current.dataset.treeValue ?? ''
+      const isOpen = current.getAttribute('aria-expanded')
+      switch (e.key) {
+        case 'ArrowDown':
+          e.preventDefault()
+          focusItem(list[i + 1])
+          return
+        case 'ArrowUp':
+          e.preventDefault()
+          focusItem(list[i - 1])
+          return
+        case 'ArrowRight':
+          e.preventDefault()
+          if (isOpen === 'false') setExpanded(val, true)
+          else if (isOpen === 'true') focusItem(list[i + 1])
+          return
+        case 'ArrowLeft': {
+          e.preventDefault()
+          if (isOpen === 'true') {
+            setExpanded(val, false)
+            return
+          }
+          const parent = current.parentElement?.closest<HTMLElement>('[role="treeitem"]')
+          if (parent && rootEl.contains(parent)) focusItem(parent)
+          return
+        }
+        case 'Home':
+          e.preventDefault()
+          focusItem(list[0])
+          return
+        case 'End':
+          e.preventDefault()
+          focusItem(list[list.length - 1])
+          return
+        case 'Enter':
+        case ' ': {
+          e.preventDefault()
+          // an item with href: follow its link (the click selects it and
+          // runs onNavigate, or the browser navigates)
+          const link = current.querySelector<HTMLElement>(':scope > [data-tree-link]')
+          if (link) link.click()
+          else onSelect(val)
+          return
+        }
+      }
+      // typeahead: a printable character, no modifier
+      if (e.key.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey) {
+        const now = Date.now()
+        const t = typeahead.current
+        t.text = now - t.at > TYPEAHEAD_RESET_MS ? e.key : t.text + e.key
+        t.at = now
+        // the same letter typed again cycles through the items it starts;
+        // a real prefix ("fi") narrows, and may match the current item
+        const typed = t.text.toLocaleLowerCase()
+        const repeat = [...typed].every((c) => c === typed[0])
+        const needle = repeat ? typed[0] : typed
+        const start = repeat ? i + 1 : i
+        for (let k = 0; k < list.length; k++) {
+          const el = list[(start + k) % list.length]
+          if ((el.dataset.treeText ?? '').toLocaleLowerCase().startsWith(needle)) {
+            focusItem(el)
+            break
+          }
+        }
+      }
+    }
+    // the roving tab stop follows focus, however it moved (keys or pointer)
+    function onFocusIn(e: FocusEvent) {
+      const item = (e.target as HTMLElement).closest<HTMLElement>('[role="treeitem"]')
+      const v = item?.dataset.treeValue
+      if (v) setFocusValue(v)
+      setKeyboardFocus(item?.matches(':focus-visible') ?? false)
+    }
+    function onFocusOut(e: FocusEvent) {
+      if (!rootEl.contains(e.relatedTarget as Node | null)) setKeyboardFocus(false)
+    }
+    const onPointerDown = () => setKeyboardFocus(false)
+    const onKey = () => setKeyboardFocus(true)
+    root.addEventListener('keydown', onKeyDown)
+    root.addEventListener('keydown', onKey)
+    root.addEventListener('focusin', onFocusIn)
+    root.addEventListener('focusout', onFocusOut)
+    root.addEventListener('pointerdown', onPointerDown)
+    return () => {
+      root.removeEventListener('keydown', onKeyDown)
+      root.removeEventListener('keydown', onKey)
+      root.removeEventListener('focusin', onFocusIn)
+      root.removeEventListener('focusout', onFocusOut)
+      root.removeEventListener('pointerdown', onPointerDown)
+    }
+  }, [rootRef, onSelect, setExpanded, setFocusValue, setKeyboardFocus])
+}

package/src/components/VirtualList/VirtualList.meta.ts

@@ -0,0 +1,39 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'A windowed list on @tanstack/react-virtual: only the rows in view (plus overscan) are mounted, and rows are measured so they may differ in height. role="list" with listitem rows carrying aria-setsize and aria-posinset. anchor="end" opens at the last item and stays pinned to the bottom while new items arrive and the reader is at the bottom (a transcript, a log). It fills its parent, or stops at maxHeight. Web only: on native, host FlashList or Legend List behind your own .native.tsx leaf.',
+  whenToUse: [
+    'Hundreds to tens of thousands of rows: sessions, a chat transcript, log lines',
+    'A list that grows at the bottom while the reader follows it (anchor="end")',
+  ],
+  whenNotToUse: [
+    'Tabular data with columns and sorting — use VirtualTable',
+    'A few dozen rows — use List; windowing only adds cost there',
+    'Selectable options in a picker — use Listbox',
+  ],
+  anatomy: {
+    required: [],
+    optional: [],
+  },
+  relatedTo: [
+    {
+      component: 'VirtualTable',
+      kind: 'contrast',
+      relationship: 'VirtualTable windows table rows with columns; VirtualList windows any row',
+    },
+    {
+      component: 'List',
+      kind: 'composition',
+      relationship: 'Render a List.Item-like row in renderItem for the list look',
+    },
+  ],
+  example: `<VirtualList
+  aria-label="Transcript"
+  items={messages}
+  getKey={(m) => m.id}
+  estimateSize="controlLg"
+  anchor="end"
+  renderItem={(m) => <Text>{m.text}</Text>}
+/>`,
+}

package/src/components/VirtualList/VirtualList.stories.tsx

@@ -0,0 +1,95 @@
+import type {Meta, StoryObj} from '@storybook/react'
+import {expect, waitFor} from 'storybook/test'
+import type {SizeToken} from '@duro-app/tokens/keys'
+import {VirtualList} from './VirtualList'
+import {Text} from '../Text/Text'
+
+const meta: Meta = {
+  title: 'Components/VirtualList',
+}
+
+export default meta
+type Story = StoryObj
+
+const ITEMS = Array.from({length: 10_000}, (_, i) => ({id: i, text: `Message ${i + 1}`}))
+
+function Rows({anchor}: {anchor?: 'start' | 'end'}) {
+  return (
+    <VirtualList
+      aria-label="Transcript"
+      items={ITEMS}
+      getKey={(m) => m.id}
+      estimateSize="controlLg"
+      anchor={anchor}
+      maxHeight="previewMaxH"
+      renderItem={(m) => <Text>{m.text}</Text>}
+    />
+  )
+}
+
+interface PlaygroundArgs {
+  count: number
+  anchor: 'start' | 'end'
+  overscan: number
+  estimateSize: SizeToken
+}
+
+export const Playground: StoryObj<PlaygroundArgs> = {
+  args: {count: 10_000, anchor: 'start', overscan: 5, estimateSize: 'controlLg'},
+  argTypes: {
+    count: {
+      control: {type: 'number', min: 0, max: 10_000, step: 500},
+      description: 'How many items',
+    },
+    anchor: {
+      control: 'inline-radio',
+      options: ['start', 'end'],
+      description: "'end' opens at the last item and follows new ones",
+    },
+    overscan: {
+      control: {type: 'number', min: 0, max: 50},
+      description: 'Rows rendered past each edge',
+    },
+    estimateSize: {
+      control: 'select',
+      options: ['controlSm', 'controlLg', 'touchTarget', 'iconXl'],
+      description: "Each row's starting height estimate (a size token)",
+    },
+  },
+  render: ({count, anchor, overscan, estimateSize}) => (
+    <VirtualList
+      aria-label="Transcript"
+      items={ITEMS.slice(0, count)}
+      getKey={(m) => m.id}
+      estimateSize={estimateSize}
+      anchor={anchor}
+      overscan={overscan}
+      maxHeight="previewMaxH"
+      renderItem={(m) => <Text>{m.text}</Text>}
+    />
+  ),
+}
+
+export const TenThousand: Story = {
+  render: () => <Rows />,
+  play: async ({canvas}) => {
+    const list = canvas.getByRole('list', {name: 'Transcript'})
+    await waitFor(() => expect(canvas.getAllByRole('listitem').length).toBeGreaterThan(0))
+    const rows = canvas.getAllByRole('listitem')
+    await expect(rows.length).toBeLessThan(50)
+    await expect(rows[0]).toHaveAttribute('aria-setsize', '10000')
+    await expect(rows[0]).toHaveAttribute('aria-posinset', '1')
+    await expect(list.scrollHeight).toBeGreaterThan(list.clientHeight * 100)
+  },
+}
+
+export const AnchoredToTheEnd: Story = {
+  render: () => <Rows anchor="end" />,
+  play: async ({canvas}) => {
+    await waitFor(() => expect(canvas.getByText('Message 10000')).toBeInTheDocument())
+    const rows = canvas.getAllByRole('listitem')
+    await expect(rows.length).toBeLessThan(50)
+    const last = rows.find((r) => r.getAttribute('aria-posinset') === '10000')
+    await expect(last).toBeDefined()
+  },
+}

package/src/components/VirtualList/VirtualList.tsx

@@ -0,0 +1,103 @@
+import {type ReactNode, useEffect, useLayoutEffect, useRef} from 'react'
+import {html} from 'react-strict-dom'
+import {useVirtualizer} from '@tanstack/react-virtual'
+import {SIZES_PX, type SizeToken} from '@duro-app/tokens/keys'
+import {resolveLength, type Length} from '../../shared/length'
+import {styles} from './styles.css'
+
+export interface VirtualListProps<T> {
+  items: readonly T[]
+  /** Each row's starting height estimate, a size token; rows are then measured. */
+  estimateSize: SizeToken
+  renderItem: (item: T, index: number) => ReactNode
+  /** A stable key per item (an id), so rows keep their measurement as items change. */
+  getKey: (item: T, index: number) => string | number
+  /** Rows rendered beyond each edge of the view. Default 5 */
+  overscan?: number
+  /**
+   * `end` starts at the last item and stays pinned to the bottom while new
+   * items arrive, as long as the reader is at the bottom (a transcript, a log).
+   * Default `start`.
+   */
+  anchor?: 'start' | 'end'
+  /** Cap the list's height; without it, it fills its parent. */
+  maxHeight?: Length
+  /** The list's accessible name. */
+  'aria-label': string
+}
+
+/** Within this many px of the end counts as "at the bottom" for `anchor="end"`. */
+const BOTTOM_SLOP = SIZES_PX.touchTarget
+
+/**
+ * A windowed list: only the rows in view (plus `overscan`) are mounted, so a
+ * list of tens of thousands stays fast. Rows are measured as they render, so
+ * they may differ in height. It is a `role="list"`; each row is a listitem
+ * with `aria-setsize` and `aria-posinset`, so assistive tech knows the full
+ * length while most rows are not in the DOM. Web only: on native, host
+ * FlashList or Legend List behind your own `.native.tsx` leaf.
+ */
+export function VirtualList<T>({
+  items,
+  estimateSize,
+  renderItem,
+  getKey,
+  overscan = 5,
+  anchor = 'start',
+  maxHeight,
+  'aria-label': ariaLabel,
+}: VirtualListProps<T>) {
+  const scrollRef = useRef<HTMLDivElement>(null)
+  const virtualizer = useVirtualizer({
+    count: items.length,
+    getScrollElement: () => scrollRef.current,
+    estimateSize: () => SIZES_PX[estimateSize],
+    getItemKey: (index) => getKey(items[index], index),
+    overscan,
+  })
+
+  // `end`: open at the last item, and follow new items while at the bottom.
+  const atBottom = useRef(true)
+  useEffect(() => {
+    const el = scrollRef.current
+    if (!el || anchor !== 'end') return
+    const onScroll = () => {
+      atBottom.current = el.scrollHeight - el.scrollTop - el.clientHeight <= BOTTOM_SLOP
+    }
+    el.addEventListener('scroll', onScroll, {passive: true})
+    return () => el.removeEventListener('scroll', onScroll)
+  }, [anchor])
+  useLayoutEffect(() => {
+    if (anchor !== 'end' || items.length === 0 || !atBottom.current) return
+    virtualizer.scrollToIndex(items.length - 1, {align: 'end'})
+  }, [anchor, items.length, virtualizer])
+
+  const rows = virtualizer.getVirtualItems()
+  return (
+    <html.div
+      ref={scrollRef}
+      role="list"
+      aria-label={ariaLabel}
+      style={[
+        styles.scroller,
+        maxHeight !== undefined && styles.scrollMax(resolveLength(maxHeight)),
+      ]}
+    >
+      <html.div style={styles.total(virtualizer.getTotalSize())}>
+        {rows.map((row) => (
+          <html.div
+            key={row.key}
+            ref={virtualizer.measureElement}
+            data-index={row.index}
+            role="listitem"
+            aria-setsize={items.length}
+            aria-posinset={row.index + 1}
+            style={styles.row(row.start)}
+          >
+            {renderItem(items[row.index], row.index)}
+          </html.div>
+        ))}
+      </html.div>
+    </html.div>
+  )
+}

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

@@ -0,0 +1,31 @@
+import {css} from 'react-strict-dom'
+
+export const styles = css.create({
+  // The scroll container: it fills its parent (a pane, a flex column) by
+  // default, or stops at `maxHeight`.
+  scroller: {
+    position: 'relative',
+    width: '100%',
+    height: '100%',
+    minHeight: 0,
+    overflowY: 'auto',
+    overscrollBehavior: 'contain',
+  },
+  scrollMax: (maxHeight: number | string) => ({
+    height: 'auto',
+    maxHeight,
+  }),
+  // The full virtual height, so the scrollbar is the list's real length.
+  total: (height: number) => ({
+    position: 'relative',
+    width: '100%',
+    height,
+  }),
+  row: (y: number) => ({
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    width: '100%',
+    transform: `translateY(${y}px)`,
+  }),
+})

package/src/hooks/useContainerBelow.native.ts

@@ -0,0 +1,30 @@
+import {useEffect, useState, type RefObject} from 'react'
+import {useWindowDimensions} from 'react-native'
+import {breakpointsPx, type Breakpoint} from '@duro-app/tokens/tokens/breakpoints.css'
+
+interface Measurable {
+  measure?: (cb: (x: number, y: number, width: number) => void) => void
+}
+
+/**
+ * Native: whether the view behind `ref` is narrower than a Duro breakpoint.
+ * There is no ResizeObserver; the view is measured after layout and again
+ * whenever the window changes size (a rotation, a split screen). `false`
+ * until the first measurement, as on the web.
+ */
+export function useContainerBelow(ref: RefObject<unknown>, breakpoint: Breakpoint): boolean {
+  const [below, setBelow] = useState(false)
+  const limit = breakpointsPx[breakpoint]
+  const {width: windowWidth} = useWindowDimensions()
+
+  useEffect(() => {
+    const frame = requestAnimationFrame(() => {
+      ;(ref.current as Measurable | null)?.measure?.((_x, _y, width) => {
+        if (width > 0) setBelow(width < limit)
+      })
+    })
+    return () => cancelAnimationFrame(frame)
+  }, [ref, limit, windowWidth])
+
+  return below
+}