@ahrowe/ui 0.27.0 → 0.28.0

package/docs/Tree.md

@@ -0,0 +1,95 @@
+# Tree
+
+**When to use:** A hierarchical list the user can expand, collapse and pick from: categories, nested locations, folder structures, org charts. For a flat list of thousands of rows use [VirtualList](VirtualList.md); for picking several unrelated values use [MultiSelect](MultiSelect.md).
+
+**Keywords:** hierarchy, directory, expand collapse, parent child, drilldown, navigation sidebar, outline, subfolder
+
+**Import:** `import { Tree, flattenTree } from '@ahrowe/ui'`  
+**Types:** `import type { TreeProps, TreeNode, TreeValue, FlatTreeNode } from '@ahrowe/ui'`
+
+```tsx
+import { useState } from 'react';
+import { Tree } from '@ahrowe/ui';
+import type { TreeNode, TreeValue } from '@ahrowe/ui';
+
+const nodes: TreeNode[] = [
+  {
+    key: 'hall-1',
+    label: 'Hall 1',
+    children: [
+      { key: 'bay-a', label: 'Bay A' },
+      { key: 'bay-b', label: 'Bay B' },
+    ],
+  },
+  { key: 'archive', label: 'Archive', disabled: true },
+];
+
+// Controlled selection
+const [selected, setSelected] = useState<TreeValue | null>(null);
+<Tree nodes={nodes} selectedKey={selected} onSelect={setSelected} aria-label="Locations" />
+
+// Uncontrolled, with some branches open to begin with
+<Tree nodes={nodes} defaultExpandedKeys={['hall-1']} defaultSelectedKey="bay-a" />
+
+// Controlled expansion, e.g. to persist it
+<Tree nodes={nodes} expandedKeys={open} onExpandedChange={setOpen} />
+
+// Clicking a branch selects it without opening it
+<Tree nodes={nodes} expandOnSelect={false} />
+
+// Icons per node, and a wider indent
+import { faWarehouse } from '@fortawesome/free-solid-svg-icons';
+<Tree nodes={nodes.map((n) => ({ ...n, icon: faWarehouse }))} indent={40} />
+```
+
+**Branch or leaf:** a node is a branch when it has a `children` array, even an empty one. `children: []` renders a toggle with nothing behind it yet, which is what you want while a branch's contents are still loading; omit `children` entirely for a true leaf.
+
+**Selection is single.** `onSelect` fires with the key and the node itself, so you do not have to look it up again. There is no multi-select or checkbox mode.
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `nodes` | `TreeNode[]` | The tree: `{ key, label, icon?, children?, disabled? }` |
+| `expandedKeys` | `TreeValue[]` | Controlled open branches (omit for uncontrolled) |
+| `defaultExpandedKeys` | `TreeValue[]` | Branches open initially when uncontrolled (default `[]`) |
+| `onExpandedChange` | `(keys: TreeValue[]) => void` | Fires with the full new set of open branches |
+| `selectedKey` | `TreeValue \| null` | Controlled selection (omit for uncontrolled) |
+| `defaultSelectedKey` | `TreeValue` | Selection when uncontrolled |
+| `onSelect` | `(key: TreeValue, node: TreeNode) => void` | Fires with the picked key and node |
+| `expandOnSelect` | `boolean` | Clicking a branch's row also toggles it (default `true`) |
+| `indent` | `number` | Pixels per level (default `20`) |
+| `toggleIcon` | `IconDefinition \| ReactElement` | Toggle icon, rotated 90° when open (default a right chevron) |
+| `height` | `number \| string` | Windows the rows through `VirtualList` at this viewport height |
+| `estimatedRowHeight` | `number` | Row height for the windowed renderer (default `32`) |
+| `emptyLabel` | `string` | Shown when `nodes` is empty (default `'Nothing here'`) |
+| `disabled` | `boolean` | Dims the tree and blocks interaction |
+| `aria-label` | `string` | Accessible name for the tree (default `'Tree'`) |
+
+**Keyboard:** `↑`/`↓` move between visible rows. `→` opens a closed branch, then steps into its first child. `←` closes an open branch, then steps out to its parent. `Home`/`End` jump to the ends. `Enter` or `Space` selects.
+
+**Accessibility:** `role="tree"` containing `role="treeitem"` rows. Because the rows render flat rather than nested, each carries `aria-level`, `aria-posinset` and `aria-setsize`; branches also carry `aria-expanded`. Focus uses a roving tabindex, so one row at a time is reachable by Tab, and it is the selected one (or the first, before anything is selected). The toggle is `aria-hidden`, since `aria-expanded` on the row already reports the state.
+
+**Why flat:** the rows are a flattened list, not nested `<div>`s. Keyboard movement becomes a step along one array instead of a tree walk, and a node's accessible name stays its own label rather than absorbing its descendants'.
+
+**Very large trees:** set `height`. `Tree` then windows its rows through [VirtualList](VirtualList.md), so only the ones in view are in the DOM, and it keeps everything else: the ARIA, the expansion, the selection and the keyboard.
+
+```tsx
+<Tree nodes={nodes} height={300} expandedKeys={open} onExpandedChange={setOpen} />
+```
+
+Two things change in that mode. Rows must be a uniform height, so size them with `--tree-node-height` rather than per row. And the tab stop moves from the selected row to the tree itself, because a roving tabindex on a row that is scrolled out of the window would leave the tree with no tab stop at all; tabbing in still lands on the selected row, which is scrolled into view first.
+
+`flattenTree` is exported separately if you want the rows without the component: it returns `FlatTreeNode`s carrying `node`, `level`, `parentKey`, `isBranch`, `isExpanded`, `setSize` and `posInSet`, ready for `VirtualList`'s `items` and `getItemDepth` (which also feeds its `treeReorder` drag-and-drop). You then write the row markup, ARIA and keyboard handling yourself.
+
+**Theming:** override these CSS variables theme-wide via `ThemeProvider` or per instance via `style`; each falls back to a built-in default:
+
+| Variable | Falls back to |
+|----------|---------------|
+| `--tree-node-height` | `32px` |
+| `--tree-selected-background` | `var(--primary-color)` |
+| `--tree-selected-color` | `var(--text-on-primary)` |
+
+**Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ Tree: { indent: 30 } }}`. See [ConfigProvider.md](ConfigProvider.md).
+
+**Slots:** `root` `node` `toggle` `icon` `label` `empty`

package/docs/VirtualList.md

@@ -139,6 +139,7 @@ const columns: VirtualListColumn<User>[] = [
 | `onLoadMore` | `() => Promise<void>` | Triggered near the bottom, and repeatedly while the rows don't fill the viewport — append items in the handler |
 | `loadMoreThreshold` | `number` | Distance from bottom that triggers `onLoadMore` (default `100`) |
 | `isLoading` | `boolean` | Replaces list body with a full-height spinner |
+| `ariaRoles` | `{ container: string; row: string }` | Replaces the roles put on the container and rows (default `list`/`listitem`, or `grid`/`row` with columns). Pass `'none'` for both when the rows carry their own semantics, as [Tree](Tree.md) does when windowing `treeitem` rows |
 
 Drag-and-drop reordering adds `reorderable`, `treeReorder`, `dragHandle`, and their callbacks — see **Row reordering** below.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahrowe/ui",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "publishConfig": {
     "access": "public"
   },
@@ -55,7 +55,7 @@
     "build:mcp": "vite build --config vite.mcp.config.ts",
     "preview": "vite preview",
     "gen-barrel": "tsx scripts/gen-barrel.ts",
-    "gc": "bash src/scripts/generateComponent.sh",
+    "gc": "tsx scripts/generate-component.ts",
     "changeset": "changeset",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",