@duro-app/ui 3.5.0 → 3.7.0

package/src/components/Tree/Tree.tsx

@@ -0,0 +1,304 @@
+import {
+  Children,
+  type ReactNode,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from 'react'
+import {html} from 'react-strict-dom'
+import {styles} from './styles.css'
+import {TreeContext, TreeLevelContext, useTree} from './TreeContext'
+
+/* Tree — a hierarchy of items (the WAI-ARIA tree pattern): single selection,
+ * expandable branches, one tab stop (roving tabindex), and the keyboard of a
+ * file explorer — ↑/↓ move between visible items, → opens a branch then goes
+ * to its first child, ← closes it then goes to the parent, Home/End, Enter
+ * or Space select, and typing jumps to the next item whose label starts with
+ * the typed letters. */
+
+// --- Root ---
+
+interface RootProps {
+  children: ReactNode
+  /** accessible name of the tree (or give `aria-labelledby`) */
+  'aria-label'?: string
+  'aria-labelledby'?: string
+  /** the selected item (controlled) */
+  value?: string | null
+  defaultValue?: string | null
+  onValueChange?: (value: string) => void
+  /** the open branches (controlled) */
+  expanded?: ReadonlyArray<string>
+  defaultExpanded?: ReadonlyArray<string>
+  onExpandedChange?: (expanded: string[]) => void
+}
+
+const TYPEAHEAD_RESET_MS = 500
+
+function Root({
+  children,
+  'aria-label': ariaLabel,
+  'aria-labelledby': ariaLabelledBy,
+  value,
+  defaultValue = null,
+  onValueChange,
+  expanded,
+  defaultExpanded = [],
+  onExpandedChange,
+}: RootProps) {
+  const [selectedInner, setSelectedInner] = useState<string | null>(defaultValue)
+  const selectedValue = value !== undefined ? value : selectedInner
+  const [expandedInner, setExpandedInner] = useState<ReadonlyArray<string>>(defaultExpanded)
+  const open = expanded ?? expandedInner
+  const [focusValue, setFocusValue] = useState<string | null>(selectedValue)
+  // the ring shows on the focused ROW (the item wraps its children, so a
+  // ring on it would circle the whole branch), only for keyboard focus —
+  // the tree's own :focus-visible
+  const [keyboardFocus, setKeyboardFocus] = useState(false)
+  const rootRef = useRef<HTMLUListElement>(null)
+
+  const onSelect = useCallback(
+    (v: string) => {
+      if (value === undefined) setSelectedInner(v)
+      onValueChange?.(v)
+    },
+    [value, onValueChange],
+  )
+  const setExpanded = useCallback(
+    (v: string, isOpen: boolean) => {
+      const next = isOpen ? [...new Set([...open, v])] : open.filter((x) => x !== v)
+      if (next.length === open.length && next.every((x, i) => x === open[i])) return
+      if (expanded === undefined) setExpandedInner(next)
+      onExpandedChange?.(next)
+    },
+    [open, expanded, onExpandedChange],
+  )
+  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()
+          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])
+
+  return (
+    <TreeContext.Provider
+      value={{
+        selectedValue,
+        onSelect,
+        isExpanded,
+        toggle,
+        setExpanded,
+        focusValue,
+        setFocusValue,
+        keyboardFocus,
+      }}
+    >
+      <TreeLevelContext.Provider value={1}>
+        <html.ul
+          ref={rootRef}
+          role="tree"
+          aria-label={ariaLabel}
+          aria-labelledby={ariaLabelledBy}
+          style={styles.root}
+        >
+          {children}
+        </html.ul>
+      </TreeLevelContext.Provider>
+    </TreeContext.Provider>
+  )
+}
+
+// --- Item ---
+
+interface ItemProps {
+  /** 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
+}
+
+function Item({value, label, textValue, children, meta}: ItemProps) {
+  const {selectedValue, onSelect, isExpanded, toggle, focusValue, keyboardFocus} = useTree()
+  const level = useContext(TreeLevelContext)
+  const hasChildren = Children.count(children) > 0
+  const open = hasChildren && isExpanded(value)
+  const selected = selectedValue === value
+  const text = textValue ?? (typeof label === 'string' ? label : '')
+  // named by its own label only: a branch's content includes its children,
+  // and a name computed from content would read the whole subtree
+  const labelId = useId()
+
+  return (
+    <html.li
+      role="treeitem"
+      aria-labelledby={labelId}
+      aria-level={level}
+      aria-expanded={hasChildren ? open : undefined}
+      aria-selected={selected}
+      tabIndex={focusValue === value ? 0 : -1}
+      data-tree-value={value}
+      data-tree-text={text}
+      style={styles.item}
+    >
+      <html.div
+        onClick={() => onSelect(value)}
+        style={[
+          styles.row,
+          styles.indent(level),
+          selected && styles.rowSelected,
+          keyboardFocus && focusValue === value && styles.rowFocused,
+        ]}
+      >
+        <html.span
+          aria-hidden
+          onClick={(e: {stopPropagation: () => void}) => {
+            if (!hasChildren) return
+            e.stopPropagation()
+            toggle(value)
+          }}
+          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 style={styles.meta}>{meta}</html.span> : null}
+      </html.div>
+      {open ? (
+        <TreeLevelContext.Provider value={level + 1}>
+          <html.ul role="group" style={styles.group}>
+            {children}
+          </html.ul>
+        </TreeLevelContext.Provider>
+      ) : null}
+    </html.li>
+  )
+}
+
+export const Tree = {
+  Root,
+  Item,
+}

package/src/components/Tree/TreeContext.ts

@@ -0,0 +1,26 @@
+import {createContext, useContext} from 'react'
+
+export interface TreeContextValue {
+  /** the selected item's value (single selection), or null */
+  selectedValue: string | null
+  onSelect: (value: string) => void
+  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
+}
+
+export const TreeContext = createContext<TreeContextValue | null>(null)
+
+export function useTree() {
+  const ctx = useContext(TreeContext)
+  if (!ctx) throw new Error('Tree compound components must be used within Tree.Root')
+  return ctx
+}
+
+/** The nesting depth of the items rendered here (1 = top level). */
+export const TreeLevelContext = createContext(1)

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

@@ -0,0 +1,96 @@
+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 {typography} from '@duro-app/tokens/tokens/typography.css'
+import {duration, easing} from '@duro-app/tokens/tokens/motion.css'
+
+export const styles = css.create({
+  root: {
+    display: 'flex',
+    flexDirection: 'column',
+    margin: 0,
+    padding: 0,
+    listStyleType: 'none',
+  },
+  // The `role="group"` holding a branch's children: purely structural.
+  group: {
+    display: 'flex',
+    flexDirection: 'column',
+    margin: 0,
+    padding: 0,
+    listStyleType: 'none',
+  },
+  // The treeitem carries focus; its row draws the ring (the item also wraps
+  // its children, so a ring on it would circle the whole branch).
+  item: {
+    display: 'flex',
+    flexDirection: 'column',
+    outlineWidth: 0,
+    outlineStyle: 'none',
+  },
+  row: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: spacing.xs,
+    paddingTop: '5px',
+    paddingBottom: '5px',
+    paddingRight: spacing.sm,
+    fontFamily: typography.fontFamily,
+    fontSize: typography.fontSizeSm,
+    color: colors.text,
+    borderRadius: radii.sm,
+    cursor: 'pointer',
+    backgroundColor: {
+      default: 'transparent',
+      ':hover': colors.bgCardHover,
+    },
+    transitionProperty: 'background-color',
+    transitionDuration: duration.fast,
+    transitionTimingFunction: easing.standard,
+  },
+  // one indent step per level below the top
+  indent: (level: number) => ({
+    paddingLeft: `calc(${spacing.sm} + ${Math.max(0, level - 1)} * ${spacing.lg})`,
+  }),
+  rowFocused: {
+    outlineWidth: 2,
+    outlineStyle: 'solid',
+    outlineColor: colors.accent,
+    outlineOffset: -2,
+  },
+  rowSelected: {
+    color: colors.accent,
+    fontWeight: typography.fontWeightMedium,
+    backgroundColor: colors.bgCardHover,
+  },
+  chevron: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    width: spacing.md,
+    flexShrink: 0,
+    color: colors.textMuted,
+    transitionProperty: 'transform',
+    transitionDuration: duration.fast,
+    transitionTimingFunction: easing.standard,
+  },
+  chevronOpen: {
+    transform: 'rotate(90deg)',
+  },
+  // a leaf keeps the chevron's width (labels align) but shows nothing
+  chevronLeaf: {
+    visibility: 'hidden',
+  },
+  label: {
+    flexGrow: 1,
+    minWidth: 0,
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+    whiteSpace: 'nowrap',
+  },
+  meta: {
+    flexShrink: 0,
+    fontSize: typography.fontSizeXs,
+    color: colors.textMuted,
+  },
+})

package/src/index.ts

@@ -74,6 +74,7 @@ export {TagGroup} from './components/TagGroup/TagGroup'
 // from there gives the same object with those attached.
 export {Table, type TableVariant, type TableSize} from './components/Table/Table'
 export {Tabs} from './components/Tabs/Tabs'
+export {Tree} from './components/Tree/Tree'
 export {Textarea, type TextareaVariant} from './components/Textarea/Textarea'
 export {
   ThemeProvider,

package/src/shared/devWarnOnce.ts

@@ -0,0 +1,15 @@
+// --- Dev-only warn registry ---
+//
+// One-shot per warning code per process: long-running dev sessions
+// shouldn't drown the console on every re-render of a misused component.
+const IS_PROD = typeof process !== 'undefined' && process.env?.NODE_ENV === 'production'
+const warned = new Set<string>()
+
+/** Warn once, outside production, as `[duro-app/ui <scope>] <message>`. */
+export function devWarnOnce(scope: string, code: string, message: string): void {
+  const key = `${scope}:${code}`
+  if (IS_PROD || warned.has(key)) return
+  warned.add(key)
+
+  console.warn(`[duro-app/ui ${scope}] ${message}`)
+}