@duro-app/ui 5.24.0 → 5.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duro-app/ui",
-  "version": "5.24.0",
+  "version": "5.25.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -92,7 +92,7 @@
   "dependencies": {
     "@tanstack/react-virtual": "^3.14.13",
     "qrcode": "^1.5.4",
-    "@duro-app/tokens": "^5.24.0"
+    "@duro-app/tokens": "^5.25.0"
   },
   "devDependencies": {
     "@babel/preset-typescript": "^7.28.0",

package/src/components/Tree/Tree.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Hierarchy of items with single selection and expandable branches (the WAI-ARIA tree pattern): one tab stop, arrow keys, Home/End, typeahead. A click or Enter on a branch row with no href selects it and toggles it open or closed (a folder); a branch with href navigates, and its chevron toggles. An Item with href renders its row as a real link (cmd-click opens a tab) outside the tab order; Enter/Space follows it, through onNavigate(href, event) when given. Compound component — Root is required. On React Native each row is a pressable link (href) or button, and a branch has its own chevron control that expands it (named by the optional Root prop expandLabel(text), default the item text); selection, expansion and aria-level are the same, the keyboard model (arrows, Home/End, typeahead) is web only. On native onNavigate is required for in-app routes: without it a relative href goes to the system (Linking.openURL). On web a tree with more items than Root virtualizeThreshold (default 150, open or not) is windowed: only the rows in view mount, as flat treeitems with aria-level, aria-setsize and aria-posinset; maxHeight caps its scroll viewport. Items must be JSX descendants of Root (fragments and arrays are fine, an Item hidden inside another component is not seen by the window). Native renders every row.',
+    'Hierarchy of items with single selection and expandable branches (the WAI-ARIA tree pattern): one tab stop, arrow keys, Home/End, typeahead. A click or Enter on a branch row with no href selects it and toggles it open or closed (a folder); a branch with href navigates, and its chevron toggles. An Item with expandable is a branch before its children exist (a directory listed only when opened): it opens like any branch and onExpandedChange tells the app to load them. An Item with href renders its row as a real link (cmd-click opens a tab) outside the tab order; Enter/Space follows it, through onNavigate(href, event) when given. Compound component — Root is required. On React Native each row is a pressable link (href) or button, and a branch has its own chevron control that expands it (named by the optional Root prop expandLabel(text), default the item text); selection, expansion and aria-level are the same, the keyboard model (arrows, Home/End, typeahead) is web only. On native onNavigate is required for in-app routes: without it a relative href goes to the system (Linking.openURL). On web a tree with more items than Root virtualizeThreshold (default 150, open or not) is windowed: only the rows in view mount, as flat treeitems with aria-level, aria-setsize and aria-posinset; maxHeight caps its scroll viewport. Items must be JSX descendants of Root (fragments and arrays are fine, an Item hidden inside another component is not seen by the window). Native renders every row.',
   whenToUse: [
     'Browsing data that nests to any depth — a file tree, zones › services › capabilities, namespace › resource',
     'Picking one node of a hierarchy to show its details beside the tree',

package/src/components/Tree/Tree.stories.tsx

@@ -616,3 +616,42 @@ export const BranchRowToggles: Story = {
     await expect(branch).toHaveAttribute('aria-expanded', 'false')
   },
 }
+
+/** A file tree that lists a directory only when it is opened (`expandable`). */
+function LazyFolders() {
+  const [expanded, setExpanded] = useState<string[]>([])
+  const [loaded, setLoaded] = useState<ReadonlySet<string>>(() => new Set())
+  return (
+    <Tree.Root
+      aria-label="Folders"
+      expanded={expanded}
+      onExpandedChange={(next) => {
+        setExpanded(next)
+        // The app lists a directory the first time it opens.
+        setLoaded((prev) => new Set([...prev, ...next]))
+      }}
+    >
+      <Tree.Item value="src" label="src" expandable>
+        {loaded.has('src') ? <Tree.Item value="app" label="app.ts" /> : null}
+      </Tree.Item>
+      <Tree.Item value="readme" label="README.md" />
+    </Tree.Root>
+  )
+}
+
+export const ExpandableBranchLoadsOnOpen: Story = {
+  name: 'Expandable branch loads on open',
+  render: () => <LazyFolders />,
+  play: async ({canvas, userEvent}) => {
+    const branch = canvas.getByRole('treeitem', {name: 'src'})
+    // A branch before its children exist: it can open, a leaf cannot.
+    await expect(branch).toHaveAttribute('aria-expanded', 'false')
+    await expect(canvas.getByRole('treeitem', {name: 'README.md'})).not.toHaveAttribute(
+      'aria-expanded',
+    )
+    branch.focus()
+    await userEvent.keyboard('{ArrowRight}')
+    await expect(branch).toHaveAttribute('aria-expanded', 'true')
+    await expect(await canvas.findByRole('treeitem', {name: 'app.ts'})).toBeVisible()
+  },
+}

package/src/components/Tree/Tree.tsx

@@ -164,10 +164,19 @@ function Root({
 
 // --- Item ---
 
-function Item({value, label, textValue, children, meta, href, onNavigate}: TreeItemProps) {
+function Item({
+  value,
+  label,
+  textValue,
+  children,
+  meta,
+  href,
+  onNavigate,
+  expandable,
+}: TreeItemProps) {
   const {isExpanded} = useTree()
   const level = useContext(TreeLevelContext)
-  const hasChildren = Children.count(children) > 0
+  const hasChildren = Children.count(children) > 0 || expandable === true
 
   return (
     <TreeItemRow

package/src/components/Tree/TreeRows.ts

@@ -9,8 +9,14 @@ export interface TreeItemProps {
   label: ReactNode
   /** plain text for typeahead when `label` isn't a string */
   textValue?: string
-  /** nested items: the branch's children (none = a leaf) */
+  /** nested items: the branch's children (none = a leaf, unless `expandable`) */
   children?: ReactNode
+  /**
+   * A branch before its children exist (a directory not listed yet): it shows the
+   * chevron and opens like any branch, and `onExpandedChange` tells the app to load
+   * them. Pass the children once they are there (or a loading row meanwhile).
+   */
+  expandable?: boolean
   /** trailing content on the row (a count, a status) */
   meta?: ReactNode
   /**
@@ -97,8 +103,17 @@ export function collectRows(
   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
+      const {
+        value,
+        label,
+        textValue,
+        children: nested,
+        meta,
+        href,
+        onNavigate,
+        expandable,
+      } = item.props
+      const hasChildren = Children.count(nested) > 0 || expandable === true
       if (hasChildren && countLeaves(nested) !== itemsOf(nested, isItem).length) complete = false
       const open = hasChildren && isOpen(value)
       total += 1