@cueplusplus/ui 0.6.0 → 0.8.0

package/dist/instruments/ledger.js

@@ -1,4 +1,6 @@
 import { cn } from "../lib/cn.js";
+import { headingTag } from "./_ledger.js";
+import { LedgerDisclosure } from "./_ledger-disclosure.js";
 import * as React from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 //#region src/instruments/ledger.tsx
@@ -12,24 +14,68 @@ import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 * micro-label in a dense list reads as a second kind of emphasis.
 */
 const LEDGER_LABEL = "font-mono text-(length:--cue-text-label) font-normal tracking-[0.15em] text-fg-subtle uppercase";
-/** `headingLevel` as a tag name, so the outline is real elements, not roles. */
-const headingTag = (level) => level === 2 ? "h2" : level === 3 ? "h3" : "h4";
+/**
+* The disclosure button a collapsible heading holds.
+*
+* Worn *with* {@link LEDGER_LABEL}, which the heading around it is already
+* wearing. The repetition is deliberate: a `<button>` carries the UA's own font
+* rather than its parent's, and while Tailwind's preflight resets that to
+* `font: inherit`, a component whose micro-label silently becomes 13px Arial if
+* a consumer drops preflight is a component with a very confusing bug report.
+* One constant applied twice cannot drift; two recipes can.
+*
+* `w-full` so the whole width of the heading is the hit area rather than the
+* word itself, and the focus ring is inset (`-outline-offset-2`) for the same
+* reason `_data-row.ts` gives: these headings dock at the top of clipped panes,
+* where an outset ring on the first one is cut off by the pane's own rim.
+*/
+const LEDGER_TOGGLE = "flex w-full min-w-0 cursor-pointer items-baseline gap-(--cue-space-2) text-left outline-none focus-visible:outline-2 focus-visible:outline-solid focus-visible:-outline-offset-2 focus-visible:outline-accent";
 /**
 * A grouped run of dense rows under sticky headings: the ledger idiom.
 *
-* The flattest of the three surfaces this package ships over one row model, and
-* the one that does the least: headings, slugs, rows. **Nothing here collapses.**
-* A ledger with a disclosure on it would be a tree with worse semantics, so the
-* component emits no `aria-expanded` anywhere, and a test holds it to that —
-* collapse belongs to `DataTree`, and grouping-with-columns belongs to a
-* grouped `Table`.
+* The flattest of the three surfaces this package ships over one row model:
+* headings, slugs, rows. What it owns above all is the document outline. Tiers
+* and groups are real `<h2>` / `<h3>` elements at caller-chosen levels, because
+* in a list of two hundred rows the heading list *is* how a screen-reader user
+* navigates.
+*
+* ## Folding: the accordion pattern, opt-in, and why it lives here
+*
+* This component used to refuse disclosure outright, on the grounds that *a
+* ledger which folds is a tree with worse semantics*. That ruling was right
+* about rows and wrong about places, and the distinction is the whole of
+* {@link LedgerTierProps.collapsible}:
 *
-* What it does own is the document outline. Tiers and groups are real `<h2>` /
-* `<h3>` elements at caller-chosen levels, because in a list of two hundred
-* rows the heading list *is* how a screen-reader user navigates.
+* - **`DataTree` folds a row.** Its `role="treeitem"` rows carry their own
+*   `aria-expanded`, its chevron is `role="presentation"` because in tree
+*   semantics the row owns its expansion, and a tier and a subgroup drawn
+*   through it stop being places and become rows. A consumer who measured this
+*   exact shape through `DataTree` counted **zero** `h2`/`h3` elements and zero
+*   `button[aria-expanded]`, which is `DataTree` working correctly and still
+*   not being what a grouped document needs.
+* - **`Ledger` folds a place.** A tier is already an `<h2>`, which is already
+*   the right element for it, so the disclosure goes *inside* the heading as a
+*   real `<button aria-expanded aria-controls>` — the accordion pattern, and
+*   the same one `Table.GroupRow`'s note has always pointed at for a table that
+*   genuinely needs to fold. The outline is untouched: the heading list of a
+*   folding ledger and a plain one are identical, which is what lets a page
+*   offer both idioms over one dataset without the outline moving under a
+*   reader who switches.
 *
-* Static markup — no `"use client"`. The rows inside it may be anything;
-* `DataRow` is the intended tenant.
+* So it is one component with two forms rather than a `DisclosureLedger` beside
+* it: everything a folding ledger needs — the gutter track, the sticky offsets,
+* the label recipe, the type contract — is this component, and a sibling would
+* have been a copy of all of it wrapped around one `<button>`.
+*
+* Expansion is controllable and stores nothing. *Which* places a reader has
+* folded is a fact about the reader; consumers keep that set themselves and
+* pass it back in. A folded run of rows is hidden rather than unmounted, so a
+* group that keeps its own fold inside a tier still keeps it after the tier has
+* been shut and opened over it.
+*
+* Static markup — no `"use client"` — **until a heading is asked to fold**, at
+* which point that heading and its rows become a small client island and the
+* rest of the ledger keeps rendering on the server.
 *
 * @example
 * <Ledger.Root className="[--cue-data-row-cols:1fr_8rem_auto]">
@@ -42,6 +88,18 @@ const headingTag = (level) => level === 2 ? "h2" : level === 3 ? "h3" : "h4";
 *     </Ledger.Group>
 *   </Ledger.Tier>
 * </Ledger.Root>
+*
+* @example
+* // Folded places are the reader's, so the reader's storage holds them.
+* <Ledger.Tier
+*   heading="Ours"
+*   count={13}
+*   collapsible
+*   expanded={!folded.includes("ours")}
+*   onExpandedChange={(open) => remember("ours", open)}
+* >
+*   <Ledger.Group label="released">…</Ledger.Group>
+* </Ledger.Tier>
 */
 const Ledger = {
 	Root: React.forwardRef(function LedgerRoot({ className, containment = true, ...elementProps }, ref) {
@@ -52,53 +110,85 @@ const Ledger = {
 			...elementProps
 		});
 	}),
-	Tier: React.forwardRef(function LedgerTier({ className, heading, count, sticky = true, headingLevel = 2, note, children, ...elementProps }, ref) {
+	Tier: React.forwardRef(function LedgerTier({ className, heading, count, sticky = true, headingLevel = 2, note, collapsible = false, expanded, defaultExpanded = true, onExpandedChange, children, ...elementProps }, ref) {
 		const Heading = headingTag(headingLevel);
-		return /* @__PURE__ */ jsxs("section", {
+		const words = /* @__PURE__ */ jsxs(Fragment, { children: [
+			/* @__PURE__ */ jsx("span", {
+				"data-slot": "ledger-tier-label",
+				children: heading
+			}),
+			count === void 0 ? null : /* @__PURE__ */ jsx("span", {
+				"data-slot": "ledger-tier-count",
+				className: "tabular-nums",
+				children: count
+			}),
+			note === void 0 ? null : /* @__PURE__ */ jsx("span", {
+				"data-slot": "ledger-tier-note",
+				className: "tracking-normal normal-case",
+				children: note
+			})
+		] });
+		const ground = sticky ? "sticky top-0 z-2 bg-bg" : null;
+		return /* @__PURE__ */ jsx("section", {
 			ref,
 			"data-slot": "ledger-tier",
 			className: cn("flex flex-col", className),
 			...elementProps,
-			children: [heading === void 0 ? null : /* @__PURE__ */ jsxs(Heading, {
+			children: heading === void 0 ? children : collapsible ? /* @__PURE__ */ jsx(LedgerDisclosure, {
+				headingLevel,
+				headingSlot: "ledger-tier-heading",
+				headingClassName: cn(LEDGER_LABEL, "py-(--cue-pad-row-y)", ground),
+				toggleSlot: "ledger-tier-toggle",
+				toggleClassName: cn(LEDGER_LABEL, LEDGER_TOGGLE),
+				panelSlot: "ledger-tier-rows",
+				panelClassName: "flex flex-col",
+				label: words,
+				expanded,
+				defaultExpanded,
+				onExpandedChange,
+				children
+			}) : /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(Heading, {
 				"data-slot": "ledger-tier-heading",
-				className: cn(LEDGER_LABEL, "flex items-baseline gap-(--cue-space-2) py-(--cue-pad-row-y)", sticky ? "sticky top-0 z-2 bg-bg" : null),
-				children: [
-					/* @__PURE__ */ jsx("span", {
-						"data-slot": "ledger-tier-label",
-						children: heading
-					}),
-					count === void 0 ? null : /* @__PURE__ */ jsx("span", {
-						"data-slot": "ledger-tier-count",
-						className: "tabular-nums",
-						children: count
-					}),
-					note === void 0 ? null : /* @__PURE__ */ jsx("span", {
-						"data-slot": "ledger-tier-note",
-						className: "tracking-normal normal-case",
-						children: note
-					})
-				]
-			}), children]
+				className: cn(LEDGER_LABEL, "flex items-baseline gap-(--cue-space-2) py-(--cue-pad-row-y)", ground),
+				children: words
+			}), children] })
 		});
 	}),
-	Group: React.forwardRef(function LedgerGroup({ className, label, headingLevel = 3, sticky = true, children, ...elementProps }, ref) {
+	Group: React.forwardRef(function LedgerGroup({ className, label, headingLevel = 3, sticky = true, collapsible = false, expanded, defaultExpanded = true, onExpandedChange, children, ...elementProps }, ref) {
 		const Heading = headingTag(headingLevel);
 		const labelled = label !== void 0;
+		const ground = sticky ? "sticky self-start [top:var(--cue-ledger-slug-top,2.5rem)] bg-bg" : null;
 		return /* @__PURE__ */ jsx("div", {
 			ref,
 			"data-slot": "ledger-group",
 			"data-labelled": labelled ? "" : void 0,
 			className: cn(labelled ? "grid [grid-template-columns:var(--cue-ledger-gutter,7rem)_minmax(0,1fr)]" : "flex flex-col", className),
 			...elementProps,
-			children: labelled ? /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(Heading, {
+			children: !labelled ? children : collapsible ? /* @__PURE__ */ jsx(LedgerDisclosure, {
+				headingLevel,
+				headingSlot: "ledger-group-label",
+				headingClassName: cn(LEDGER_LABEL, "min-w-0 py-(--cue-pad-row-y) pr-(--cue-space-3)", ground),
+				toggleSlot: "ledger-group-toggle",
+				toggleClassName: cn(LEDGER_LABEL, LEDGER_TOGGLE),
+				panelSlot: "ledger-group-rows",
+				panelClassName: "flex min-w-0 flex-col",
+				label: /* @__PURE__ */ jsx("span", {
+					className: "min-w-0 truncate",
+					children: label
+				}),
+				expanded,
+				defaultExpanded,
+				onExpandedChange,
+				children
+			}) : /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(Heading, {
 				"data-slot": "ledger-group-label",
-				className: cn(LEDGER_LABEL, "min-w-0 truncate py-(--cue-pad-row-y) pr-(--cue-space-3)", sticky ? "sticky self-start [top:var(--cue-ledger-slug-top,2.5rem)] bg-bg" : null),
+				className: cn(LEDGER_LABEL, "min-w-0 truncate py-(--cue-pad-row-y) pr-(--cue-space-3)", ground),
 				children: label
 			}), /* @__PURE__ */ jsx("div", {
 				"data-slot": "ledger-group-rows",
 				className: "flex min-w-0 flex-col",
 				children
-			})] }) : children
+			})] })
 		});
 	}),
 	Empty: React.forwardRef(function LedgerEmpty({ className, ...elementProps }, ref) {

package/dist/instruments/table.d.ts

@@ -16,13 +16,26 @@ interface TableRootProps extends React.ComponentPropsWithoutRef<"table"> {}
 interface TableSectionProps extends React.ComponentPropsWithoutRef<"tbody"> {}
 interface TableRowProps extends React.ComponentPropsWithoutRef<"tr"> {
   /**
-   * The row responds to a pointer: the row-hover wash and a pointer cursor
-   * across the whole row. Defaults to `false`.
+   * The row responds to a pointer and to focus: the row-hover wash, a pointer
+   * cursor across the whole row, and an inset focus ring. Defaults to `false`.
    *
    * Opt-in rather than automatic, because a table of figures nobody can click
    * that lit up under the pointer would be promising an interaction it does not
    * have. Wiring the row up to actually do something — a click handler, a
    * keyboard path to the same thing — stays the caller's job; this is the paint.
+   *
+   * **The focus ring ships with it, because the caller's half is what makes the
+   * row focusable.** A `<tr>` cannot take focus on its own, so the moment a
+   * caller gives one a `tabIndex` to run
+   * {@link activateRowFromKeyDown} against, a keyboard user can reach and
+   * activate a row that shows nothing — a WCAG 2.4.7 failure the pointer user
+   * never sees. The ring is *inset* (`-outline-offset-2`), the same ruling as
+   * `Row` and `DataRow.Root`: these tables live in clipped panes and scroll
+   * regions, where an outset ring on the first or last row is cut off by the
+   * pane's own rim. `outline-solid` rides along with every `outline-<n>` here
+   * because Tailwind v4 leaves `--tw-outline-style` unset otherwise and the
+   * ring never paints — `test/focus-ring.test.ts` is what keeps the pair
+   * together.
    */
   interactive?: boolean;
   /**
@@ -47,6 +60,8 @@ interface TableHeadProps extends React.ComponentPropsWithoutRef<"th"> {
    */
   sticky?: boolean;
 }
+/** The heading elements a group divider's label may be asked to be. */
+type TableGroupHeadingLevel = 2 | 3 | 4 | 5 | 6;
 interface TableGroupRowProps extends Omit<React.ComponentPropsWithoutRef<"tr">, "children"> {
   /**
    * How many columns the divider spans. Required: it must equal the table's
@@ -56,6 +71,29 @@ interface TableGroupRowProps extends Omit<React.ComponentPropsWithoutRef<"tr">,
   span: number;
   /** What the group is called. */
   label: React.ReactNode;
+  /**
+   * Make the label slot a real heading element. Defaults to `undefined` — no
+   * heading, and the label stays the `<span>` it has always been.
+   *
+   * **Set this rather than passing a heading as `label`.** The label slot wraps
+   * whatever it is given, so an `<h2>` handed in as `label` lands *inside* a
+   * `<span>` — which renders, and exposes the heading, and does not validate: a
+   * `<span>` is phrasing content and may not contain a heading. With this prop
+   * the wrapper *is* the heading (`<h2 data-slot="table-group-label">`), so
+   * there is nothing to nest.
+   *
+   * A heading inside a `<th>` is valid — `<th>` takes flow content — and it is
+   * useful: a screen-reader user navigates a long grouped table by heading, and
+   * without one the group names are reachable only by walking the rows. The
+   * `scope="rowgroup"` association is untouched either way; this adds the
+   * divider to the document outline, it does not change what the cell heads.
+   *
+   * Levels run `2`–`6` because the outline has to describe the real nesting of
+   * the page the table sits in, not the table's own idea of itself — the same
+   * ruling as {@link LedgerTierProps.headingLevel}. There is no `1`: a group
+   * divider is never the title of the document.
+   */
+  headingLevel?: TableGroupHeadingLevel;
   /** How many rows the group holds, printed beside its name. */
   count?: number;
   /**

package/dist/instruments/table.js

@@ -79,6 +79,11 @@ const TableBody = React.forwardRef(function TableBody({ className, ...elementPro
 * table whose only per-row controls live in a hidden track wants either a
 * focusable cell beside it or an always-visible cluster.
 *
+* A caller who instead makes the *row* focusable — a `tabIndex` plus
+* {@link activateRowFromClick} and {@link activateRowFromKeyDown}, which is the
+* shape a row that opens a drawer takes — gets the focus ring from
+* {@link TableRowProps.interactive} and needs to draw nothing of its own.
+*
 * The selected tint is the row's, not the cell's: a `background` on the `<tr>`
 * shows through every cell in it, so the fill cannot end up ragged where one
 * cell sets a ground of its own.
@@ -88,7 +93,7 @@ const TableRow = React.forwardRef(function TableRow({ className, interactive = f
 		ref,
 		"data-slot": "table-row",
 		"data-selected": selected ? "" : void 0,
-		className: cn("group/data-row border-b border-border last:border-b-0 data-[selected]:bg-accent-soft", interactive ? "cursor-pointer hover:bg-(--cue-row-hover)" : null, className),
+		className: cn("group/data-row border-b border-border last:border-b-0 data-[selected]:bg-accent-soft", interactive ? "cursor-pointer outline-none hover:bg-(--cue-row-hover) focus-visible:outline-2 focus-visible:outline-solid focus-visible:-outline-offset-2 focus-visible:outline-accent" : null, className),
 		...elementProps
 	});
 });
@@ -121,6 +126,31 @@ const TableHead = React.forwardRef(function TableHead({ className, numeric = fal
 		...elementProps
 	});
 });
+/** `headingLevel` as a tag name, so the outline is real elements, not roles. */
+const headingTag = (level) => `h${level}`;
+/**
+* The label slot's own treatment, worn by the `<span>` and by every heading
+* level alike — which is the point: the two forms have to be indistinguishable.
+*
+* Everything here is a no-op on a `<span>` and a correction on a heading, and
+* each of the four exists because a UA stylesheet sets it on `<h2>`–`<h6>`:
+*
+* - `inline` — headings are `display: block`, and a block label would push the
+*   count onto a second line. This is the one that breaks the layout outright.
+* - `text-[length:inherit]` — `<h2>` is `1.5em` and `<h6>` is `0.67em`, so
+*   without this the divider's type would change with the level it was given,
+*   which is a heading level leaking into the visual design.
+* - `font-normal` — headings come bold, and a bold micro-label in a dense list
+*   reads as a second kind of emphasis (the same ruling as `Ledger`'s heading).
+* - `m-0` — headings carry a block margin that would thicken the divider row.
+*
+* Preflight already does the middle two for consumers who import it, but the
+* library does not assume the consumer's reset: the divider has to look the
+* same either way. Tracking, case and colour are *not* restated — no UA rule
+* touches them, so they inherit from the `<th>` that owns the recipe, and a
+* second copy of a treatment is exactly how two surfaces drift apart.
+*/
+const TABLE_GROUP_LABEL = "m-0 inline text-[length:inherit] font-normal";
 /**
 * The canonical console table: hairlines, mono figures, no zebra striping.
 *
@@ -161,7 +191,8 @@ const Table = {
 	Header: TableHeader,
 	Body: TableBody,
 	Row: TableRow,
-	GroupRow: React.forwardRef(function TableGroupRow({ className, span, label, count, sticky = false, ...elementProps }, ref) {
+	GroupRow: React.forwardRef(function TableGroupRow({ className, span, label, count, headingLevel, sticky = false, ...elementProps }, ref) {
+		const Label = headingLevel === void 0 ? "span" : headingTag(headingLevel);
 		return /* @__PURE__ */ jsx("tr", {
 			ref,
 			"data-slot": "table-group-row",
@@ -171,8 +202,9 @@ const Table = {
 				scope: "rowgroup",
 				"data-slot": "table-group-cell",
 				className: cn("bg-bg px-(--cue-pad-row-x) py-(--cue-pad-row-y) text-left font-mono text-(length:--cue-text-label) font-normal tracking-[0.15em] whitespace-nowrap text-fg-subtle uppercase", sticky ? "sticky z-2 [top:var(--cue-table-group-top,0px)]" : null, className),
-				children: [/* @__PURE__ */ jsx("span", {
+				children: [/* @__PURE__ */ jsx(Label, {
 					"data-slot": "table-group-label",
+					className: TABLE_GROUP_LABEL,
 					children: label
 				}), count === void 0 ? null : /* @__PURE__ */ jsx("span", {
 					"data-slot": "table-group-count",

package/manifest/components/data-row.json

@@ -157,6 +157,11 @@
       "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>",

package/manifest/components/data-tree.json

@@ -128,6 +128,7 @@
   "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": [

package/manifest/components/ledger.json

@@ -5,7 +5,7 @@
   "importPath": "@cueplusplus/ui",
   "peerDependencies": [],
   "clientOnly": false,
-  "description": "A grouped run of dense rows under sticky headings: the ledger idiom.\n\nThe flattest of the three surfaces this package ships over one row model, and\nthe one that does the least: headings, slugs, rows. **Nothing here collapses.**\nA ledger with a disclosure on it would be a tree with worse semantics, so the\ncomponent emits no `aria-expanded` anywhere, and a test holds it to that —\ncollapse belongs to `DataTree`, and grouping-with-columns belongs to a\ngrouped `Table`.\n\nWhat it does own is the document outline. Tiers and groups are real `<h2>` /\n`<h3>` elements at caller-chosen levels, because in a list of two hundred\nrows the heading list *is* how a screen-reader user navigates.\n\nStatic markup — no `\"use client\"`. The rows inside it may be anything;\n`DataRow` is the intended tenant.",
+  "description": "A grouped run of dense rows under sticky headings: the ledger idiom.\n\nThe flattest of the three surfaces this package ships over one row model:\nheadings, slugs, rows. What it owns above all is the document outline. Tiers\nand groups are real `<h2>` / `<h3>` elements at caller-chosen levels, because\nin a list of two hundred rows the heading list *is* how a screen-reader user\nnavigates.\n\n## Folding: the accordion pattern, opt-in, and why it lives here\n\nThis component used to refuse disclosure outright, on the grounds that *a\nledger which folds is a tree with worse semantics*. That ruling was right\nabout rows and wrong about places, and the distinction is the whole of\n{@link LedgerTierProps.collapsible}:\n\n- **`DataTree` folds a row.** Its `role=\"treeitem\"` rows carry their own\n  `aria-expanded`, its chevron is `role=\"presentation\"` because in tree\n  semantics the row owns its expansion, and a tier and a subgroup drawn\n  through it stop being places and become rows. A consumer who measured this\n  exact shape through `DataTree` counted **zero** `h2`/`h3` elements and zero\n  `button[aria-expanded]`, which is `DataTree` working correctly and still\n  not being what a grouped document needs.\n- **`Ledger` folds a place.** A tier is already an `<h2>`, which is already\n  the right element for it, so the disclosure goes *inside* the heading as a\n  real `<button aria-expanded aria-controls>` — the accordion pattern, and\n  the same one `Table.GroupRow`'s note has always pointed at for a table that\n  genuinely needs to fold. The outline is untouched: the heading list of a\n  folding ledger and a plain one are identical, which is what lets a page\n  offer both idioms over one dataset without the outline moving under a\n  reader who switches.\n\nSo it is one component with two forms rather than a `DisclosureLedger` beside\nit: everything a folding ledger needs — the gutter track, the sticky offsets,\nthe label recipe, the type contract — is this component, and a sibling would\nhave been a copy of all of it wrapped around one `<button>`.\n\nExpansion is controllable and stores nothing. *Which* places a reader has\nfolded is a fact about the reader; consumers keep that set themselves and\npass it back in. A folded run of rows is hidden rather than unmounted, so a\ngroup that keeps its own fold inside a tier still keeps it after the tier has\nbeen shut and opened over it.\n\nStatic markup — no `\"use client\"` — **until a heading is asked to fold**, at\nwhich point that heading and its rows become a small client island and the\nrest of the ledger keeps rendering on the server.",
   "props": [],
   "typeReferences": [],
   "subcomponents": [
@@ -71,6 +71,34 @@
           "required": false,
           "defaultValue": null,
           "description": "A qualifier printed after the name — a date, a source, a state."
+        },
+        {
+          "name": "collapsible",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Put a disclosure in the tier's heading that folds its rows away. Defaults\nto `false`, and a tier with no `heading` has nothing to fold from, so it\nignores this and renders as it always has.\n\n**This is the accordion pattern, not the tree pattern.** What folds is the\nheading — a *place* — and the `<h2>` stays exactly where it was with a real\n`<button aria-expanded aria-controls>` inside it. The rows below are hidden\nwhile it is shut, which takes them out of the accessibility tree and out of\nthe layout but keeps whatever state they hold. If what you are folding is a\n*row*, and the thing under it is that row's children rather than that\nplace's contents, you want `DataTree` and its `treeitem` semantics instead."
+        },
+        {
+          "name": "expanded",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": null,
+          "description": "Whether the tier is open, when the caller owns the state.\n\n**Persistence is the caller's.** Which places a reader has folded is a fact\nabout the reader, not about the list, and it belongs wherever that consumer\nkeeps the rest of them — `localStorage`, a URL, a profile. This library\nstores nothing. Pass this with {@link LedgerTierProps.onExpandedChange};\nomit both and the tier keeps its own state from\n{@link LedgerTierProps.defaultExpanded}. Ignored unless `collapsible`."
+        },
+        {
+          "name": "defaultExpanded",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "true",
+          "description": "Whether an uncontrolled tier starts open. Defaults to `true`.\n\nOpen, because a ledger whose content is folded away on first paint has\nhidden the thing the reader came for; the reader folds what they are done\nwith. Ignored unless `collapsible`, and ignored entirely once\n{@link LedgerTierProps.expanded} is passed."
+        },
+        {
+          "name": "onExpandedChange",
+          "type": "((expanded: boolean) => void)",
+          "required": false,
+          "defaultValue": null,
+          "description": "Called with the tier's next state each time the reader presses the\ndisclosure — `true` when it is being opened, `false` when it is being shut.\n\nFires in both the controlled and the uncontrolled form, so a consumer can\nrecord what was folded without also having to own the state."
         }
       ],
       "typeReferences": [
@@ -102,6 +130,34 @@
           "required": false,
           "defaultValue": "true",
           "description": "Dock the slug under the tier heading while the group's rows scroll past.\nDefaults to `true`.\n\nThe offset is a custom property, `--cue-ledger-slug-top` (default `2.5rem`):\nhow far down the slug docks depends on how tall the tier heading above it\nrenders, which is a function of the density and the type the *caller*\nconfigured. Set it on the ledger — `className=\"[--cue-ledger-slug-top:2rem]\"` —\nrather than measuring at runtime."
+        },
+        {
+          "name": "collapsible",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Put a disclosure in the group's slug that folds its rows away. Defaults to\n`false`, and an unlabelled group has no slug to fold from, so it ignores\nthis. The same accordion pattern the tier takes — see\n{@link LedgerTierProps.collapsible} for why it is not the tree pattern."
+        },
+        {
+          "name": "expanded",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": null,
+          "description": "Whether the group is open, when the caller owns the state. Persistence is\nthe caller's; see {@link LedgerTierProps.expanded}."
+        },
+        {
+          "name": "defaultExpanded",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "true",
+          "description": "Whether an uncontrolled group starts open. Defaults to `true`."
+        },
+        {
+          "name": "onExpandedChange",
+          "type": "((expanded: boolean) => void)",
+          "required": false,
+          "defaultValue": null,
+          "description": "Called with the group's next state each time the reader presses the slug."
         }
       ],
       "typeReferences": [
@@ -121,11 +177,13 @@
   "variants": {},
   "defaultVariants": {},
   "tokensUsed": [
+    "--cue-accent",
     "--cue-bg",
     "--cue-data-row-cols",
     "--cue-fg",
     "--cue-fg-subtle",
     "--cue-font-mono",
+    "--cue-icon-sm",
     "--cue-ledger-gutter",
     "--cue-ledger-slug-top",
     "--cue-pad-row-x",
@@ -135,7 +193,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "Grouped dense rows under sticky tier headings and gutter slugs, with no disclosure anywhere.",
+  "summary": "Grouped dense rows under sticky tier headings and gutter slugs, with an opt-in disclosure that folds a heading without leaving the outline.",
   "examples": [
     {
       "title": "Tiers, groups, rows",
@@ -147,9 +205,14 @@
       "code": "<Ledger.Tier>\n  <Ledger.Group>\n    <DataRow.Root>…</DataRow.Root>\n  </Ledger.Group>\n</Ledger.Tier>",
       "language": "tsx"
     },
+    {
+      "title": "Folded places, persisted by the caller",
+      "code": "<Ledger.Tier\n  heading=\"Ours\"\n  count={13}\n  collapsible\n  expanded={!folded.includes(\"ours\")}\n  onExpandedChange={(open) => remember(\"ours\", open)}\n>\n  <Ledger.Group label=\"released\" collapsible defaultExpanded={false}>\n    <DataRow.Root>…</DataRow.Root>\n  </Ledger.Group>\n</Ledger.Tier>",
+      "language": "tsx"
+    },
     {
       "title": "Usage",
-      "code": "<Ledger.Root className=\"[--cue-data-row-cols:1fr_8rem_auto]\">\n  <Ledger.Tier heading=\"Ours\" count={12}>\n    <Ledger.Group label=\"released\">\n      <DataRow.Root interactive onActivate={open}>…</DataRow.Root>\n    </Ledger.Group>\n    <Ledger.Group label=\"lab\">\n      <Ledger.Empty>Nothing yet.</Ledger.Empty>\n    </Ledger.Group>\n  </Ledger.Tier>\n</Ledger.Root>",
+      "code": "<Ledger.Root className=\"[--cue-data-row-cols:1fr_8rem_auto]\">\n  <Ledger.Tier heading=\"Ours\" count={12}>\n    <Ledger.Group label=\"released\">\n      <DataRow.Root interactive onActivate={open}>…</DataRow.Root>\n    </Ledger.Group>\n    <Ledger.Group label=\"lab\">\n      <Ledger.Empty>Nothing yet.</Ledger.Empty>\n    </Ledger.Group>\n  </Ledger.Tier>\n</Ledger.Root>\n// Folded places are the reader's, so the reader's storage holds them.\n<Ledger.Tier\n  heading=\"Ours\"\n  count={13}\n  collapsible\n  expanded={!folded.includes(\"ours\")}\n  onExpandedChange={(open) => remember(\"ours\", open)}\n>\n  <Ledger.Group label=\"released\">…</Ledger.Group>\n</Ledger.Tier>",
       "language": "tsx"
     }
   ],
@@ -158,16 +221,18 @@
   "mdUrl": "/docs/components/ledger.md",
   "jsonUrl": "/r/components/ledger.json",
   "whenToUse": [
-    "A long list that is grouped but never folded: a corpus by source, a patch by direction, a run log by day.",
-    "A surface whose groups should be reachable by heading, since the tiers and slugs are real `h2`/`h3` elements."
+    "A long grouped list: a corpus by source, a patch by direction, a run log by day.",
+    "A surface whose groups should be reachable by heading, since the tiers and slugs are real `h2`/`h3` elements.",
+    "A grouped list the reader folds *by place* — `collapsible` puts a real `button[aria-expanded]` inside the heading and leaves the `h2`/`h3` outline exactly as it was."
   ],
   "whenNotToUse": [
-    "A hierarchy the reader folds. Use `DataTree`, which owns collapse and the tree semantics that go with it.",
+    "A hierarchy whose *rows* fold into their own children. Use `DataTree`, where the row is the treeitem and owns its expansion.",
     "Rows meant to be compared down a named column. Use a grouped `Table`, where the columns are named once in a `thead`.",
     "A handful of rows in a panel. Use `Row` inside `Panel`; a tier heading over three rows is furniture with nothing to organise."
   ],
   "commonMistakes": [
-    "Adding a toggle to a tier. A ledger that folds is a tree with worse semantics — the component emits no `aria-expanded`, and a test holds it to that.",
+    "Reaching for `DataTree` to fold a grouped list. A tree turns every tier and subgroup into a `treeitem` row and leaves zero headings behind — if the thing folding is a *place*, `collapsible` is the prop.",
+    "Storing the folded set inside the component. Which places a reader folded is a fact about the reader: pass `expanded` and `onExpandedChange` and keep it wherever the rest of that reader's preferences live.",
     "Framing each group in a `Panel`. A card per group turns one list into a stack of little tables and breaks the top-to-bottom scan.",
     "Leaving `--cue-ledger-slug-top` at its default after changing the density or the heading type, which docks the slug over the tier heading instead of under it.",
     "Passing an `empty` string as a prop. `Ledger.Empty` takes the words because \"this place is empty\" and \"your filter emptied it\" are different sentences."
@@ -182,6 +247,16 @@
       "code": "<Panel className=\"w-full\">\n  <div className=\"max-h-[18rem] overflow-y-auto\">\n    <Ledger.Root className={PATCH_TRACKS}>\n      <Ledger.Tier heading=\"Patch\" count={PATCH_DEVICES.length} note=\"polled 18:04\">\n        {PATCH_GROUPS.map((group) => (\n          <Ledger.Group key={group.id} label={group.label}>\n            {group.rows.map((device) => (\n              <DataRow.Root key={device.id} interactive>\n                <PatchRowSlots device={device} />\n              </DataRow.Root>\n            ))}\n          </Ledger.Group>\n        ))}\n        <Ledger.Group label=\"spare\">\n          <Ledger.Empty>Nothing yet.</Ledger.Empty>\n        </Ledger.Group>\n      </Ledger.Tier>\n    </Ledger.Root>\n  </div>\n</Panel>",
       "note": "The same rows as tiers and slugs: sticky headings, a gutter for the group name, and no disclosure anywhere — the ledger does not collapse.",
       "interaction": "the tier heading and the group slug dock as the rows scroll under them; scroll the pane to see it."
+    },
+    {
+      "title": "Ledger — collapsible",
+      "group": "instruments",
+      "components": [
+        "Ledger"
+      ],
+      "code": "<Panel className=\"w-full\">\n  <div className=\"max-h-[18rem] overflow-y-auto\">\n    <Ledger.Root className={PATCH_TRACKS}>\n      <Ledger.Tier\n        heading=\"Patch\"\n        count={PATCH_DEVICES.length}\n        collapsible\n        expanded={patchOpen}\n        onExpandedChange={setPatchOpen}\n      >\n        {PATCH_GROUPS.map((group, index) => (\n          <Ledger.Group\n            key={group.id}\n            label={group.label}\n            collapsible\n            defaultExpanded={index === 0}\n          >\n            {group.rows.map((device) => (\n              <DataRow.Root key={device.id} interactive>\n                <PatchRowSlots device={device} />\n              </DataRow.Root>\n            ))}\n          </Ledger.Group>\n        ))}\n      </Ledger.Tier>\n    </Ledger.Root>\n  </div>\n</Panel>",
+      "note": "The same ledger with `collapsible` on the tier and on one group. The disclosure is a real `button[aria-expanded aria-controls]` *inside* the `h2`/`h3`, so the heading outline is identical to the bench above it. A folded run of rows is hidden rather than unmounted — out of the layout and out of the accessibility tree, but still holding its state, which is what lets a group keep its own fold while the tier above it is shut and reopened. Which places are folded is the caller's to keep; this bench keeps it in React state and nothing is stored by the library.",
+      "interaction": "press a tier heading or a group slug to fold it; the chevron turns, the sibling group stays open, and Tab reaches each disclosure as a real button with Enter and Space. Fold the first group, then fold and reopen the tier over it: the group is still folded."
     }
   ]
 }