@cueplusplus/ui 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @cueplusplus/ui
 
+## 0.8.0
+
+### Minor Changes
+
+- 4c7b963: `Ledger.Tier` and `Ledger.Group` take `collapsible`: the heading stays the `h2`/`h3` element it always was and gains a real `button[aria-expanded aria-controls]` inside it, which folds the run of rows below away. The heading outline is untouched, so a page that offers the same dataset folded and unfolded does not move a screen-reader user's heading list. Expansion is controlled or uncontrolled — `expanded`, `defaultExpanded`, `onExpandedChange` — and the library stores nothing: which places a reader folded is the caller's to keep. A folded run of rows is hidden rather than unmounted, so a group holding its own fold inside a tier still holds it after the tier above has been shut and opened again. A ledger nobody asks to fold renders exactly as before, with no client boundary.
+
+### Patch Changes
+
+- @cueplusplus/tokens@0.8.0
+
 ## 0.7.0
 
 ### Minor Changes

package/dist/instruments/_ledger-disclosure.js

@@ -0,0 +1,103 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { ChevronRightGlyph } from "../chrome/_glyphs.js";
+import { headingTag } from "./_ledger.js";
+import * as React from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/instruments/_ledger-disclosure.tsx
+/**
+* A heading that folds the rows beneath it: the accordion pattern, once, for
+* both of the ledger's headings.
+*
+* ## Why the button is inside the heading rather than instead of it
+*
+* This is the disclosure shape the APG calls an accordion, and the one
+* `Table.GroupRow`'s own note already points at — *"a real
+* `<button aria-expanded aria-controls>` inside this cell, never the row
+* itself"*. The heading element survives, so the page's `h2`/`h3` outline is
+* unchanged whether a tier folds or not, and a screen-reader user who navigates
+* a two-hundred-row ledger by heading — which is what the outline is *for* —
+* finds the same places in the same order either way. Making the heading the
+* button, or replacing it with one, would trade that outline for a control, and
+* the outline is the more valuable of the two.
+*
+* The glyph is `aria-hidden`, so the button's accessible name is the heading's
+* own words. A reader hears "Ours, 13, collapsed button", not "button".
+*
+* ## Why the folded rows are hidden rather than unmounted
+*
+* A folded run of rows stays mounted inside a panel that carries `hidden`. The
+* obvious alternative — dropping the children while the run is shut, so that
+* folding something away costs nothing to have folded — is wrong here, and the
+* reason is that **the rows are not always inert**. A `Ledger.Group` inside a
+* tier is itself a disclosure holding its own uncontrolled state: unmount it
+* and that state goes with it, so a reader who folds three groups, folds the
+* tier over them and opens it again finds all three sprung back open. A control
+* that says nothing about touching them had quietly undone their work. React
+* state below a fold is the caller's too, and this component is not entitled to
+* throw it away.
+*
+* Nothing is given up in exchange. A `hidden` subtree is out of the
+* accessibility tree exactly as an absent one is — no heading in it reaches the
+* outline, no row in it answers `getByRole`, and a screen reader walks past all
+* of it — so the two forms are indistinguishable to the reader this component
+* is built for. What differs is only that the caller's state survives.
+*
+* The panel element itself would have to stay in any case: `aria-controls` must
+* name an element that exists, and pointed at a node that leaves with its
+* contents it becomes a dangling reference and an `aria-valid-attr-value`
+* failure — the very trap `DataRowDisclosure.controls` documents.
+*
+* ## Why the folded panel wears no classes at all
+*
+* `hidden` is a UA rule, `[hidden] { display: none }`, and **any author
+* `display` beats it**: a panel that keeps `flex` while it is `hidden` is a
+* panel that is not hidden. Rather than fight that with a `display` utility
+* whose win depends on Tailwind's emission order, the folded panel is given no
+* class list at all, and the layout classes come back when it opens.
+*
+* Keeping the rows mounted is what makes this load-bearing rather than tidy.
+* When the panel was emptied on folding there was nothing inside to leak; now
+* the panel's own `display: none` is the only thing standing between a folded
+* run of rows and a visible one. It is enough — a `display: none` element
+* generates no boxes for any of its descendants, whatever `display` each of
+* them asks for — but it has to actually apply, and jsdom cannot see whether it
+* does, which is why `tests/browser/data-surfaces.spec.ts` reads the computed
+* `display` on both real engines.
+*/
+function LedgerDisclosure({ headingLevel, headingSlot, headingClassName, toggleSlot, toggleClassName, panelSlot, panelClassName, label, expanded: expandedProp, defaultExpanded = true, onExpandedChange, children }) {
+	const [selfExpanded, setSelfExpanded] = React.useState(defaultExpanded);
+	const expanded = expandedProp ?? selfExpanded;
+	const panelId = React.useId();
+	const Heading = headingTag(headingLevel);
+	const toggle = () => {
+		const next = !expanded;
+		if (expandedProp === void 0) setSelfExpanded(next);
+		onExpandedChange?.(next);
+	};
+	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(Heading, {
+		"data-slot": headingSlot,
+		className: headingClassName,
+		children: /* @__PURE__ */ jsxs("button", {
+			type: "button",
+			"data-slot": toggleSlot,
+			"aria-expanded": expanded,
+			"aria-controls": panelId,
+			onClick: toggle,
+			className: toggleClassName,
+			children: [/* @__PURE__ */ jsx(ChevronRightGlyph, {
+				"aria-hidden": "true",
+				"data-slot": `${toggleSlot}-glyph`,
+				className: cn("size-icon-sm shrink-0 self-center transition-transform duration-150 motion-reduce:transition-none", expanded ? "rotate-90" : null)
+			}), label]
+		})
+	}), /* @__PURE__ */ jsx("div", {
+		id: panelId,
+		"data-slot": panelSlot,
+		hidden: !expanded,
+		className: expanded ? panelClassName : void 0,
+		children
+	})] });
+}
+//#endregion
+export { LedgerDisclosure };

package/dist/instruments/_ledger.d.ts

@@ -0,0 +1,21 @@
+//#region src/instruments/_ledger.d.ts
+/**
+ * The outline half of the ledger, in a module carrying no runtime directive.
+ *
+ * `ledger.tsx` renders on the server and has to keep doing so — a document of
+ * two hundred rows that ships its own JavaScript in order to be *read* is
+ * exactly what the static form exists to avoid — while the disclosure in
+ * `_ledger-disclosure.tsx` holds React state and is therefore `"use client"`.
+ *
+ * A server module may **render** a client one, but it may not **call into** it:
+ * every value imported from a `"use client"` file is a client reference, and
+ * invoking one during a server render throws rather than returning a tag name.
+ * So the two symbols both halves need — what a heading level is, and which
+ * element it names — live here, in a plain module either graph can compile,
+ * instead of being copied into both and drifting the day one of them learns
+ * about `h5`.
+ */
+/** The heading elements a tier or a group may be given. */
+type LedgerHeadingLevel = 2 | 3 | 4;
+//#endregion
+export { LedgerHeadingLevel };

package/dist/instruments/_ledger.js

@@ -0,0 +1,5 @@
+//#region src/instruments/_ledger.ts
+/** `headingLevel` as a tag name, so the outline is real elements, not roles. */
+const headingTag = (level) => level === 2 ? "h2" : level === 3 ? "h3" : "h4";
+//#endregion
+export { headingTag };

package/dist/instruments/ledger.d.ts

@@ -1,7 +1,6 @@
+import { LedgerHeadingLevel } from "./_ledger.js";
 import * as React from "react";
 //#region src/instruments/ledger.d.ts
-/** The heading elements a tier or a group may be given. */
-type LedgerHeadingLevel = 2 | 3 | 4;
 interface LedgerRootProps extends React.ComponentPropsWithoutRef<"div"> {
   /**
    * Make the ledger a size container, so a caller's `@container` rules shed
@@ -40,6 +39,48 @@ interface LedgerTierProps extends React.ComponentPropsWithoutRef<"section"> {
   headingLevel?: LedgerHeadingLevel;
   /** A qualifier printed after the name — a date, a source, a state. */
   note?: React.ReactNode;
+  /**
+   * Put a disclosure in the tier's heading that folds its rows away. Defaults
+   * to `false`, and a tier with no `heading` has nothing to fold from, so it
+   * ignores this and renders as it always has.
+   *
+   * **This is the accordion pattern, not the tree pattern.** What folds is the
+   * heading — a *place* — and the `<h2>` stays exactly where it was with a real
+   * `<button aria-expanded aria-controls>` inside it. The rows below are hidden
+   * while it is shut, which takes them out of the accessibility tree and out of
+   * the layout but keeps whatever state they hold. If what you are folding is a
+   * *row*, and the thing under it is that row's children rather than that
+   * place's contents, you want `DataTree` and its `treeitem` semantics instead.
+   */
+  collapsible?: boolean;
+  /**
+   * Whether the tier is open, when the caller owns the state.
+   *
+   * **Persistence is the caller's.** Which places a reader has folded is a fact
+   * about the reader, not about the list, and it belongs wherever that consumer
+   * keeps the rest of them — `localStorage`, a URL, a profile. This library
+   * stores nothing. Pass this with {@link LedgerTierProps.onExpandedChange};
+   * omit both and the tier keeps its own state from
+   * {@link LedgerTierProps.defaultExpanded}. Ignored unless `collapsible`.
+   */
+  expanded?: boolean;
+  /**
+   * Whether an uncontrolled tier starts open. Defaults to `true`.
+   *
+   * Open, because a ledger whose content is folded away on first paint has
+   * hidden the thing the reader came for; the reader folds what they are done
+   * with. Ignored unless `collapsible`, and ignored entirely once
+   * {@link LedgerTierProps.expanded} is passed.
+   */
+  defaultExpanded?: boolean;
+  /**
+   * Called with the tier's next state each time the reader presses the
+   * disclosure — `true` when it is being opened, `false` when it is being shut.
+   *
+   * Fires in both the controlled and the uncontrolled form, so a consumer can
+   * record what was folded without also having to own the state.
+   */
+  onExpandedChange?: (expanded: boolean) => void;
 }
 interface LedgerGroupProps extends React.ComponentPropsWithoutRef<"div"> {
   /**
@@ -64,24 +105,70 @@ interface LedgerGroupProps extends React.ComponentPropsWithoutRef<"div"> {
    * rather than measuring at runtime.
    */
   sticky?: boolean;
+  /**
+   * Put a disclosure in the group's slug that folds its rows away. Defaults to
+   * `false`, and an unlabelled group has no slug to fold from, so it ignores
+   * this. The same accordion pattern the tier takes — see
+   * {@link LedgerTierProps.collapsible} for why it is not the tree pattern.
+   */
+  collapsible?: boolean;
+  /**
+   * Whether the group is open, when the caller owns the state. Persistence is
+   * the caller's; see {@link LedgerTierProps.expanded}.
+   */
+  expanded?: boolean;
+  /** Whether an uncontrolled group starts open. Defaults to `true`. */
+  defaultExpanded?: boolean;
+  /** Called with the group's next state each time the reader presses the slug. */
+  onExpandedChange?: (expanded: boolean) => void;
 }
 interface LedgerEmptyProps extends React.ComponentPropsWithoutRef<"p"> {}
 /**
  * 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
  *
- * 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.
+ * 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}:
  *
- * Static markup — no `"use client"`. The rows inside it may be anything;
- * `DataRow` is the intended tenant.
+ * - **`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.
+ *
+ * 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]">
@@ -94,6 +181,18 @@ interface LedgerEmptyProps extends React.ComponentPropsWithoutRef<"p"> {}
  *     </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>
  */
 declare const Ledger: {
   Root: React.ForwardRefExoticComponent<LedgerRootProps & React.RefAttributes<HTMLDivElement>>;

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/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."
     }
   ]
 }

package/manifest/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "library": "@cueplusplus/ui",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "themes": [
     "cue",
@@ -29,7 +29,7 @@
   ],
   "tokens": {
     "path": "./tokens.json",
-    "sha256": "6672f3007cb48503b465985501b881b7d5144816bc716d4350e7d9bd7b7c566e"
+    "sha256": "6d7c8411b968edd7c1d6dca18d845ec52370da8f6364cc28454b48122fb3ead0"
   },
   "systemApis": [
     {
@@ -3501,7 +3501,7 @@
       "mdUrl": "/docs/components/data-tree.md",
       "jsonUrl": "/r/components/data-tree.json",
       "path": "./components/data-tree.json",
-      "sha256": "33244c5faf277716152a605c28726b0be0fb110f1bafa8b0b84f8a00a9315b55"
+      "sha256": "3e68587c9fde809009a4a9661636a7b64dbe72b519cde4d6093bd36996106bdf"
     },
     {
       "name": "GroupBar",
@@ -3521,13 +3521,13 @@
       "slug": "ledger",
       "group": "instruments",
       "importPath": "@cueplusplus/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.",
       "status": "stable",
       "url": "/docs/components/ledger",
       "mdUrl": "/docs/components/ledger.md",
       "jsonUrl": "/r/components/ledger.json",
       "path": "./components/ledger.json",
-      "sha256": "129b47da8898b856d150ae7c6901e1e5340cabacd15457b860aa03e80139c388"
+      "sha256": "52cc7f45dbf809e5be6eb04fc2420038143ee199d4f8bef29033d78197c20da6"
     },
     {
       "name": "LogViewer",

package/manifest/tokens.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "library": "@cueplusplus/tokens",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "themes": [
     "cue",
     "terminal",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueplusplus/ui",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "CUE++ design system components: Tailwind v4 styled wrappers over Base UI, driven by @cueplusplus/tokens.",
   "license": "MIT",
   "type": "module",
@@ -140,7 +140,7 @@
     "clsx": "^2.1.1",
     "culori": "^4.0.2",
     "tailwind-merge": "^3.6.0",
-    "@cueplusplus/tokens": "0.7.0"
+    "@cueplusplus/tokens": "0.8.0"
   },
   "peerDependencies": {
     "@assistant-ui/react": "^0.15.16",
@@ -253,8 +253,8 @@
     "tsdown": "0.22.14",
     "typescript": "^5.7.0",
     "vitest": "^4.1.10",
-    "@repo/typescript-config": "0.0.0",
-    "@repo/docgen": "0.0.0"
+    "@repo/docgen": "0.0.0",
+    "@repo/typescript-config": "0.0.0"
   },
   "scripts": {
     "build": "pnpm run check:manifest && tsdown",