@cueplusplus/ui 0.13.0

package/manifest/components/data-row.json

@@ -0,0 +1,222 @@
+{
+  "name": "DataRow",
+  "slug": "data-row",
+  "group": "instruments",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The dense interactive row, as one anatomy three surfaces share.\n\n`Ledger`, a grouped `Table` and `DataTree` are three drawings of the same row\nmodel, and this is the model: a marker, a label, a description, tags, a\nfigure, and a trailing action cluster that is only there when you are looking\nat the row. Composing them yourself — rather than passing a `columns` array —\nis what keeps the primitive domain-neutral: a corpus of skills and a rig of\nfixtures need the same six slots and completely different columns.\n\nThe slots are thin: each is a `<span>` with a `data-slot`, the type and\ntruncation rule for its column, and nothing else. They may be used inside a\n`DataTree` row and inside a `Table.Cell` too — `Table.Row` carries the same\n`group/data-row` name, so `DataRow.Actions` reveals in the table idiom\nwithout a second implementation.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Root",
+    "Marker",
+    "Label",
+    "Description",
+    "Tags",
+    "Meta",
+    "Actions"
+  ],
+  "parts": [
+    {
+      "name": "Root",
+      "usage": "DataRow.Root",
+      "description": "The row itself: a grid line of slots, hairline-separated from its neighbours.\n\nNot a `<button>`, which is the one decision everything else here follows\nfrom. A dense row carries its own controls — a copy button, a menu trigger, a\nlink to the thing it names — and no button may contain them. So the row is a\n`<div>` that earns its keyboard behaviour explicitly:\n`tabIndex`, Enter/Space, and a click reading that leaves nested controls and\nmodifier-clicked links alone (see `activateRowFromClick` in `_data-row.ts`).\n\nGeometry comes from the density row tokens and the column tracks from\n`--cue-data-row-cols`, which the caller sets — see `DATA_ROW_COLUMNS`. The\ncount of children must equal the count of tracks at every width: a template\none track short is exactly how the trailing action cluster ends up wrapped\nonto a phantom second row.\n\n**Tightening the controls inside a row** is a scoped custom-property retune,\nnot a prop. `IconButton`, `CopyButton` and `Avatar` at `size=\"sm\"` read\n`--cue-control-sm`, and `Chip` reads `--cue-chip-h`; redeclaring those two on\na wrapper around the list — `<div className=\"[--cue-control-sm:1.25rem] [--cue-chip-h:1rem]\">` —\nshrinks every control inside it and nothing outside it. A class on the button\ncannot do this: `size-control-sm` is a utility, and utilities are not shadowed\nby a rule with a longer selector. Custom properties inherit, which is what\nmakes them the only lever that reaches inside a component you did not write.",
+      "props": [
+        {
+          "name": "interactive",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "The row responds to a pointer and to the keyboard: hover wash, `cursor`,\nan inset focus ring and a tab stop. Defaults to `false`.",
+          "control": {
+            "kind": "boolean"
+          }
+        },
+        {
+          "name": "selected",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Draw the row as picked out of the list. Defaults to `false`.\n\nSets `data-selected`, which is also what the hover-revealed action track and\nthe accent tint key off — so a `<tr data-selected>` in the table idiom gets\nexactly the same treatment without going through this component.",
+          "control": {
+            "kind": "boolean"
+          }
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Grey the row out and stop it responding to anything. Defaults to `false`.",
+          "control": {
+            "kind": "boolean"
+          }
+        },
+        {
+          "name": "onActivate",
+          "type": "(() => void)",
+          "required": false,
+          "defaultValue": null,
+          "description": "What \"open this row\" means — a drawer, a detail pane, a route.",
+          "control": {
+            "kind": "callback",
+            "fixture": "callback.log"
+          }
+        },
+        {
+          "name": "disclosure",
+          "type": "DataRowDisclosure",
+          "required": false,
+          "defaultValue": null,
+          "description": "Expose the row as a disclosure: `data-expanded` always, `aria-expanded`\nwhen the row has a `role` that can carry it, and `aria-controls` when the\ndisclosed element is on the page.\n\n**`aria-expanded` is gated on the role, because on a bare `<div>` it is\nworse than nothing.** A role-less div maps to `generic`, which supports\nonly the global attributes — so the state is dropped outright by Blink,\nWebKit and Gecko alike (verified through Chromium's own accessibility\ntree), announces nothing, and adds a critical `aria-allowed-attr` finding\nto any axe run over the console that used it. `role` passes straight\nthrough as a div prop, so a row that genuinely is a disclosure says which\nkind it is — `role=\"button\"` for a row that opens a drawer, `role=\"row\"`\ninside a grid — and gets the attribute with it. Everything else gets\n`data-expanded`, which styles and tests exactly as well and promises\nnothing to a screen reader.\n\nThe row is still not given a widget role on its own account: a\n`role=\"button\"` row could not legally hold the buttons and links these rows\nexist to contain, and that judgement belongs to the caller who knows what\ntheir row does. Where the disclosure has to be bulletproof for assistive\ntechnology, reach for `DataTree` (real `treeitem` expansion) or a\n`Table.GroupRow` with a real toggle button in it.",
+          "control": {
+            "kind": "opaque"
+          }
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"div\">"
+      ]
+    },
+    {
+      "name": "Marker",
+      "usage": "DataRow.Marker",
+      "description": "The leading mark: a tick, a status dot, a kind glyph. Never the label.",
+      "props": [],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"span\">"
+      ]
+    },
+    {
+      "name": "Label",
+      "usage": "DataRow.Label",
+      "description": "The primary column: what the row *is*.\n\n`min-w-0 truncate` rather than a wrap, because a dense list is scanned down a\ncolumn: one row that grew to two lines breaks the scan for every row after it.",
+      "props": [],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"span\">"
+      ]
+    },
+    {
+      "name": "Description",
+      "usage": "DataRow.Description",
+      "description": "The secondary column: the sentence under the name, one line, muted.",
+      "props": [],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"span\">"
+      ]
+    },
+    {
+      "name": "Tags",
+      "usage": "DataRow.Tags",
+      "description": "A run of `Chip`s or other marks, kept on one line and allowed to clip.",
+      "props": [],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"span\">"
+      ]
+    },
+    {
+      "name": "Meta",
+      "usage": "DataRow.Meta",
+      "description": "The figure column: a count, a version, a duration.\n\n`tabular-nums` for the same reason every other figure in this library is set\nthat way — a changing digit must not shift the column under the reader.",
+      "props": [],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"span\">"
+      ]
+    },
+    {
+      "name": "Actions",
+      "usage": "DataRow.Actions",
+      "description": "The trailing controls, revealed on hover, on focus and on selection.\n\nThree mechanisms, each guarding a specific failure:\n\n- **`invisible`, not `hidden`.** `visibility` keeps the cluster's box, so the\n  track it sits in is the same width at rest as it is revealed and nothing\n  in the row moves when the pointer arrives. `display: none` frees the space\n  and every column to its left slides on hover.\n- **`focus-within` reveals it too, and the row's own focus is what triggers\n  it.** `:focus-within` matches the element that *has* focus as well as one\n  that contains it, and that ordering is what keeps these controls reachable\n  at all: content inside a `visibility: hidden` subtree is not focusable, so\n  Tab could never enter a track that only appeared once something inside it\n  was focused. The row takes focus, the track appears, and Tab walks into it.\n  (Which is also why an interactive row is the shape to use when the row has\n  actions: on a static row nothing takes focus first.)\n- **`@media (hover: none)` shows it outright.** On a touch screen there is no\n  hover to reveal anything with, so the cluster is simply always there. This\n  is the `hover: none` query rather than `pointer: coarse` on purpose: what\n  the reveal depends on is hovering, not the pointer's precision, and a\n  trackpad-and-touchscreen laptop has both.\n\n**The host has to supply the focus, and not every host does.** Because the\ntrack cannot be entered until something outside it takes focus, a row with no\nfocusable element outside the cluster puts these controls beyond a keyboard\nuser entirely — visible to a mouse, unreachable by Tab, WCAG 2.1.1. An\ninteractive `DataRow.Root` and a `DataTree` `treeitem` are focusable rows and\nsatisfy this on their own; a `<tr>` is not, so a `Table.Row` holding this\ncluster needs a real focusable element of its own in another cell — the row's\nname as a link is the usual one, and `Table.Row`'s own note says so too.\n\n`data-stop` is the row's opt-out marker: a click anywhere inside this cluster\nnever opens the row (see `activateRowFromClick` in `_data-row.ts`).",
+      "props": [],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"span\">"
+      ]
+    }
+  ],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-data-row-cols",
+    "--cue-data-tree-indent",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-hair",
+    "--cue-pad-row-x",
+    "--cue-pad-row-y",
+    "--cue-row-hover",
+    "--cue-space-1",
+    "--cue-space-3",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "The dense list row: six slots, a hover-revealed action track, and columns the caller declares.",
+  "examples": [
+    {
+      "title": "Declaring the tracks",
+      "code": "<Ledger.Root className=\"[--cue-data-row-cols:1.5rem_minmax(8rem,1fr)_6rem_auto]\">\n  <DataRow.Root interactive onActivate={() => open(device)}>\n    <DataRow.Marker>\n      <StatusDot tone=\"ok\" />\n    </DataRow.Marker>\n    <DataRow.Label>{device.name}</DataRow.Label>\n    <DataRow.Meta>{device.latency}</DataRow.Meta>\n    <DataRow.Actions>\n      <CopyButton value={device.id} size=\"sm\" className=\"w-control-sm px-0\" />\n      <IconButton icon={MoreVertical} size=\"sm\" aria-label={`Actions for ${device.name}`} />\n    </DataRow.Actions>\n  </DataRow.Root>\n</Ledger.Root>",
+      "language": "tsx"
+    },
+    {
+      "title": "The container, named",
+      "code": "<Ledger.Root className=\"patch [container-name:patch]\">…</Ledger.Root>",
+      "language": "tsx"
+    },
+    {
+      "title": "corpus.css",
+      "code": "@container patch (max-width: 46rem) {\n  .patch [data-slot=\"data-row\"] {\n    --cue-data-row-cols: 1.5rem minmax(8rem, 1fr) auto;\n  }\n  .patch [data-slot=\"data-row-description\"] {\n    display: none;\n  }\n}",
+      "language": "css"
+    },
+    {
+      "title": "The same decision, on a table row",
+      "code": "import { activateRowFromClick, activateRowFromKeyDown } from \"@cueplusplus/ui\";\n\n<Table.Row\n  interactive\n  tabIndex={0}\n  onClick={(event) => activateRowFromClick(event, () => open(device))}\n  onKeyDown={(event) => activateRowFromKeyDown(event, () => open(device))}\n>",
+      "language": "tsx"
+    },
+    {
+      "title": "A density island for the list, not for the app",
+      "code": "<div className=\"[--cue-chip-h:1rem] [--cue-control-sm:1.25rem]\">\n  <Ledger.Root>…</Ledger.Root>\n</div>",
+      "language": "tsx"
+    },
+    {
+      "title": "Usage",
+      "code": "<DataRow.Root interactive onActivate={() => open(skill)}>\n  <DataRow.Marker><StatusDot tone=\"ok\" /></DataRow.Marker>\n  <DataRow.Label>{skill.name}</DataRow.Label>\n  <DataRow.Meta>{skill.installs}</DataRow.Meta>\n</DataRow.Root>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/data-row",
+  "mdUrl": "/docs/components/data-row.md",
+  "jsonUrl": "/r/components/data-row.json",
+  "whenToUse": [
+    "A list of hundreds of records that is scanned down a column and opened one at a time — a corpus, a patch, a run log.",
+    "Any row that has to look identical in a `Ledger`, a grouped `Table` and a `DataTree`, because all three draw this anatomy."
+  ],
+  "whenNotToUse": [
+    "A panel's label-and-value lines. Use `Row`, which is a real `<button>` when it acts and needs no column tracks.",
+    "One object's fields. Use `DescriptionList`.",
+    "A row whose only job is to run one action. Use a `Button` — this row exists because rows contain controls, and a row that has just one should be the control."
+  ],
+  "commonMistakes": [
+    "Rendering more children than the tracks in `--cue-data-row-cols`. The extra child wraps onto a phantom second row, which is what the count rule exists to prevent.",
+    "Shedding a column by branching `className` in JSX. A utility outranks the `@container` rule meant to hide it, so the child survives while the template loses its track — declare the shed child's `display` in the stylesheet that changes the template.",
+    "Putting a `@container` rule's subject on `Ledger.Root` itself. It is the size container, and nothing is its own container — that rule never matches, while the `display: none` rule on the slots inside does, so the row sheds a child and keeps its track. Target a descendant: `.patch [data-slot=\"data-row\"]`.",
+    "Shrinking the controls inside rows with `h-5 w-5` on each button. Redeclare `--cue-control-sm` and `--cue-chip-h` on a wrapper instead; custom properties inherit and reach inside components you did not write.",
+    "Wrapping the row in a `<button>` or giving it `role=\"button\"` to get keyboard behaviour. It already has Enter and Space, and a button may not contain the row's own buttons and links."
+  ],
+  "specimens": [
+    {
+      "title": "DataRow",
+      "group": "instruments",
+      "components": [
+        "DataRow"
+      ],
+      "code": "<Panel className={`w-full ${PATCH_TRACKS}`}>\n  {PATCH_DEVICES.slice(0, 3).map((device, index) => (\n    <DataRow.Root key={device.id} interactive selected={index === 1}>\n      <PatchRowSlots device={device} />\n    </DataRow.Root>\n  ))}\n  <DataRow.Root disabled>\n    <PatchRowSlots device={{ ...PATCH_DEVICES[4], name: \"Offline monitor\" }} />\n  </DataRow.Root>\n</Panel>",
+      "note": "The row anatomy on its own: a marker, a name, a sentence, a figure and a trailing action track. The column tracks are the caller's, set as `--cue-data-row-cols` — the primitive never knows the dataset.",
+      "interaction": "hover, focus-within and selection each reveal the action track; it is hidden with `visibility`, so revealing it moves nothing else in the row. On a touch screen it is simply always there."
+    }
+  ]
+}

package/manifest/components/data-table-pagination.json

@@ -0,0 +1,97 @@
+{
+  "name": "DataTablePagination",
+  "slug": "data-table-pagination",
+  "group": "instruments",
+  "importPath": "@cueplusplus/ui/instruments/data-table",
+  "peerDependencies": [
+    "@tanstack/react-table"
+  ],
+  "clientOnly": true,
+  "description": "The pager: four buttons, the position, and the row count.\n\nFirst and last are present because a console table is often sorted to put the\ninteresting row at one end, and stepping there one page at a time is not a\nnavigation strategy. Every button is an `IconButton` with a real accessible\nname — an arrow glyph alone announces as nothing.",
+  "props": [
+    {
+      "name": "table",
+      "type": "DataTablePager",
+      "required": true,
+      "defaultValue": null,
+      "description": "The table instance from {@link useCueTable}, or anything with the same seven members.",
+      "control": {
+        "kind": "opaque"
+      }
+    },
+    {
+      "name": "labels",
+      "type": "Partial<DataTablePaginationLabels>",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible names for the four buttons.",
+      "control": {
+        "kind": "opaque"
+      }
+    },
+    {
+      "name": "formatPosition",
+      "type": "((page: number, pages: number) => string)",
+      "required": false,
+      "defaultValue": "(page, pages) => `${page} / ${pages}`",
+      "description": "Render the position readout. Defaults to `\"2 / 7\"`.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "formatRowCount",
+      "type": "((rows: number) => string)",
+      "required": false,
+      "defaultValue": "(rows) => `${rows} row${rows === 1 ? \"\" : \"s\"}`",
+      "description": "Render the row count. Defaults to `\"340 rows\"`.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-text-label"
+  ],
+  "summary": "The pager: four buttons, the position, and the row count.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<DataTablePagination table={table} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/data-table-pagination",
+  "mdUrl": "/docs/components/data-table-pagination.md",
+  "jsonUrl": "/r/components/data-table-pagination.json",
+  "specimens": [
+    {
+      "title": "DataTable recipe",
+      "group": "instruments",
+      "components": [
+        "DataTableToolbar",
+        "DataTablePagination"
+      ],
+      "code": "<FixtureTable />",
+      "note": "Not a component: `useCueTable` wires four TanStack v9 features, `DataTableToolbar` and `DataTablePagination` supply the chrome, and the markup stays at the call site. Rendered through the same Table above.",
+      "interaction": "the header cells are buttons that toggle sorting; the pager disables at the ends rather than hiding."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/data-table-toolbar.json

@@ -0,0 +1,127 @@
+{
+  "name": "DataTableToolbar",
+  "slug": "data-table-toolbar",
+  "group": "instruments",
+  "importPath": "@cueplusplus/ui/instruments/data-table",
+  "peerDependencies": [
+    "@tanstack/react-table"
+  ],
+  "clientOnly": true,
+  "description": "The strip above a table: one search box, a match count, your controls.\n\nThe count is the part worth having as a component. \"12/340\" next to a filter\nbox is the difference between \"the table is empty\" and \"the filter is too\ntight\", and it is the first thing left out of a hand-rolled toolbar.",
+  "props": [
+    {
+      "name": "value",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "The current query. Pair it with `onValueChange` and the table's global filter.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "onValueChange",
+      "type": "((value: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Fired on every keystroke in the search box.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "placeholder",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Filter…",
+      "description": "Placeholder for the search box. Defaults to `\"Filter…\"`.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "searchLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Filter rows",
+      "description": "Accessible name for the search box. Defaults to `\"Filter rows\"`.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "count",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Rows currently matching. Shown as `count/total` when both are given.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "total",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Rows before filtering.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Trailing controls — a column picker, an export button.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"onChange\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-text-label"
+  ],
+  "summary": "The strip above a table: one search box, a match count, your controls.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<DataTableToolbar value={q} onValueChange={setQ} count={table.getRowCount()} total={data.length}>\n  <Button variant=\"ghost\" size=\"sm\">Export</Button>\n</DataTableToolbar>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/data-table-toolbar",
+  "mdUrl": "/docs/components/data-table-toolbar.md",
+  "jsonUrl": "/r/components/data-table-toolbar.json",
+  "specimens": [
+    {
+      "title": "DataTable recipe",
+      "group": "instruments",
+      "components": [
+        "DataTableToolbar",
+        "DataTablePagination"
+      ],
+      "code": "<FixtureTable />",
+      "note": "Not a component: `useCueTable` wires four TanStack v9 features, `DataTableToolbar` and `DataTablePagination` supply the chrome, and the markup stays at the call site. Rendered through the same Table above.",
+      "interaction": "the header cells are buttons that toggle sorting; the pager disables at the ends rather than hiding."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/data-tree.json

@@ -0,0 +1,185 @@
+{
+  "name": "DataTree",
+  "slug": "data-tree",
+  "group": "instruments",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A hierarchy of multi-column rows: the tree idiom over the `DataRow` anatomy.\n\n## The ARIA pattern, chosen before the component was written\n\n`role=\"treegrid\"` is **rejected** for this foundation. It is the semantically\nexact answer — tabular *and* hierarchical — and it is the one with the worst\nreal-world assistive-technology record: Adrian Roselli's survey of expando\ntables calls its support poor and notes that the APG's own worked example\ncarries unresolved issues; fancytree's maintainer describes treegrid support\nas unproven ground; MUI X shipped hierarchical rows with no `aria-level` /\n`aria-expanded` / `aria-setsize` at all and retrofitted them later. Treegrid\nearns its cost when cells are individually interactive or editable, because\nthen a reader genuinely needs two-dimensional cell navigation. This surface is\nread-and-navigate: you move down rows, fold a branch, and open the thing a row\nnames.\n\nSo the pattern is `role=\"tree\"` with `role=\"treeitem\"` rows — VS Code's\nchoice and Carbon's, and the best-supported composite pattern in ARIA:\n\n- A **flat DOM** with `aria-level` / `aria-posinset` / `aria-setsize` per row\n  rather than nested `role=\"group\"` wrappers.\n- **Roving tabindex**: the tree is one Tab stop and the arrows move inside it.\n- The **APG tree keyboard map**: Up/Down between visible rows, Home/End to the\n  ends, Right to unfold then to descend, Left to fold then to ascend,\n  Enter/Space to select.\n- Expansion lives on the **row**, as `aria-expanded` on the `treeitem` — that\n  is what tree semantics mean by a parent, and it is why the chevron here is\n  `role=\"presentation\"` rather than a button. (The other half of this trade\n  is `Table.GroupRow`, where the table's semantics own the grouping and a real\n  `<button aria-expanded>` owns the disclosure. Two patterns, each internally\n  consistent; what would be wrong is half of each.)\n\n**The documented trade**: columns are not independently navigable. A row's\nmulti-column content lives *inside* the treeitem, so a screen-reader user\nhears the row as one string rather than moving cell to cell through it. For a\ndense browse-and-open surface that is the better bargain — `tree` works today\non every screen reader, `treegrid` does not — but a surface whose cells are\ngenuinely editable has outgrown this component and wants a real treegrid from\na library that maintains one.\n\n## Everything else\n\nRows are the `DataRow` chassis: same padding, same hairline, same hover wash,\nsame inset focus ring, same `group/data-row`, so `DataRow.Actions` reveals in\na tree exactly as it does in a ledger. The row element itself is the\ntreeitem — one element owns focus, expansion, selection and the click reading\n— and the caller's `DataRow.*` slots are its content.\n\nA tree whose items declare no children anywhere is a flat list: no chevrons,\nno spacer column where a chevron would be, no guides, and `aria-expanded` on\nnothing. A leaf row that carried `aria-expanded=\"false\"` would tell a screen\nreader it has children it does not have.",
+  "props": [
+    {
+      "name": "items",
+      "type": "readonly DataTreeItem[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The roots, in display order.",
+      "control": {
+        "kind": "array"
+      }
+    },
+    {
+      "name": "expanded",
+      "type": "readonly string[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "Expanded ids when controlled. Pass with `onExpandedChange`.",
+      "control": {
+        "kind": "array",
+        "fixture": "agent.transcript"
+      }
+    },
+    {
+      "name": "defaultExpanded",
+      "type": "readonly string[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "Initially expanded ids when uncontrolled.",
+      "control": {
+        "kind": "array",
+        "fixture": "agent.transcript"
+      }
+    },
+    {
+      "name": "onExpandedChange",
+      "type": "((expanded: string[]) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the whole next expanded set whenever a row is folded or unfolded.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "selected",
+      "type": "string | null",
+      "required": false,
+      "defaultValue": null,
+      "description": "Selected id when controlled. Pass with `onSelect`.",
+      "control": {
+        "kind": "string",
+        "nullable": true
+      }
+    },
+    {
+      "name": "defaultSelected",
+      "type": "string | null",
+      "required": false,
+      "defaultValue": "null",
+      "description": "Initially selected id when uncontrolled.",
+      "control": {
+        "kind": "string",
+        "nullable": true
+      }
+    },
+    {
+      "name": "onSelect",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the id of the row the user selected.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "guides",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Draw the depth guides. Defaults to `true`.\n\nRoots never draw one — there is no ancestor to draw — so a flat tree draws\nnone at all whatever this is set to.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the tree. Required in practice — name what it lists.",
+      "control": {
+        "kind": "string"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"onSelect\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-data-row-cols",
+    "--cue-data-tree-indent",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-hair",
+    "--cue-icon-sm",
+    "--cue-pad-row-x",
+    "--cue-pad-row-y",
+    "--cue-row-hover",
+    "--cue-space-3",
+    "--cue-text-ui"
+  ],
+  "summary": "A hierarchy of multi-column rows under real `role=\"tree\"` semantics, with CSS depth guides.",
+  "examples": [
+    {
+      "title": "Items carry rows, not labels",
+      "code": "const items: DataTreeItem[] = groups.map((group) => ({\n  id: group.id,\n  row: <DataRow.Label>{group.label}</DataRow.Label>,\n  children: group.rows.map((device) => ({\n    id: device.id,\n    row: (\n      <>\n        <DataRow.Label>{device.name}</DataRow.Label>\n        <DataRow.Meta>{device.latency}</DataRow.Meta>\n      </>\n    ),\n  })),\n}));\n\n<DataTree\n  aria-label=\"Patch\"\n  className=\"[--cue-data-row-cols:1fr_6rem]\"\n  items={items}\n  defaultExpanded={[\"inputs\"]}\n  selected={selected}\n  onSelect={setSelected}\n/>;",
+      "language": "tsx"
+    },
+    {
+      "title": "The container, named",
+      "code": "<div className=\"patch [container-type:inline-size] [container-name:patch]\">\n  <DataTree … />\n</div>",
+      "language": "tsx"
+    },
+    {
+      "title": "Narrow the step before you drop the guides",
+      "code": "@container patch (max-width: 32rem) {\n  .patch [data-slot=\"data-tree\"] {\n    --cue-data-tree-indent: 0.75rem;\n  }\n}",
+      "language": "css"
+    },
+    {
+      "title": "Usage",
+      "code": "<DataTree\n  aria-label=\"Patch\"\n  items={nodes}\n  defaultExpanded={[\"inputs\"]}\n  selected={selected}\n  onSelect={setSelected}\n  className=\"[--cue-data-row-cols:1fr_8rem_auto]\"\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/data-tree",
+  "mdUrl": "/docs/components/data-tree.md",
+  "jsonUrl": "/r/components/data-tree.json",
+  "whenToUse": [
+    "A grouped list the reader folds and unfolds, where each row still carries columns — a patch by bus, a corpus by stack, a plan by phase.",
+    "A hierarchy that has to keep working for a screen-reader user today: this is the `tree` pattern, which is the best-supported composite pattern in ARIA."
+  ],
+  "whenNotToUse": [
+    "A single-column outline of labels with a glyph gutter. Use `Tree`, which is that component.",
+    "A grouped list nobody folds. Use `Ledger` or a grouped `Table`; disclosure semantics you never use are a promise you never keep.",
+    "A grouped document whose *headings* fold, where the `h2`/`h3` outline has to survive. Use `Ledger` with `collapsible`: a tree makes every tier and subgroup a `treeitem` row and leaves no headings behind.",
+    "A grid whose cells are individually editable. That needs a real `treegrid` from a library that maintains one — this component trades cell navigation away on purpose."
+  ],
+  "commonMistakes": [
+    "Expecting cell-by-cell arrow navigation. Columns live inside the treeitem, so a row is announced as one string; that is the documented trade for the support `tree` has and `treegrid` does not.",
+    "Giving a leaf `children: []` to make it look like the others. An empty array *is* a parent — an empty folder — and it will carry `aria-expanded`.",
+    "Passing `expanded` without `onExpandedChange`, which freezes the tree: controlled means the caller owns the next state.",
+    "Fighting the guides with a row background. They are a `background-image` and survive hover and selection fills by design; switch them off with `guides={false}` instead."
+  ],
+  "specimens": [
+    {
+      "title": "DataTree",
+      "group": "instruments",
+      "components": [
+        "DataTree"
+      ],
+      "code": "<Panel className={`w-full ${PATCH_TRACKS}`}>\n  <DataTree\n    aria-label=\"Patch\"\n    items={PATCH_TREE}\n    defaultExpanded={[\"inputs\"]}\n    defaultSelected=\"scarlett\"\n  />\n</Panel>",
+      "note": "The same rows as a hierarchy: `role='tree'` with `treeitem` rows, chosen over `treegrid` for the support it actually has. Guides are a background gradient keyed off the row's depth, so a hover or selection fill cannot cover them.",
+      "interaction": "one tab stop: arrows move between rows, Right unfolds then descends, Left folds then climbs, Enter selects."
+    }
+  ]
+}