@godxjp/ui 28.8.0 → 28.10.0

package/agent/components/Topbar.json

@@ -0,0 +1,83 @@
+{
+  "example": "import { Topbar, TopbarItem, AppShell } from \"@godxjp/ui/layout\";\nimport { Button } from \"@godxjp/ui/general\";\nimport { Avatar, AvatarFallback } from \"@godxjp/ui/data-display\";\nimport { AppSettingPicker } from \"@godxjp/ui/navigation\";\nimport { PanelLeftClose, Search } from \"lucide-react\";\n\n// The shell gives you slots; YOU decide what goes in them.\n<AppShell\n  sidebar={<MySidebar />}\n  topbar={\n    <Topbar\n      start={\n        <>\n          <TopbarItem aria-label={t(\"toggleSidebar\")} onClick={toggle}>\n            <PanelLeftClose />\n          </TopbarItem>\n          <Avatar className=\"rounded-md\">\n            <AvatarFallback className=\"bg-primary text-primary-foreground font-bold\">C</AvatarFallback>\n          </Avatar>\n        </>\n      }\n      center={\n        <TopbarItem onClick={openSearch}>\n          <Search />\n          {t(\"search\")}\n        </TopbarItem>\n      }\n      end={\n        <>\n          <AppSettingPicker kind=\"locale\" />\n          <UserMenu />\n        </>\n      }\n    />\n  }\n>\n  {children}\n</AppShell>",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "Topbar",
+  "props": [
+    {
+      "description": "Instance inset using logical token steps.",
+      "name": "pad",
+      "type": "PadProp"
+    },
+    {
+      "description": "bar uses shell bar height/inset. Renders a div, suitable for nested panel chrome.",
+      "name": "height",
+      "type": "\"bar\" | \"auto\""
+    },
+    {
+      "defaultValue": "undefined",
+      "description": "Inline-start cluster — typically the sidebar toggle (a `Button` with a `PanelLeftClose` icon), the brand mark (an `Avatar`), and primary nav.",
+      "name": "start",
+      "type": "ReactNode"
+    },
+    {
+      "defaultValue": "undefined",
+      "description": "Center cluster (grows + centers) — optional. e.g. a search trigger (`Button` + `Search` icon opening your command palette) or a page/entity switcher (`DropdownMenu`). ⚠ HIDDEN AT 1100px AND BELOW by default: the slot follows `--topbar-center-compact-display` (default `none`) so it cannot cover the start breadcrumb/title or the end utilities when a 16rem sidebar is docked. A global search placed here is therefore invisible on tablets and every phone until you set `--topbar-center-compact-display: flex`.",
+      "name": "center",
+      "type": "ReactNode"
+    },
+    {
+      "defaultValue": "undefined",
+      "description": "Inline-end cluster — settings pickers (`AppSettingPicker kind=\"locale\"|\"theme\"`), a notifications `Button`, the user-menu `DropdownMenu`.",
+      "name": "end",
+      "type": "ReactNode"
+    },
+    {
+      "defaultValue": "\"scroll\"",
+      "description": "What a bar that does not fit does with the cells that do not fit (gh#728). scroll (default) lets the BAR scroll on the inline axis while the start and end clusters keep their cells whole — every cell stays in the DOM and in the accessibility tree, Tab reaches each one in order, and the browser scrolls a focused cell into view; the scrollbar is suppressed (a horizontal bar inside a 48px chrome row would eat the height that caused the deficit), so the pointer affordance is drag/wheel. clip is the pre-gh#728 behaviour: a cell past the cluster's edge is simply not painted — still focusable, still announced, invisible and unreachable by pointer. Independent of TopbarItem hideBelow, which REMOVES a cell at a step; this is only about what happens once there is no budget left.",
+      "name": "overflow",
+      "type": "\"scroll\" | \"clip\""
+    },
+    {
+      "defaultValue": "undefined",
+      "description": "Escape hatch — render fully custom bar content instead of the three slots. When set, `start`/`center`/`end` are ignored.",
+      "name": "children",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Merged onto the bar element; arbitrary props (aria-*, etc.) are forwarded.",
+      "name": "className",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "AppShell — place Topbar in its `topbar` slot. AppShell also exposes its own `logo`/`topbarLeft`/`topbarRight` slots if you don't want a separate Topbar at all.",
+    "Avatar — the brand mark for the `start` slot (use `shape=\"square\"` for a product glyph; never a `rounded-*` utility, which freezes the radius where no theme can reach it).",
+    "AppSettingPicker — locale/theme/timezone/currency picker; the consumer drops it into `end`. Its appearance (icon-only, labelled, bordered) is configured on IT, not on Topbar.",
+    "DropdownMenu — wrap a `Button` to build an entity switcher or user menu yourself, then place it in a slot."
+  ],
+  "rules": [
+    2,
+    3,
+    5,
+    6
+  ],
+  "storyPath": "layout/Topbar.stories.tsx",
+  "tagline": "A PURE SLOT bar for the app shell — positions three clusters (start / center / end) and owns ONLY the bar layout. It bakes NO chrome: no product switcher, no search box, no notification bell, no language picker. The CONSUMER composes those from real primitives and drops them into a slot; whether a control is icon-only / labelled / bordered is that control's own config, never the shell's.",
+  "usage": [
+    "DO compose the bar yourself: a brand mark (an `Avatar`) + sidebar toggle in `start`, a search trigger in `center`, settings pickers + notifications + user menu in `end`. The shell only positions; it never decides WHICH controls exist.",
+    "DO build the sidebar toggle as a `TopbarItem` with a `PanelLeftClose`/`PanelLeftOpen` icon and your own `t()` aria-label, wired to AppShell's `sidebarCollapsed`. There is no baked toggle — but there IS a bar CELL, and it is not a Button: a Button in a slot is a --control-height pill floating in a taller bar, with its own hover fill and a ring drawn around the pill instead of the cell. The same holds for the notifications bell and the account trigger.",
+    "DO put a locale/theme switcher in `end` using `AppSettingPicker` (or your own control) — icon-only vs labelled, bordered vs not, is THAT component's prop, not Topbar's. Topbar does not ship or force a language picker.",
+    "DON'T look for `product`/`project`/`onSearchOpen`/`onNotificationsOpen`/`collapsed` props — they were removed. A chrome control only exists if YOU put it in a slot, so there is never a dead dropdown / empty search with nothing behind it.",
+    "DO render Topbar inside `AppShell`'s `topbar` slot (or any `<header>`). For a non-three-cluster layout, pass `children` and lay it out yourself.",
+    "DO decide, explicitly, what happens to the `center` slot at 1100px and below. It is REMOVED there by default (`--topbar-center-compact-display: none`) so it cannot cover the start or end clusters when a 16rem sidebar is docked — which also means a global search trigger in `center` is gone on tablets AND phones. This default arrived in 18.6.0 and changed behaviour for consumers who touched nothing but their lockfile. If your center content already has a compact presentation (an icon-only search trigger), opt back in globally with `:root { --topbar-center-compact-display: flex; }`; if it does not, move the trigger into `end` for compact widths. Never re-create either behaviour with a page-local media query.",
+    "DO rely on the built-in shrink contract instead of hand-tuning widths: the bar never exceeds its shell allocation, `start` shrinks first and `center` yields its whole box, a long tenant/brand string truncates rather than spilling over a sibling or leaking a horizontal document scroll, and `end` keeps its natural width anchored inline-end — the locale picker and user menu stay visible at 1024px with a 16rem sidebar. If a label must degrade gracefully rather than be cut, give THAT element `truncate`/`text-overflow` yourself; don't add `overflow`/`flex` overrides to the slots.",
+    "KNOW what happens when the shrink contract runs out: the BAR scrolls (`overflow=\"scroll\"`, the default), it does not slice. The start cluster keeps a floor of one bar cell and the end cluster keeps its cells whole, so what does not fit is off-port rather than half-painted — Tab still reaches every cell and the browser scrolls the focused one fully into view. Measured at 320x568 on a bar 44px over budget: start cluster 0 -> 32px, end cluster clientWidth 150.3/scrollWidth 285 -> 204/204, last end cell x=384.8 (outside a 390px viewport) -> fully inside it, 7/7 cells reachable by keyboard. `overflow=\"clip\"` restores the pre-gh#728 slicing for a bar you have measured as never overflowing (gh#728).",
+    "KNOW the shrink contract reaches only the LAST child of `start` — and `Button` ships `shrink-0`, so any Button you put mid-slot (the classic entity switcher, with a brand mark before it and a screen title after) keeps its full width while the cluster clips it. Clipped, but still focusable: a keyboard user tabs to a control they cannot see (SC 2.4.7). Give such a control `fill` so it takes the leftover room and lets its label ellipse, and wrap that label in `<Text truncate>` — NOT `className=\"min-w-0 flex-1\"` plus a `truncate` span, which is the utility pair ui-audit blocks and which this guidance used to recommend. Budget the `end` cluster too — it is `flex: 0 1 auto` and shrink-weighted, but a cell in it is still a cell you chose to put on a phone: an ambient status chip there is space the start cluster does not get (a 93px environment Badge left `start` 25px of a 198px bar at 320). Hide ambient chips below `sm`."
+  ],
+  "useCases": [
+    "Admin shell: `start` = sidebar toggle + brand mark (`Avatar`) + an entity switcher (`DropdownMenu` around a `Button`); `center` = a `Button` search trigger; `end` = `AppSettingPicker` (locale) + a notifications `Button` + a user `DropdownMenu`.",
+    "Minimal shell (no search, no notifications): pass only `start` (brand mark) and `end` (user menu). Nothing else renders — no empty chrome.",
+    "Marketing / docs header: pass `children` with a fully custom flex layout when the three-cluster model doesn't fit."
+  ]
+}

package/agent/components/TopbarItem.json

@@ -0,0 +1,79 @@
+{
+  "example": "import { Topbar, TopbarItem } from \"@godxjp/ui/layout\";\nimport { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent } from \"@godxjp/ui/navigation\";\n\n<Topbar\n  end={\n    <DropdownMenu>\n      <DropdownMenuTrigger asChild>\n        <TopbarItem aria-label=\"Account\">\n          <Avatar><AvatarFallback>SD</AvatarFallback></Avatar>\n        </TopbarItem>\n      </DropdownMenuTrigger>\n      <DropdownMenuContent align=\"end\">…</DropdownMenuContent>\n    </DropdownMenu>\n  }\n/>",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "TopbarItem",
+  "props": [
+    {
+      "description": "The cell's leading glyph, placed in a slot the CELL sizes (--topbar-icon-size). Prefer it over passing the glyph as a child whenever the glyph is wrapped: `.ui-topbar-item > svg` only reaches a DIRECT child, so a glyph inside a `<Flex hideBelow>` renders at lucide's intrinsic 24px — measured at 390px on an org-switcher cell, 1.5x the cell's step (gh#712). Decorative by convention (the cell's name comes from its own aria-label); pass <Icon as={…} size=… label=… /> here when the glyph needs a name or a different step. Rendered with asChild too (gh#726): the sized slot is inserted INSIDE the child element, ahead of that element's own children, and the child element (e.g. an <a>) stays the rendered root with every merged prop.",
+      "name": "icon",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Drop the icon slot FROM a breakpoint step upwards (Flex hideFrom's contract, scoped to the glyph), so the cell reads label-only on a wide bar. Decorative: the accessible name is unaffected (gh#726).",
+      "name": "iconHideFrom",
+      "type": "BreakpointProp"
+    },
+    {
+      "description": "VISUALLY hide the label BELOW a breakpoint step (Flex hideBelow's contract, scoped to the label), so the cell collapses to icon-only on a narrow bar. The label stays in the accessibility tree (clipped, not display:none), so the icon-only cell keeps its accessible name. Under asChild the child element's own children are the label (gh#726).",
+      "name": "labelHideBelow",
+      "type": "BreakpointProp"
+    },
+    {
+      "description": "Overlaid count; does not change the bar cell width. Not rendered with asChild.",
+      "name": "badge",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Count tone, shared with Sidebar badges.",
+      "name": "badgeTone",
+      "type": "\"neutral\" | \"destructive\""
+    },
+    {
+      "description": "Hide the bar cell below a design-system breakpoint without interrupting its stretch chain.",
+      "name": "hideBelow",
+      "type": "BreakpointProp"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Render the bar-cell shape onto the child instead of emitting a <button> — for a router link, or a menu/popover trigger that must own the element.",
+      "name": "asChild",
+      "type": "boolean"
+    },
+    {
+      "description": "Cell content — a glyph, a label, an Avatar, or any pair of them.",
+      "name": "children",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Root class override.",
+      "name": "className",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "Topbar (the slot bar it belongs to)",
+    "Button (the right control everywhere that is not a bar)",
+    "AppShell (owns the bar height it stretches to)"
+  ],
+  "rules": [
+    2,
+    3,
+    5,
+    6
+  ],
+  "storyPath": "layout/TopbarItem.stories.tsx",
+  "tagline": "ONE interactive cell of a Topbar slot — the account button, a settings or notifications trigger. Full bar height, the bar's own hover surface, and the focus mark hosted INSIDE the cell. Use it INSTEAD OF a Button in a Topbar slot: a Button there is a --control-height pill floating in a taller bar, with its own hover fill and a ring drawn around the pill.",
+  "usage": [
+    "DO put bar triggers in a Topbar slot as TopbarItem, not as Button — that is the difference between chrome and a control that landed in the chrome.",
+    "DO wrap it in a DropdownMenuTrigger asChild for a user menu; the open state lights the cell via [data-state=open].",
+    "DON'T set a height: the cell stretches to whatever the bar is (AppShell's grid row, --topbar-height, or the coarse-pointer bar), which is why there is no height knob.",
+    "DO collapse a cell by breakpoint with its own props, never by hand-wrapping the glyph: `<TopbarItem asChild icon={<Target />} labelHideBelow=\"sm\"><a href=\"/goals\">Goals</a></TopbarItem>` replaces `<Flex hideFrom=\"sm\"><Icon as={Target} size=\"md\" /></Flex>` — icon-only below sm, the label still the accessible name. Add `iconHideFrom` for a label-only cell from a step up (gh#726).",
+    "DON'T reach for it outside a Topbar — a full-bleed cell needs a bar to bleed to. Use Button anywhere else."
+  ],
+  "useCases": [
+    "Account / user-menu trigger in the topbar end slot",
+    "Notifications bell, settings or theme trigger",
+    "Sidebar collapse toggle in the topbar start slot"
+  ]
+}

package/agent/components/Transfer.json

@@ -0,0 +1,141 @@
+{
+  "example": "import { useState } from \"react\";\nimport { Transfer } from \"@godxjp/ui/data-entry\";\n\nconst ALL_ACCOUNTS = [\n  { value: \"1010\", title: \"Cash\", description: \"Asset\" },\n  { value: \"1020\", title: \"Accounts Receivable\", description: \"Asset\" },\n  { value: \"2010\", title: \"Accounts Payable\", description: \"Liability\" },\n  { value: \"3010\", title: \"Revenue\", description: \"Income\" },\n  { value: \"4010\", title: \"Cost of Goods Sold\", description: \"Expense\", disabled: true },\n];\n\nexport function AccountMapping() {\n  const [targetKeys, setTargetKeys] = useState<string[]>([\"1010\"]);\n\n  return (\n    <Transfer\n      dataSource={ALL_ACCOUNTS}\n      targetKeys={targetKeys}\n      onValueChange={(nextKeys) => setTargetKeys(nextKeys)}\n      titles={[\"Available Accounts\", \"Mapped Accounts\"]}\n      showSearch\n    />\n  );\n}",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "Transfer",
+  "props": [
+    {
+      "description": "Canonical controlled target keys; takes precedence over targetKeys.",
+      "name": "value",
+      "type": "string[]"
+    },
+    {
+      "description": "Initial uncontrolled target keys.",
+      "name": "defaultValue",
+      "type": "string[]"
+    },
+    {
+      "description": "Compatibility name for uncontrolled initial target keys.",
+      "name": "defaultTargetKeys",
+      "type": "string[]"
+    },
+    {
+      "description": "Native form name; repeats once per target key.",
+      "name": "name",
+      "type": "string"
+    },
+    {
+      "description": "Preserve assignment while preventing edits.",
+      "name": "readOnly",
+      "type": "boolean"
+    },
+    {
+      "description": "Independent pane pages; select-all affects visible enabled rows.",
+      "name": "pagination",
+      "type": "boolean | { pageSize?: number }"
+    },
+    {
+      "description": "Show each pane select-all control; defaults true.",
+      "name": "showSelectAll",
+      "type": "boolean"
+    },
+    {
+      "description": "Custom search predicate.",
+      "name": "filterOption",
+      "type": "(query: string, item: TransferItemProp) => boolean"
+    },
+    {
+      "description": "Custom non-interactive row content; checkbox labels remain associated.",
+      "name": "render",
+      "type": "(item: TransferItemProp) => ReactNode"
+    },
+    {
+      "description": "Full flat list of all items (both source and target). Each item needs a unique `key` string, a `title` (ReactNode rendered in the list row), an optional `description` (shown as a secondary line), and an optional `disabled` boolean to lock individual items.",
+      "name": "dataSource",
+      "required": true,
+      "type": "TransferItemProp[]"
+    },
+    {
+      "description": "Keys of items currently in the right (target) panel. Items whose key is NOT in this array appear in the left (source) panel. This is the primary controlled state — you must update it inside `onChange`.",
+      "name": "targetKeys",
+      "required": true,
+      "type": "string[]"
+    },
+    {
+      "description": "Called after the user clicks a move button. Receives the new full targetKeys array, the direction of movement ('right' = source→target, 'left' = target→source), and the keys that were actually moved. Update your targetKeys state here.",
+      "name": "onChange",
+      "type": "(targetKeys: string[], direction: 'left' | 'right', moveKeys: string[]) => void"
+    },
+    {
+      "description": "Panel header labels. Index 0 = left/source panel, index 1 = right/target panel. Defaults to i18n strings (dataEntry.transfer.source / dataEntry.transfer.target).",
+      "name": "titles",
+      "type": "[React.ReactNode, React.ReactNode]"
+    },
+    {
+      "defaultValue": "false",
+      "description": "When true, renders a SearchInput inside each panel that filters items by title and description text (debounce=0). Does not affect the underlying data; purely a client-side filter.",
+      "name": "showSearch",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "When true, hides the left-pointing move button so items can only flow source → target. Useful for append-only assignment flows.",
+      "name": "oneWay",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Disables the entire component: all checkboxes, the search input (pointer-events-none), and both move buttons.",
+      "name": "disabled",
+      "type": "DisabledProp (boolean)"
+    },
+    {
+      "description": "Extra Tailwind classes applied to the outer flex wrapper. Use to constrain width or add margin.",
+      "name": "className",
+      "type": "string"
+    },
+    {
+      "description": "Controlled selection state as a tuple: index 0 = keys checked in the source panel, index 1 = keys checked in the target panel. Omit to use internal (uncontrolled) selection state. Must be paired with `onSelectChange` when provided.",
+      "name": "selectedKeys",
+      "type": "[string[], string[]]"
+    },
+    {
+      "description": "Called whenever the checked selection in either panel changes. Provides updated arrays for source and target selections. Required when `selectedKeys` is controlled.",
+      "name": "onSelectChange",
+      "type": "(sourceSelectedKeys: string[], targetSelectedKeys: string[]) => void"
+    },
+    {
+      "description": "Fires when items move between panels; you own `targetKeys` state.",
+      "name": "onValueChange",
+      "type": "(targetKeys: string[], direction: \"left\" | \"right\", moveKeys: string[]) => void"
+    }
+  ],
+  "related": [
+    "MultiSelect — picks multiple values from a dropdown; prefer when the option set is large and a panel layout is not needed.",
+    "Checkbox (list) — use for a simple flat multi-select without a shuttle/move metaphor.",
+    "Select (compound) — single or multi-value dropdown; not a dual-panel component.",
+    "Tree — hierarchical item display; combine with Transfer's dataSource if items have a tree structure but the shuttle UX is still needed."
+  ],
+  "rules": [
+    23,
+    31
+  ],
+  "storyPath": "data-entry/Transfer.stories.tsx",
+  "tagline": "Dual-list shuttle that moves items between source and target via Checkbox selection — you own targetKeys state; never hand-roll a two-panel picker.",
+  "usage": [
+    "DO own `targetKeys` in state and update it inside `onChange`: `const [targetKeys, setTargetKeys] = useState<string[]>([]); onValueChange={(next) => setTargetKeys(next)}`.",
+    "DO NOT hand-roll a two-panel checkbox picker — Transfer ships the full shuttle UX (select-all header, indeterminate state, search, move buttons, empty state) out of the box.",
+    "DO enable `showSearch` for lists longer than ~10 items; the built-in SearchInput filters by both `title` and `description` text content, including ReactNode content via `reactNodeText`.",
+    "DO use `oneWay={true}` for append-only flows (e.g. adding permissions to a role) where items must never be moved back.",
+    "DO control `selectedKeys` / `onSelectChange` only when you need to read which items are currently checked (e.g. for a bulk-action toolbar outside the component). For most cases, leave both props out and let Transfer manage selection internally.",
+    "AVOID using Transfer for simple single-select or toggle scenarios — use a Checkbox list or Select multiple instead. Transfer is specifically for shuttle/dual-panel assignment flows."
+  ],
+  "useCases": [
+    "Assigning roles or permissions to a user: source panel shows available roles, target panel shows assigned roles; `oneWay={false}` allows removal.",
+    "Building a report column picker: source = all available columns, target = columns included in the report, user orders and moves them across.",
+    "Account mapping in an accounting app: map external chart-of-accounts entries (source) to canonical internal accounts (target) in a bulk import wizard.",
+    "Tag / label assignment in a CMS: move content tags from an available pool into a 'selected' set for a document.",
+    "Feature-flag targeting: move user segments from an 'all segments' list into the 'targeted segments' panel for a flag.",
+    "Permission set builder in an admin UI: shuttle individual API scopes from 'available' to 'granted' for an API key or OAuth client."
+  ]
+}

package/agent/components/Tree.json

@@ -0,0 +1,185 @@
+{
+  "docPath": "docs/data-display/tree.tsx",
+  "example": "import * as React from \"react\";\nimport { Tree } from \"@godxjp/ui/data-display\";\n\nconst permissions = [\n  {\n    value: \"billing\",\n    label: \"Billing\",\n    children: [\n      { value: \"billing.invoice.read\", label: \"Read invoices\" },\n      { value: \"billing.invoice.write\", label: \"Issue invoices\" },\n    ],\n  },\n  {\n    value: \"people\",\n    label: \"People\",\n    children: [\n      { value: \"people.read\", label: \"Read profiles\" },\n      { value: \"people.write\", label: \"Edit profiles\", disabled: true },\n    ],\n  },\n];\n\nexport function PermissionTree() {\n  // The name is YOUR copy — run it through your app's own i18n, not the library's.\n  const [granted, setGranted] = React.useState<string[]>([\"billing.invoice.read\"]);\n\n  return (\n    <Tree\n      aria-label=\"Permissions\"\n      treeData={permissions}\n      checkable\n      defaultExpandAll\n      checkedValues={granted}\n      onCheckedValuesChange={setGranted}\n    />\n  );\n}",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "Tree",
+  "props": [
+    {
+      "description": "The hierarchy. Each node: `{ value: string; label: ReactNode; disabled?: boolean; disableCheckbox?: boolean; isLeaf?: boolean; icon?: ReactNode; children?: TreeNodeProp[] }`. Same node shape as TreeSelect/Cascader; use `fieldNames` to remap an API response instead of transforming it.",
+      "name": "treeData",
+      "required": true,
+      "type": "TreeNodeProp[]"
+    },
+    {
+      "description": "Remap the data's own key names, e.g. `{ label: 'name', value: 'id', children: 'items' }`.",
+      "name": "fieldNames",
+      "type": "{ label?: string; value?: string; children?: string }"
+    },
+    {
+      "description": "Controlled SELECTION (antd `selectedKeys`). `string` while single, `string[]` once `multiple` is on. Selection and checks are separate axes — do not use this for checkboxes.",
+      "name": "value",
+      "type": "string | string[]"
+    },
+    {
+      "description": "Initial selection for an uncontrolled tree. Ignored once `value` is passed.",
+      "name": "defaultValue",
+      "type": "string | string[]"
+    },
+    {
+      "description": "Selection change (antd `onSelect`). Emits `string | undefined` while single, `string[]` once `multiple` is on.",
+      "name": "onValueChange",
+      "type": "(value: string | string[] | undefined) => void"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Allow more than one selected node. Also sets `aria-multiselectable` on the tree.",
+      "name": "multiple",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Draw a checkbox on every node (antd `checkable`). Checking cascades to descendants and a parent shows `indeterminate` while only some are checked. With `checkable`, Enter/Space toggles the checkbox rather than selecting.",
+      "name": "checkable",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Parent and child checks are independent (antd `checkStrictly`) — no cascade and no indeterminate state.",
+      "name": "checkStrictly",
+      "type": "boolean"
+    },
+    {
+      "description": "Controlled checked nodes (antd `checkedKeys`).",
+      "name": "checkedValues",
+      "type": "string[]"
+    },
+    {
+      "description": "Initial checked nodes for an uncontrolled tree (antd `defaultCheckedKeys`).",
+      "name": "defaultCheckedValues",
+      "type": "string[]"
+    },
+    {
+      "description": "Checked-set change (antd `onCheck`). The array is normalised: a branch appears only when every tickable child is checked, so it can never claim a partial selection is complete.",
+      "name": "onCheckedValuesChange",
+      "type": "(values: string[]) => void"
+    },
+    {
+      "description": "Controlled expanded branches (antd `expandedKeys`).",
+      "name": "expandedValues",
+      "type": "string[]"
+    },
+    {
+      "description": "Initial expanded branches (antd `defaultExpandedKeys`).",
+      "name": "defaultExpandedValues",
+      "type": "string[]"
+    },
+    {
+      "description": "Expansion change (antd `onExpand`). Fires for controlled and uncontrolled trees.",
+      "name": "onExpandedValuesChange",
+      "type": "(values: string[]) => void"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Start with every branch open. Seeded once on mount, never re-applied.",
+      "name": "defaultExpandAll",
+      "type": "boolean"
+    },
+    {
+      "description": "Lazy children (antd `loadData`). Called ONCE per node the first time a branch with no `children` and `isLeaf !== true` is expanded; a Skeleton row and `aria-busy` cover the wait. Push the fetched children into `treeData`.",
+      "name": "loadData",
+      "type": "(node: TreeNodeProp) => void | Promise<void>"
+    },
+    {
+      "description": "Render a node's title yourself (antd `titleRender`).",
+      "name": "titleRender",
+      "type": "(node: TreeNodeProp) => ReactNode"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Draw the connector rails between a parent and its children (antd `showLine`). Off by default — a rail is chrome, and chrome defaults quiet.",
+      "name": "showLine",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Rule between the rows: a hairline on every node's block-start except the outline's first, so a tree used as navigation inside a Card reads as a list instead of one block (gh#732). The rule runs the FULL width of the row at every depth — never indented per level, which would make the children read as a nested table. Colour is `--tree-divider-color` (default `hsl(var(--border))`). Off by default, like `showLine` — chrome defaults quiet. Not antd's name: antd's Tree has no such capability, and `bordered` means a grid's frame plus column rules elsewhere in this library.",
+      "name": "divided",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Draw each node's `icon` (antd `showIcon`). `variant=\"directory\"` supplies folder/file glyphs when a node has no `icon` of its own.",
+      "name": "showIcon",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "\"default\"",
+      "description": "`directory` is antd's `<DirectoryTree>`: folder/file glyphs and a full-row selected band.",
+      "name": "variant",
+      "type": "\"default\" | \"directory\""
+    },
+    {
+      "defaultValue": "\"md\"",
+      "description": "Row height tier — the shared `--control-height` ladder, so rows stay in step with the controls beside them under every density.",
+      "name": "size",
+      "type": "\"xs\" | \"sm\" | \"md\" | \"lg\""
+    },
+    {
+      "defaultValue": "false",
+      "description": "Disable the whole tree: nothing selects, checks or expands, and the nodes stay readable.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "description": "Classes applied to the `role=\"tree\"` container.",
+      "name": "className",
+      "type": "string"
+    },
+    {
+      "description": "HTML id on the `role=\"tree\"` container.",
+      "name": "id",
+      "type": "string"
+    },
+    {
+      "description": "Accessible name of the tree. Required unless `aria-labelledby` names it from a visible heading.",
+      "name": "aria-label",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "TreeList — REMOVED in 21.0.0, replaced by Tree. It was a flat `<ul>` whose `depth` only drove `margin-inline-start`: it LOOKED like a tree and had no expand/collapse, no `role=\"tree\"`, no keyboard and no selection contract. Migration: nest the flat `items` into `treeData` (`id`→`value`, `title`→`label`, `depth`→nesting) and pass `aria-label`. A genuinely static indented outline that never opens is a `Descriptions` or a `ListRow` stack, not a tree.",
+    "TreeSelect — the same hierarchy INSIDE a Popover, as a form field. Use TreeSelect when the answer is a value in a form; use Tree when the hierarchy itself is the page.",
+    "Cascader — a path picker across columns. Use it when the user walks one path to a leaf; use Tree when several branches are open at once.",
+    "Accordion — single-level disclosure with rich panel content. It is not a hierarchy and has no tree keyboard model.",
+    "ScrollArea — wrap Tree in one to cap a long outline; Tree does not virtualise in v1."
+  ],
+  "rules": [
+    2,
+    6,
+    23,
+    31,
+    44,
+    45
+  ],
+  "storyPath": "data-display/Tree.stories.tsx",
+  "tagline": "The standalone WAI-ARIA tree view on a page (antd `Tree` / `DirectoryTree`) — nested `treeData`, a disclosure triangle per branch, roving-tabindex arrow navigation, optional tri-state checkboxes and async `loadData`. Reach for it whenever nodes expand, collapse or are navigated by keyboard; TreeSelect is the same hierarchy inside a Popover.",
+  "usage": [
+    "DO name the tree — pass `aria-label` (through your own `t()`) or `aria-labelledby`. A tree with no name is an unlabelled landmark for every screen reader user.",
+    "DO keep SELECTION and CHECKS apart: `value`/`onValueChange` is which node is open in the detail pane; `checkedValues`/`onCheckedValuesChange` is which nodes are ticked. They are two axes, exactly as in antd — never drive one from the other.",
+    "DO let the keyboard work: the tree ships the full APG contract (Up/Down through visible nodes, Right expands then descends, Left collapses then climbs, Home/End, Enter/Space, `*` to expand the current level, type-ahead). Do not add your own key handling on top.",
+    "DON'T nest a Button, Checkbox, Link or any focusable control inside a node label. A tree item owns exactly ONE tab stop; the disclosure triangle and the tick box are decorative glyphs for that reason. Put row actions in a sibling column outside the tree, or open a detail pane on selection.",
+    "DON'T hand-roll an indented `<ul>` (or a NavList / ListRow stack with a per-depth margin) for a hierarchy. A flat indented list only LOOKS like a tree: no expand/collapse, no `role=\"tree\"`, no keyboard model, no selection contract. `TreeList` was exactly that list and was REMOVED in 21.0.0 — Tree is what replaced it, and it is the one to reach for whenever nodes expand, collapse or are keyboard-navigated.",
+    "DO pass `divided` when the tree IS the navigation of a page — a wiki/document outline or a section index sitting in a `Card` (`Card` > `CardContent flush` > `Tree divided`). Without a rule the rows run together and the outline reads as one block; with it, it reads as the ruled list ListRow and Table already give a flat list. Retint it per theme with `--tree-divider-color`, never with a per-page utility class.",
+    "DO cap a long tree with `ScrollArea` — virtualisation is not in v1, so a 5,000-node tree renders 5,000 rows.",
+    "DO push fetched children into `treeData` from `loadData`; the tree calls it once per node and shows a Skeleton row until the data lands."
+  ],
+  "useCases": [
+    "A permission tree: modules → resources → actions with tri-state checkboxes, where ticking a module ticks everything under it and a partly-granted module shows the dash.",
+    "A category browser beside a detail pane — selecting a category loads its products, and the whole hierarchy stays navigable by keyboard.",
+    "An organisation chart / department picker on a settings page, where a branch's children are fetched on demand with `loadData`.",
+    "A file explorer (`variant=\"directory\"`, `showIcon`, `showLine`) where folders and files read differently and the selected row spans the width.",
+    "A chart-of-accounts outline that must expand and collapse — the case a flat indented list only ever looked like it handled.",
+    "A wiki / document page index used as the navigation of a screen, inside a Card: `divided` rules the rows so the outline reads as a list, and selection drives the reading pane."
+  ]
+}