@duro-app/ui 5.17.0 → 5.19.0

package/src/components/Tree/TreeContext.ts

@@ -1,4 +1,5 @@
 import {createContext, useContext} from 'react'
+import type {TreeFocusStore} from './TreeFocusStore'
 
 export interface TreeContextValue {
   /** the selected item's value (single selection), or null */
@@ -7,11 +8,10 @@ export interface TreeContextValue {
   isExpanded: (value: string) => boolean
   toggle: (value: string) => void
   setExpanded: (value: string, expanded: boolean) => void
-  /** the item holding the tree's single tab stop (roving tabindex) */
-  focusValue: string | null
-  setFocusValue: (value: string) => void
-  /** the focus holder is focused from the keyboard (draws its ring) */
-  keyboardFocus: boolean
+  /** the tab stop and the focus ring: rows subscribe, the tree does not re-render */
+  focus: TreeFocusStore
+  /** native: names a branch's chevron control from the item's text */
+  expandLabel?: (label: string) => string
 }
 
 export const TreeContext = createContext<TreeContextValue | null>(null)

package/src/components/Tree/TreeFocusStore.ts

@@ -0,0 +1,73 @@
+import {useSyncExternalStore} from 'react'
+
+/** What a row reads of the tree's focus: nothing, the tab stop, or the tab stop with the ring. */
+export type RowFocus = 'none' | 'tabStop' | 'ringed'
+
+/**
+ * The tree's focus, outside React state: the item holding the roving tab stop,
+ * whether its ring shows (keyboard focus), and a focus request an off-screen
+ * row waits on. A row reads only "am I the tab stop / ringed" through
+ * `useTreeRowFocus`, so a focus move re-renders the row that lost it and the
+ * row that gained it, not the tree.
+ */
+export interface TreeFocusStore {
+  getValue: () => string | null
+  getPending: () => string | null
+  /** moves the tab stop */
+  setValue: (value: string | null) => void
+  setRing: (ring: boolean) => void
+  /** moves the tab stop and asks the window to focus the row once it mounts */
+  request: (value: string) => void
+  clearPending: () => void
+  subscribe: (listener: () => void) => () => void
+  read: (value: string) => RowFocus
+}
+
+export function createTreeFocusStore(initial: string | null): TreeFocusStore {
+  let value = initial
+  let ring = false
+  let pending: string | null = null
+  const listeners = new Set<() => void>()
+  const emit = () => {
+    for (const listener of listeners) listener()
+  }
+  return {
+    getValue: () => value,
+    getPending: () => pending,
+    setValue: (next) => {
+      if (next === value) return
+      value = next
+      emit()
+    },
+    setRing: (next) => {
+      if (next === ring) return
+      ring = next
+      emit()
+    },
+    request: (next) => {
+      value = next
+      pending = next
+      emit()
+    },
+    clearPending: () => {
+      if (pending === null) return
+      pending = null
+      emit()
+    },
+    subscribe: (listener) => {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+    read: (own) => (own !== value ? 'none' : ring ? 'ringed' : 'tabStop'),
+  }
+}
+
+export function useTreeRowFocus(store: TreeFocusStore, value: string): RowFocus {
+  return useSyncExternalStore(store.subscribe, () => store.read(value))
+}
+
+export function useTreePendingFocus(store: TreeFocusStore): string | null {
+  return useSyncExternalStore(store.subscribe, store.getPending)
+}

package/src/components/Tree/TreeItemRow.tsx

@@ -0,0 +1,71 @@
+import {type ReactNode, useId} from 'react'
+import {TreeRow} from './TreeRow'
+import {useTree} from './TreeContext'
+import {useTreeRowFocus} from './TreeFocusStore'
+import type {WindowedRow} from './TreeRowProps'
+import type {OnNavigate} from '../../shared/navigate'
+
+interface TreeItemRowProps {
+  value: string
+  level: number
+  label: ReactNode
+  meta?: ReactNode
+  text: string
+  href?: string
+  onNavigate?: OnNavigate
+  hasChildren: boolean
+  open: boolean
+  /** the open branch's children (nested tree), none in a windowed one */
+  branch: ReactNode
+  windowed?: WindowedRow
+}
+
+/**
+ * One row of the tree with its state: the selection from the tree, and the
+ * tab stop and ring from the focus store, which this row alone subscribes to.
+ * Shared by the nested `Tree.Item` and the windowed rows.
+ */
+export function TreeItemRow({
+  value,
+  level,
+  label,
+  meta,
+  text,
+  href,
+  onNavigate,
+  hasChildren,
+  open,
+  branch,
+  windowed,
+}: TreeItemRowProps) {
+  const {selectedValue, onSelect, toggle, focus, expandLabel} = useTree()
+  const rowFocus = useTreeRowFocus(focus, value)
+  // named by its own label (and meta) only: a branch's content includes its
+  // children, and a name computed from content would read the whole subtree
+  const labelId = useId()
+  const metaId = useId()
+
+  return (
+    <TreeRow
+      value={value}
+      level={level}
+      label={label}
+      meta={meta}
+      text={text}
+      href={href}
+      onNavigate={onNavigate}
+      hasChildren={hasChildren}
+      open={open}
+      selected={selectedValue === value}
+      tabStop={rowFocus !== 'none'}
+      ringed={rowFocus === 'ringed'}
+      labelId={labelId}
+      metaId={metaId}
+      onSelect={() => onSelect(value)}
+      onToggle={() => toggle(value)}
+      expandLabel={expandLabel}
+      branch={branch}
+      windowed={windowed}
+    />
+  )
+}

package/src/components/Tree/TreeRow.native.tsx

@@ -0,0 +1,96 @@
+import {html} from 'react-strict-dom'
+import {SPACING_PX} from '@duro-app/tokens/keys'
+import {styles} from './styles.css'
+import type {TreeRowProps} from './TreeRowProps'
+import {devWarnOnce} from '../../shared/devWarnOnce'
+// Explicit suffix: a native-only module has no web file for moduleSuffixes to pair.
+import {followLink} from '../../shared/followLink.native'
+
+/* The native row of a Tree.Item, for both variants (with and without href).
+ *
+ * The row is a plain View holding two SIBLINGS: a branch's chevron control and
+ * the press target. react-strict-dom turns an `html.div` with `onClick` into an
+ * accessible Pressable that hides its descendants from VoiceOver, so the
+ * chevron can never sit inside the press target. The native `li` and group
+ * `ul` take role="none" (RSD defaults them to listitem/list), so nothing is
+ * announced twice. Label and meta are each a View container: no View inside a
+ * Text. Hook-free: Tree.Item owns the state. */
+export function TreeRow({
+  level,
+  label,
+  meta,
+  text,
+  href,
+  onNavigate,
+  hasChildren,
+  open,
+  selected,
+  onSelect,
+  onToggle,
+  expandLabel,
+  branch,
+}: TreeRowProps) {
+  if (href !== undefined && onNavigate === undefined) {
+    devWarnOnce(
+      'Tree',
+      'href-without-onNavigate',
+      'Tree.Item has an href but no onNavigate: on native a relative href goes to the system (Linking.openURL) and leaves the app. Pass onNavigate to route in-app.',
+    )
+  }
+  const chevronLabel = expandLabel ? expandLabel(text) : text
+  if (hasChildren && chevronLabel === '') {
+    devWarnOnce(
+      'Tree',
+      'empty-expand-label',
+      'A Tree.Item branch has no text for its expand control: give it a string label or textValue, or Tree.Root an expandLabel.',
+    )
+  }
+
+  const press = () => {
+    onSelect()
+    if (href !== undefined) followLink(href, onNavigate, 'Tree.Item')
+    // a branch with no link toggles on its row (a folder), as on the web
+    else if (hasChildren) onToggle()
+  }
+
+  return (
+    <html.li role="none" style={styles.item}>
+      <html.div
+        style={[
+          styles.nativeRow,
+          styles.indentPx(SPACING_PX.sm + Math.max(0, level - 1) * SPACING_PX.lg),
+          selected && styles.rowSelected,
+        ]}
+      >
+        {hasChildren ? (
+          <html.div
+            role="button"
+            aria-expanded={open}
+            aria-label={chevronLabel}
+            onClick={onToggle}
+            style={styles.chevronControl}
+          >
+            <html.span style={[styles.chevronGlyph, open && styles.chevronOpen]}>▸</html.span>
+          </html.div>
+        ) : null}
+        <html.div
+          role={href !== undefined ? 'link' : 'button'}
+          aria-selected={selected}
+          onClick={press}
+          style={styles.pressTarget}
+        >
+          {hasChildren ? null : <html.div style={styles.chevronSpacer} />}
+          <html.div style={styles.labelBox}>
+            <html.span>{label}</html.span>
+          </html.div>
+          {meta != null ? <html.div style={styles.metaBox}>{meta}</html.div> : null}
+        </html.div>
+      </html.div>
+      {open ? (
+        <html.ul role="none" style={styles.group}>
+          {branch}
+        </html.ul>
+      ) : null}
+    </html.li>
+  )
+}

package/src/components/Tree/TreeRow.tsx

@@ -0,0 +1,112 @@
+import {html} from 'react-strict-dom'
+import {styles} from './styles.css'
+import type {TreeRowProps} from './TreeRowProps'
+import {isPlainClick, type LinkClickEvent} from '../../shared/navigate'
+
+/* The web row of a Tree.Item: the treeitem `li` with its aria, the row as a
+ * real link (href) or a div, the chevron, the label and the meta. Hook-free:
+ * Tree.Item owns the state. TreeRow.native.tsx is the native counterpart. */
+export function TreeRow({
+  value,
+  level,
+  label,
+  meta,
+  text,
+  href,
+  onNavigate,
+  hasChildren,
+  open,
+  selected,
+  tabStop,
+  ringed,
+  labelId,
+  metaId,
+  onSelect,
+  onToggle,
+  branch,
+  windowed,
+}: TreeRowProps) {
+  const rowStyles = [
+    styles.indent(level),
+    selected && styles.rowSelected,
+    ringed && styles.rowFocused,
+  ]
+  const rowContent = (
+    <>
+      <html.span
+        aria-hidden
+        onClick={
+          hasChildren
+            ? (e: {stopPropagation: () => void; preventDefault: () => void}) => {
+                // the chevron only toggles: it never selects, nor follows a link
+                e.stopPropagation()
+                e.preventDefault()
+                onToggle()
+              }
+            : undefined
+        }
+        style={[styles.chevron, open && styles.chevronOpen, !hasChildren && styles.chevronLeaf]}
+      >
+        ▸
+      </html.span>
+      <html.span id={labelId} style={styles.label}>
+        {label}
+      </html.span>
+      {meta != null ? (
+        <html.span id={metaId} style={styles.meta}>
+          {meta}
+        </html.span>
+      ) : null}
+    </>
+  )
+
+  return (
+    <html.li
+      role="treeitem"
+      aria-labelledby={meta != null ? `${labelId} ${metaId}` : labelId}
+      aria-level={level}
+      aria-expanded={hasChildren ? open : undefined}
+      aria-selected={selected}
+      aria-setsize={windowed?.setSize}
+      aria-posinset={windowed?.posInSet}
+      data-index={windowed?.index}
+      ref={windowed?.measureRef}
+      tabIndex={tabStop ? 0 : -1}
+      data-tree-value={value}
+      data-tree-text={text}
+      style={[styles.item, windowed && styles.windowRow(windowed.top)]}
+    >
+      {href !== undefined ? (
+        <html.a
+          href={href}
+          tabIndex={-1}
+          data-tree-link=""
+          onClick={(e: LinkClickEvent) => {
+            if (!isPlainClick(e)) return
+            onSelect()
+            onNavigate?.(href, e)
+          }}
+          style={[styles.row, styles.rowLink, ...rowStyles]}
+        >
+          {rowContent}
+        </html.a>
+      ) : (
+        <html.div
+          onClick={() => {
+            onSelect()
+            // a branch with no link toggles on its row (a folder); with a link the row navigates
+            if (hasChildren) onToggle()
+          }}
+          style={[styles.row, ...rowStyles]}
+        >
+          {rowContent}
+        </html.div>
+      )}
+      {open && !windowed ? (
+        <html.ul role="group" style={styles.group}>
+          {branch}
+        </html.ul>
+      ) : null}
+    </html.li>
+  )
+}

package/src/components/Tree/TreeRowProps.ts

@@ -0,0 +1,42 @@
+import type {ReactNode} from 'react'
+import type {OnNavigate} from '../../shared/navigate'
+
+/** What `Tree.Item` hands its row: state is decided there, markup here. */
+export interface TreeRowProps {
+  value: string
+  level: number
+  label: ReactNode
+  meta?: ReactNode
+  /** plain text of the item (typeahead, native names) */
+  text: string
+  href?: string
+  onNavigate?: OnNavigate
+  hasChildren: boolean
+  open: boolean
+  selected: boolean
+  /** the item holds the tree's tab stop */
+  tabStop: boolean
+  /** draw the keyboard focus ring on the row */
+  ringed: boolean
+  labelId: string
+  metaId: string
+  onSelect: () => void
+  onToggle: () => void
+  /** the chevron control's accessible name (native) */
+  expandLabel?: (label: string) => string
+  /** the open branch's children, already inside their level context */
+  branch: ReactNode
+  /** web, windowed tree: the row is flat, placed by the window, and sets its own set size */
+  windowed?: WindowedRow
+}
+
+/** What a row of a windowed tree adds: the window places and measures it. */
+export interface WindowedRow {
+  /** the row's index among the visible rows (the virtualizer's `data-index`) */
+  index: number
+  setSize: number
+  posInSet: number
+  /** distance from the top of the scrolled content, in px */
+  top: number
+  measureRef: (el: HTMLElement | null) => void
+}

package/src/components/Tree/TreeRows.ts

@@ -0,0 +1,139 @@
+import {Children, Fragment, isValidElement, type ReactElement, type ReactNode} from 'react'
+import type {OnNavigate} from '../../shared/navigate'
+
+/** The props of a `Tree.Item`. */
+export interface TreeItemProps {
+  /** unique within the tree */
+  value: string
+  /** what the row shows */
+  label: ReactNode
+  /** plain text for typeahead when `label` isn't a string */
+  textValue?: string
+  /** nested items: the branch's children (none = a leaf) */
+  children?: ReactNode
+  /** trailing content on the row (a count, a status) */
+  meta?: ReactNode
+  /**
+   * Makes the row a link to this URL. A plain click (or Enter / Space)
+   * selects the item and calls `onNavigate`; a modified click keeps the
+   * browser default (new tab, new window) and does not select.
+   */
+  href?: string
+  /**
+   * Client-side navigation for `href`: called for a plain primary click. Call
+   * `event.preventDefault()`, then your router's navigate.
+   */
+  onNavigate?: OnNavigate
+}
+
+/** One visible row of the tree, read from the items without rendering them. */
+export interface TreeRowModel {
+  value: string
+  level: number
+  text: string
+  label: ReactNode
+  meta: ReactNode
+  href: string | undefined
+  onNavigate: OnNavigate | undefined
+  hasChildren: boolean
+  open: boolean
+  /** the value of the parent row, null at the top level */
+  parent: string | null
+  setSize: number
+  posInSet: number
+}
+
+export interface CollectedRows {
+  /** the rows in view order: an open branch is followed by its children */
+  rows: TreeRowModel[]
+  /** every item of the tree, open or not (what the threshold counts) */
+  total: number
+  /**
+   * false when a branch holds something other than `Tree.Item`s (an item
+   * inside another component): the pass cannot see those rows, so the tree
+   * must not be windowed, or they would vanish
+   */
+  complete: boolean
+}
+
+/** The plain text of an item: typeahead and names. */
+export function itemText(label: ReactNode, textValue: string | undefined): string {
+  return textValue ?? (typeof label === 'string' ? label : '')
+}
+
+type ItemElement = ReactElement<TreeItemProps>
+
+/** The `Tree.Item` elements among `children`, looking through fragments and arrays. */
+function itemsOf(children: ReactNode, isItem: (el: ReactElement) => boolean): ItemElement[] {
+  const out: ItemElement[] = []
+  Children.forEach(children, (child) => {
+    if (!isValidElement<{children?: ReactNode}>(child)) return
+    if (child.type === Fragment) out.push(...itemsOf(child.props.children, isItem))
+    else if (isItem(child)) out.push(child as ItemElement)
+  })
+  return out
+}
+
+/**
+ * holds-until: a consumer needs to window a tree whose Items sit inside its own
+ * components. The pass reads JSX props only, so it cannot see an Item that a
+ * component renders; `complete` turns false and Tree renders unwindowed with a
+ * dev warning. Then: collect by rendering Items in a register-only mode.
+ *
+ * The collect pass: walks the `Tree.Item` elements of the tree and returns its
+ * visible rows, with each row's level and its set size and position among its
+ * siblings. It reads props only: no DOM, no render, no mutation of anything
+ * outside this call. Items must be JSX descendants of the root (through
+ * fragments or arrays); an item hidden inside another component is not seen.
+ */
+export function collectRows(
+  children: ReactNode,
+  isItem: (el: ReactElement) => boolean,
+  isOpen: (value: string) => boolean,
+): CollectedRows {
+  const rows: TreeRowModel[] = []
+  let total = 0
+  let complete = true
+  const visit = (nodes: ReactNode, level: number, parent: string | null, visible: boolean) => {
+    const items = itemsOf(nodes, isItem)
+    items.forEach((item, index) => {
+      const {value, label, textValue, children: nested, meta, href, onNavigate} = item.props
+      const hasChildren = Children.count(nested) > 0
+      if (hasChildren && countLeaves(nested) !== itemsOf(nested, isItem).length) complete = false
+      const open = hasChildren && isOpen(value)
+      total += 1
+      if (visible) {
+        rows.push({
+          value,
+          level,
+          text: itemText(label, textValue),
+          label,
+          meta,
+          href,
+          onNavigate,
+          hasChildren,
+          open,
+          parent,
+          setSize: items.length,
+          posInSet: index + 1,
+        })
+      }
+      if (hasChildren) visit(nested, level + 1, value, visible && open)
+    })
+  }
+  visit(children, 1, null, true)
+  if (countLeaves(children) !== itemsOf(children, isItem).length) complete = false
+  return {rows, total, complete}
+}
+
+/** The non-fragment nodes among `children` (null, false and '' are not counted). */
+function countLeaves(children: ReactNode): number {
+  let n = 0
+  Children.forEach(children, (child) => {
+    if (child == null || typeof child === 'boolean' || child === '') return
+    if (isValidElement<{children?: ReactNode}>(child) && child.type === Fragment) {
+      n += countLeaves(child.props.children)
+    } else n += 1
+  })
+  return n
+}

package/src/components/Tree/TreeWindow.native.tsx

@@ -0,0 +1,19 @@
+import type {ReactNode} from 'react'
+import type {Length} from '../../shared/length'
+import type {TreeRowModel} from './TreeRows'
+
+/* Native renders every row (windowing is the host app's, plan N0): the web
+ * window and its @tanstack/react-virtual stay out of the native graph. */
+export const CAN_WINDOW = false
+
+interface TreeWindowProps {
+  rows: readonly TreeRowModel[]
+  maxHeight?: Length
+  'aria-label'?: string
+  'aria-labelledby'?: string
+  scrollRef: unknown
+}
+
+export function TreeWindow(_props: TreeWindowProps): ReactNode {
+  return null
+}

package/src/components/Tree/TreeWindow.tsx

@@ -0,0 +1,118 @@
+import {defaultRangeExtractor, useVirtualizer, type Range} from '@tanstack/react-virtual'
+import {type RefObject, useEffect} from 'react'
+import {html} from 'react-strict-dom'
+import {SIZES_PX} from '@duro-app/tokens/keys'
+import {resolveLength, type Length} from '../../shared/length'
+import {useTree} from './TreeContext'
+import {useTreePendingFocus} from './TreeFocusStore'
+import {TreeItemRow} from './TreeItemRow'
+import type {TreeRowModel} from './TreeRows'
+import {styles} from './styles.css'
+
+export const CAN_WINDOW = true
+
+/** Rows rendered beyond each edge of the view. */
+const OVERSCAN = 8
+/** A row's height before it is measured: the touch target, as VirtualList. */
+const ESTIMATED_ROW_PX = SIZES_PX.controlMd
+
+interface TreeWindowProps {
+  rows: readonly TreeRowModel[]
+  maxHeight?: Length
+  'aria-label'?: string
+  'aria-labelledby'?: string
+  scrollRef: RefObject<HTMLDivElement | null>
+}
+
+/**
+ * The windowed tree (web): a scroll container `role="tree"` that mounts only
+ * the rows in view, plus the tab stop, as flat treeitems carrying their level,
+ * set size and position. The keyboard runs in useTreeKeyboard on the row
+ * model; a move to a row that is not mounted asks the focus store, and this
+ * window scrolls to it and focuses it once it mounts.
+ */
+export function TreeWindow({
+  rows,
+  maxHeight,
+  'aria-label': ariaLabel,
+  'aria-labelledby': ariaLabelledBy,
+  scrollRef,
+}: TreeWindowProps) {
+  const {focus} = useTree()
+  const pending = useTreePendingFocus(focus)
+  const virtualizer = useVirtualizer({
+    count: rows.length,
+    getScrollElement: () => scrollRef.current,
+    estimateSize: () => ESTIMATED_ROW_PX,
+    getItemKey: (index) => rows[index]?.value ?? index,
+    overscan: OVERSCAN,
+    // the tab stop stays mounted wherever the view is, so Tab can always enter
+    rangeExtractor: (range: Range) => {
+      const indexes = defaultRangeExtractor(range)
+      const stop = rows.findIndex((row) => row.value === focus.getValue())
+      if (stop < 0 || indexes.includes(stop)) return indexes
+      return [...indexes, stop].sort((a, b) => a - b)
+    },
+  })
+
+  const target = pending === null ? -1 : rows.findIndex((row) => row.value === pending)
+  useEffect(() => {
+    if (target >= 0) virtualizer.scrollToIndex(target)
+  }, [target, virtualizer])
+  // after the scroll the row is mounted (the extractor keeps the tab stop in
+  // the window): focus it and answer the request
+  useEffect(() => {
+    if (pending === null) return
+    if (target < 0) {
+      focus.clearPending()
+      return
+    }
+    const el = scrollRef.current?.querySelector<HTMLElement>(`[data-index="${target}"]`)
+    if (!el) return
+    el.focus({preventScroll: true})
+    focus.clearPending()
+  })
+
+  const virtualRows = virtualizer.getVirtualItems()
+  return (
+    <html.div
+      ref={scrollRef}
+      role="tree"
+      aria-label={ariaLabel}
+      aria-labelledby={ariaLabelledBy}
+      style={[
+        styles.windowScroller,
+        maxHeight !== undefined && styles.windowScrollerMax(resolveLength(maxHeight)),
+      ]}
+    >
+      <html.div role="none" style={styles.windowTotal(virtualizer.getTotalSize())}>
+        {virtualRows.map((virtualRow) => {
+          const row = rows[virtualRow.index]
+          if (!row) return null
+          return (
+            <TreeItemRow
+              key={row.value}
+              value={row.value}
+              level={row.level}
+              label={row.label}
+              meta={row.meta}
+              text={row.text}
+              href={row.href}
+              onNavigate={row.onNavigate}
+              hasChildren={row.hasChildren}
+              open={row.open}
+              branch={null}
+              windowed={{
+                index: virtualRow.index,
+                setSize: row.setSize,
+                posInSet: row.posInSet,
+                top: virtualRow.start,
+                measureRef: virtualizer.measureElement,
+              }}
+            />
+          )
+        })}
+      </html.div>
+    </html.div>
+  )
+}