@duro-app/ui 5.18.0 → 5.20.0

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

@@ -30,6 +30,37 @@ export const styles = css.create({
     outlineWidth: 0,
     outlineStyle: 'none',
   },
+  // the scroll container of a windowed tree (role="tree"): fills its parent,
+  // or stops at `maxHeight`
+  windowScroller: {
+    position: 'relative',
+    width: '100%',
+    height: '100%',
+    minHeight: 0,
+    margin: 0,
+    padding: 0,
+    listStyleType: 'none',
+    overflowY: 'auto',
+    overscrollBehavior: 'contain',
+  },
+  windowScrollerMax: (maxHeight: number | string) => ({
+    height: 'auto',
+    maxHeight,
+  }),
+  // the full virtual height, so the scrollbar is the tree's real length
+  windowTotal: (height: number) => ({
+    position: 'relative',
+    width: '100%',
+    height,
+  }),
+  // a windowed row: flat, placed by the window
+  windowRow: (top: number) => ({
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    width: '100%',
+    transform: `translateY(${top}px)`,
+  }),
   row: {
     display: 'flex',
     alignItems: 'center',
@@ -73,9 +104,57 @@ 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: {
+  // Native: the outer row View, holding the chevron control and the press
+  // target as siblings (the level indent is added by the row).
+  nativeRow: {
     display: 'flex',
+    flexDirection: 'row',
+    alignItems: 'center',
+    paddingRight: spacing.sm,
+    borderRadius: radii.sm,
+  },
+  // Native: the pressable part of the row.
+  pressTarget: {
+    display: 'flex',
+    flexDirection: 'row',
+    alignItems: 'center',
+    flexGrow: 1,
+    flexShrink: 1,
+    gap: spacing.xs,
+    paddingTop: microSpacing.px5,
+    paddingBottom: microSpacing.px5,
+    borderRadius: radii.sm,
+    backgroundColor: {
+      default: 'transparent',
+      ':active': colors.bgCardHover,
+    },
+  },
+  // Native: the branch's chevron control, at least the WCAG 2.5.8 minimum.
+  chevronControl: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    minWidth: sizes.chip,
+    minHeight: sizes.chip,
+    flexShrink: 0,
+  },
+  chevronGlyph: {
+    color: colors.textMuted,
+  },
+  // Native: a leaf's gutter, as wide as the chevron control, inside the press target.
+  chevronSpacer: {
+    width: sizes.chip,
+    flexShrink: 0,
+  },
+  labelBox: {
+    display: 'flex',
+    flexGrow: 1,
+    flexShrink: 1,
+    minWidth: 0,
+  },
+  metaBox: {
+    display: 'flex',
+    flexShrink: 0,
   },
   chevron: {
     display: 'inline-flex',

package/src/components/Tree/useTreeKeyboard.ts

@@ -1,31 +1,70 @@
-import {type ReactNode, useEffect, useLayoutEffect, useRef} from 'react'
+import {type RefObject, useEffect, useLayoutEffect, useRef} from 'react'
+import type {TreeFocusStore} from './TreeFocusStore'
+import type {TreeRowModel} from './TreeRows'
 
 /** 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
+  rootRef: RefObject<HTMLElement | null>
+  focus: TreeFocusStore
+  /** the visible rows when the tree is windowed (most are not in the DOM), else null */
+  windowedRows: readonly TreeRowModel[] | null
+  /** a change here re-checks the tab stop: the items or the open branches */
+  children: unknown
   open: ReadonlyArray<string>
-  children: ReactNode
   onSelect: (value: string) => void
   setExpanded: (value: string, open: boolean) => void
 }
 
+/** What navigation needs of an item, from the row model or from the DOM. */
+interface NavItem {
+  value: string
+  text: string
+  /** undefined for a leaf */
+  expanded: boolean | undefined
+  parent: string | null
+}
+
+const itemSelector = (value: string) => `[data-tree-value="${CSS.escape(value)}"]`
+
+/** The rendered treeitems as nav items: DOM order IS the visible order. */
+function readDom(root: HTMLElement): NavItem[] {
+  return Array.from(root.querySelectorAll<HTMLElement>('[role="treeitem"]')).map((el) => {
+    const expanded = el.getAttribute('aria-expanded')
+    const parent = el.parentElement?.closest<HTMLElement>('[role="treeitem"]')
+    return {
+      value: el.dataset.treeValue ?? '',
+      text: el.dataset.treeText ?? '',
+      expanded: expanded === null ? undefined : expanded === 'true',
+      parent: parent && root.contains(parent) ? (parent.dataset.treeValue ?? null) : null,
+    }
+  })
+}
+
+function readRows(rows: readonly TreeRowModel[]): NavItem[] {
+  return rows.map((row) => ({
+    value: row.value,
+    text: row.text,
+    expanded: row.hasChildren ? row.open : undefined,
+    parent: row.parent,
+  }))
+}
+
 /**
  * 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.
+ * (WAI-ARIA tree pattern). A nested tree reads its items from the DOM; a
+ * windowed one from the row model, since most rows are not mounted: a move to
+ * a row that is not mounted goes through the focus store, and the window
+ * scrolls to it and focuses it. Native has none of them (plan N0, Decision 6):
+ * useTreeKeyboard.native.ts.
  */
 export function useTreeKeyboard({
   rootRef,
-  focusValue,
-  setFocusValue,
-  setKeyboardFocus,
-  open,
+  focus,
+  windowedRows,
   children,
+  open,
   onSelect,
   setExpanded,
 }: TreeKeyboardInput) {
@@ -34,32 +73,33 @@ export function useTreeKeyboard({
   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])
+    if (root.querySelector('[role="treeitem"][tabindex="0"]')) return
+    const first =
+      windowedRows?.[0]?.value ??
+      root.querySelector<HTMLElement>('[role="treeitem"]')?.dataset.treeValue ??
+      null
+    focus.setValue(first)
+  }, [rootRef, focus, windowedRows, children, open])
 
-  // 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()
+    const read = () => (windowedRows ? readRows(windowedRows) : readDom(rootEl))
+    const focusItem = (item: NavItem | undefined) => {
+      if (!item) return
+      const el = rootEl.querySelector<HTMLElement>(itemSelector(item.value))
+      if (el) el.focus()
+      else focus.request(item.value)
     }
     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 list = read()
       const val = current.dataset.treeValue ?? ''
-      const isOpen = current.getAttribute('aria-expanded')
+      const i = list.findIndex((item) => item.value === val)
+      const here = list[i]
       switch (e.key) {
         case 'ArrowDown':
           e.preventDefault()
@@ -71,17 +111,16 @@ export function useTreeKeyboard({
           return
         case 'ArrowRight':
           e.preventDefault()
-          if (isOpen === 'false') setExpanded(val, true)
-          else if (isOpen === 'true') focusItem(list[i + 1])
+          if (here?.expanded === false) setExpanded(val, true)
+          else if (here?.expanded === true) focusItem(list[i + 1])
           return
         case 'ArrowLeft': {
           e.preventDefault()
-          if (isOpen === 'true') {
+          if (here?.expanded === true) {
             setExpanded(val, false)
             return
           }
-          const parent = current.parentElement?.closest<HTMLElement>('[role="treeitem"]')
-          if (parent && rootEl.contains(parent)) focusItem(parent)
+          focusItem(list.find((item) => item.value === here?.parent))
           return
         }
         case 'Home':
@@ -99,7 +138,12 @@ export function useTreeKeyboard({
           // runs onNavigate, or the browser navigates)
           const link = current.querySelector<HTMLElement>(':scope > [data-tree-link]')
           if (link) link.click()
-          else onSelect(val)
+          else {
+            onSelect(val)
+            // a branch with no link toggles too, as a click on its row does
+            const expanded = current.getAttribute('aria-expanded')
+            if (expanded !== null) setExpanded(val, expanded !== 'true')
+          }
           return
         }
       }
@@ -116,9 +160,9 @@ export function useTreeKeyboard({
         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)
+          const item = list[(start + k) % list.length]
+          if (item.text.toLocaleLowerCase().startsWith(needle)) {
+            focusItem(item)
             break
           }
         }
@@ -128,14 +172,14 @@ export function useTreeKeyboard({
     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)
+      if (v) focus.setValue(v)
+      focus.setRing(item?.matches(':focus-visible') ?? false)
     }
     function onFocusOut(e: FocusEvent) {
-      if (!rootEl.contains(e.relatedTarget as Node | null)) setKeyboardFocus(false)
+      if (!rootEl.contains(e.relatedTarget as Node | null)) focus.setRing(false)
     }
-    const onPointerDown = () => setKeyboardFocus(false)
-    const onKey = () => setKeyboardFocus(true)
+    const onPointerDown = () => focus.setRing(false)
+    const onKey = () => focus.setRing(true)
     root.addEventListener('keydown', onKeyDown)
     root.addEventListener('keydown', onKey)
     root.addEventListener('focusin', onFocusIn)
@@ -148,5 +192,5 @@ export function useTreeKeyboard({
       root.removeEventListener('focusout', onFocusOut)
       root.removeEventListener('pointerdown', onPointerDown)
     }
-  }, [rootRef, onSelect, setExpanded, setFocusValue, setKeyboardFocus])
+  }, [rootRef, focus, windowedRows, onSelect, setExpanded])
 }

package/src/index.native.ts

@@ -24,6 +24,7 @@ export {Heading, type HeadingVariant} from './components/Heading/Heading'
 export {Input, type InputVariant} from './components/Input/Input'
 export {Switch} from './components/Switch/Switch'
 export {Text, type TextVariant, type TextColor} from './components/Text/Text'
+export {TextLink, type TextLinkVariant} from './components/TextLink/TextLink'
 export {Textarea, type TextareaVariant} from './components/Textarea/Textarea'
 
 // Form field wrappers (RN-safe — used by Input/Textarea/Checkbox)
@@ -95,11 +96,14 @@ export {
 
 // Layout primitives
 export {PageShell, type PageShellMaxWidth, type PageShellPadding} from './components/PageShell'
+export {Panel} from './components/Panel/Panel'
 export {Stack, type SpacingKey} from './components/Stack/Stack'
 export {Inline} from './components/Inline/Inline'
 export {Cluster} from './components/Cluster/Cluster'
 export {Grid} from './components/Grid/Grid'
 export type {GridTrack} from './shared/length'
+// ADR-0002: the shape a link part's onNavigate receives (native: followLink)
+export type {LinkClickEvent, OnNavigate} from './shared/navigate'
 
 // Theming — resolves to ThemeProvider.native.tsx on Metro (RN-safe variant:
 // no display:contents / portal mount; applies the theme to a flex container).

package/src/shared/InLandmarkContext.ts

@@ -0,0 +1,8 @@
+import {createContext} from 'react'
+
+/**
+ * True inside `AppShell.Rail`, which is already a named navigation landmark.
+ * A `SideNav.Root` reads it and renders no second navigation landmark: a plain
+ * block, or `role="group"` carrying its `aria-label` when it has one.
+ */
+export const InLandmarkContext = createContext(false)

package/src/shared/followLink.native.ts

@@ -0,0 +1,33 @@
+import {Linking} from 'react-native'
+import type {LinkClickEvent, OnNavigate} from './navigate'
+
+/**
+ * Follows a link on native (ADR-0002, native addendum): a native link part
+ * renders no `href`, because react-strict-dom replaces the press handler of an
+ * `html.a` that has one. It builds a tracked `LinkClickEvent` (primary button,
+ * no modifier), hands it to `onNavigate`, and opens the URL with the system
+ * (`Linking.openURL`) unless `onNavigate` called `event.preventDefault()`.
+ * `source` names the part in the warning when the URL cannot be opened.
+ */
+export function followLink(href: string, onNavigate: OnNavigate | undefined, source: string): void {
+  let prevented = false
+  const event: LinkClickEvent = {
+    button: 0,
+    metaKey: false,
+    ctrlKey: false,
+    shiftKey: false,
+    altKey: false,
+    get defaultPrevented() {
+      return prevented
+    },
+    preventDefault() {
+      prevented = true
+    },
+  }
+  onNavigate?.(href, event)
+  if (!prevented) {
+    Linking.openURL(href).catch((error: unknown) => {
+      console.warn(`[duro] ${source}: could not open ${href}: ${String(error)}`)
+    })
+  }
+}

package/src/shared/navigate.ts

@@ -1,4 +1,6 @@
 /* Router-agnostic links (docs/adr/0002-link-parts-navigate-through-onnavigate.md).
+ * On native a link part renders no `href` and goes through `followLink`
+ * (followLink.native.ts), which calls the same `onNavigate` (ADR-0002 addendum).
  *
  * Every link part renders a real `<a href>`, so the browser keeps what a link
  * does on its own: cmd/ctrl-click and middle-click open a tab, shift-click a