@cueplusplus/ui 0.7.0 → 0.9.0

package/dist/configurator/panel-sections.js

@@ -1,22 +1,20 @@
 "use client";
 import { cn } from "../lib/cn.js";
 import { Input } from "../forms/input.js";
-import { DENSITY_LEVELS } from "../system/density.js";
+import { useDensities, useThemes } from "../system/theme-registry.js";
 import { SectionHeader } from "../chrome/section-header.js";
 import { SegmentedControl } from "../chrome/segmented-control.js";
 import { Field, FieldLabel } from "../forms/field.js";
 import { Slider } from "../forms/slider.js";
 import { Kbd } from "../primitives/kbd.js";
 import { useTheme } from "../system/use-theme.js";
-import { THEME_PRESETS } from "../theming/_presets.js";
 import { tokenProperty } from "../theming/serialize.js";
 import { COLOR_TOKENS, FONT_TOKENS, isSafeCssValue } from "./_overrides.js";
 import { TokenEditor } from "./token-editor.js";
 import * as React from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
+import { resolve } from "@cueplusplus/theme-base";
 //#region src/configurator/panel-sections.tsx
-/** The presets, in menu order, with the palette each one is announced by. */
-const PRESETS = Object.keys(THEME_PRESETS);
 /** The five colours a preset is recognisable from, in reading order. */
 const SWATCH_TOKENS = [
 	"bg",
@@ -44,13 +42,25 @@ const MODE_ITEMS = [
 * and `Ultra-large` alone are 25 characters — so the segmented control wears
 * the garment sizes and the value it sets is still the ladder's own name.
 */
-const DENSITY_LABELS = {
+const BASE_DENSITY_LABELS = {
 	"ultra-compact": "XS",
 	"compact": "S",
 	"normal": "M",
 	"large": "L",
 	"ultra-large": "XL"
 };
+/**
+* What a rung is called in the panel.
+*
+* A lookup rather than a table, because the ladder is open now: a theme may add
+* a rung, and this package has no garment size to give it. Its own name is the
+* only label that is certainly true — longer than a letter, and honest about
+* being the theme's rather than the ladder's. The base five keep their sizes,
+* so nothing a user has learned moves.
+*/
+function densityLabel(rung) {
+	return BASE_DENSITY_LABELS[rung] ?? rung;
+}
 /** Bounds of the text-scale knob, from spec §6's `fontScale`. */
 const FONT_SCALE = {
 	min: .8,
@@ -77,7 +87,16 @@ const FONT_LABELS = {
 };
 /** Base UI hands a range slider an array; every slider here has one thumb. */
 const single = (value) => Array.isArray(value) ? value[0] ?? 0 : value;
-/** A number knob wired to one token, live on drag and persisted on release. */
+/**
+* A number knob wired to one token, live on drag and persisted on release.
+*
+* The three it is used for are `--cue-radius-scale` and `--cue-density`, both
+* crossed with the density ladder when they are written, and `--cue-font-scale`,
+* which the provider publishes inline. Naming them here is not decoration: the
+* package manifest's token list is scraped for literal `--cue-*` spellings, and
+* a token whose only spelling in this file is the bare `token="radius-scale"`
+* prop is a token the docs page for this section does not list.
+*/
 function ScaleSlider({ label, token, edits, bounds }) {
 	const value = Number(edits.value(token));
 	return /* @__PURE__ */ jsx(Slider, {
@@ -147,16 +166,27 @@ function TextTokenField({ label, token, edits, placeholder }) {
 */
 function PresetSection({ edits, zoom, className }) {
 	const { theme, density, mode, resolvedMode, setTheme, setDensity, setMode } = useTheme();
+	const themes = useThemes();
+	const densities = useDensities();
 	return /* @__PURE__ */ jsxs(SectionHeader, {
 		label: "Preset",
 		collapsible: true,
 		className,
 		children: [
-			/* @__PURE__ */ jsx("div", {
+			themes.length === 0 ? /* @__PURE__ */ jsxs("p", {
+				className: "text-fg-muted text-ui",
+				children: [
+					"No themes registered — pass ",
+					/* @__PURE__ */ jsx("code", { children: "themes" }),
+					" to ",
+					/* @__PURE__ */ jsx("code", { children: "ThemeProvider" }),
+					"."
+				]
+			}) : /* @__PURE__ */ jsx("div", {
 				className: "grid grid-cols-2 gap-(--cue-space-2)",
-				children: PRESETS.map((name) => {
-					const preset = THEME_PRESETS[name];
-					const palette = (resolvedMode === "light" ? preset.light : preset.dark) ?? preset.dark;
+				children: themes.map((manifest) => {
+					const name = manifest.name;
+					const palette = resolve(manifest, { mode: resolvedMode }).colors;
 					const active = name === theme;
 					return /* @__PURE__ */ jsxs("button", {
 						type: "button",
@@ -197,9 +227,9 @@ function PresetSection({ edits, zoom, className }) {
 				itemClassName: "flex-1",
 				value: density,
 				onValueChange: (next) => setDensity(next),
-				items: DENSITY_LEVELS.map((level) => ({
-					value: level,
-					label: DENSITY_LABELS[level]
+				items: densities.map((rung) => ({
+					value: rung.name,
+					label: densityLabel(rung.name)
 				}))
 			}),
 			/* @__PURE__ */ jsx(ScaleSlider, {

package/dist/elements/command-palette.js

@@ -32,7 +32,7 @@ function ElementsCommandPalette({ commands, query, activeId, onQueryChange, onAc
 		if (next) onActiveChange?.(next.id);
 	};
 	useEffect(() => {
-		document.getElementById(optionId(activeId))?.scrollIntoView({ block: "nearest" });
+		document.getElementById(`${listId}-${activeId}`)?.scrollIntoView({ block: "nearest" });
 	}, [activeId, listId]);
 	const onKeyDown = (event) => {
 		if (event.nativeEvent.isComposing) return;

package/dist/elements/flow-graph.js

@@ -47,7 +47,7 @@ function FlowGraph({ nodes, edges, visibleCount, className, ...props }) {
 					const from = nodes.find((node) => node.id === edge.from);
 					const to = nodes.find((node) => node.id === edge.to);
 					if (!from || !to) return null;
-					shownIds.has(edge.from) && shownIds.has(edge.to);
+					const live = shownIds.has(edge.from) && shownIds.has(edge.to);
 					const a = center(from);
 					const b = center(to);
 					const midX = (a.x + b.x) / 2;
@@ -55,7 +55,7 @@ function FlowGraph({ nodes, edges, visibleCount, className, ...props }) {
 						d: `M ${a.x + NODE_W / 2} ${a.y} C ${midX} ${a.y}, ${midX} ${b.y}, ${b.x - NODE_W / 2} ${b.y}`,
 						fill: "none",
 						strokeWidth: "1.5",
-						className: cn("transition-opacity duration-500 motion-reduce:transition-none", "stroke-fg-subtle")
+						className: cn("transition-opacity duration-500 motion-reduce:transition-none", "stroke-fg-subtle", live ? "opacity-100" : "opacity-30")
 					}, `${edge.from}-${edge.to}`);
 				})
 			}), shown.map((node) => /* @__PURE__ */ jsx("div", {

package/dist/elements/markdown.js

@@ -130,7 +130,7 @@ function safeUrl(value) {
 const FENCE = /^ {0,3}(`{3,}|~{3,})/;
 /** Whether a character can sit next to a delimiter run without closing a word. */
 function isBoundary(char) {
-	return char === "" || /[\s!-\/:-@[-`{-~]/.test(char);
+	return char === "" || /[\s!-/:-@[-`{-~]/.test(char);
 }
 /**
 * Where the last block of `source` begins: after the final blank line that is

package/dist/elements/surfaces.js

@@ -80,10 +80,11 @@ function ShimmerLabel({ active = true, className, ...props }) {
 * announced nor copied into a selection.
 */
 function SwapLabel({ active, children, className }) {
-	const layers = [useRef(null), useRef(null)];
+	const restingRef = useRef(null);
+	const activeRef = useRef(null);
 	const [width, setWidth] = useState(null);
 	useLayoutEffect(() => {
-		const target = layers[active]?.current;
+		const target = (active === 0 ? restingRef : activeRef).current;
 		if (!target) return void 0;
 		const measure = () => setWidth(Math.ceil(target.getBoundingClientRect().width));
 		measure();
@@ -96,7 +97,7 @@ function SwapLabel({ active, children, className }) {
 		style: width === null ? void 0 : { width },
 		className: cn("grid overflow-x-clip transition-[width] duration-300 ease-[cubic-bezier(0.23,1,0.32,1)] motion-reduce:transition-none", className),
 		children: children.map((layer, index) => /* @__PURE__ */ jsx("span", {
-			ref: layers[index],
+			ref: index === 0 ? restingRef : activeRef,
 			"aria-hidden": active !== index,
 			className: cn(labelSwap, active === index ? labelSwapIn : labelSwapOut),
 			children: layer

package/dist/index.d.ts

@@ -33,6 +33,7 @@ import { Tree, TreeProps, TreeVisibility, TreeVisibilityToggle, TreeVisibilityTo
 import { Toolbar, ToolbarButtonProps, ToolbarGroupProps, ToolbarRootProps, ToolbarSeparatorProps } from "./chrome/toolbar.js";
 import "./chrome/index.js";
 import { ControlVariantProps, FormControlSize, bareControlClasses, controlClasses, controlGroupFocusClasses, controlSurface, controlVariants } from "./forms/_chassis.js";
+import { TokenOverrides } from "./system/overrides.js";
 import { FontFamilies, ResolvedMode, ThemeContextValue, ThemeProvider, ThemeProviderProps } from "./system/theme-provider.js";
 import { Autocomplete, AutocompleteProps } from "./forms/autocomplete.js";
 import { ButtonGroup, ButtonGroupOrientation, ButtonGroupProps } from "./forms/button-group.js";
@@ -122,7 +123,9 @@ import "./primitives/index.js";
 import { Density, DensityProps } from "./system/density.js";
 import { CuePortalFrame, CuePortalFrameProps, useCuePortalProps } from "./system/portal.js";
 import { DEFAULT_STORAGE_KEY, PersistedPreferences, PrepaintDefaults, PrepaintOptions, prepaintScript } from "./system/prepaint.js";
+import { ThemeRegistry } from "./system/vocabulary.js";
+import { useDensities, useFonts, useThemes } from "./system/theme-registry.js";
 import { ControlSize, useControlHeight, useDensity } from "./system/use-density.js";
 import { useTheme } from "./system/use-theme.js";
-import { DensityLevel, FontName, Mode, ThemeName } from "./system/index.js";
-export { AGENT_COLOR_PROPERTY, AGENT_HUES, AGENT_ROOT_COLOR, Accordion, type AccordionHeaderProps, type AccordionItemProps, type AccordionPanelProps, type AccordionRootProps, type AccordionTriggerProps, type AgentColorOptions, AgentPile, type AgentPileEntry, type AgentPileProps, type AgentPileSize, AlertDialog, type AlertDialogActionProps, type AlertDialogCancelProps, type AlertDialogContentProps, type AlertDialogDescriptionProps, type AlertDialogFooterProps, type AlertDialogRootProps, type AlertDialogTitleProps, type AlertDialogTriggerProps, AppBar, type AppBarActionsProps, type AppBarBrandProps, type AppBarLinkProps, type AppBarNavProps, type AppBarRegister, type AppBarRootProps, type AppBarSeparatorProps, AppShell, type AppShellAsideProps, type AppShellBarProps, type AppShellBodyProps, type AppShellContentProps, type AppShellNavTriggerProps, type AppShellRootProps, type AppShellScrollerProps, type AppShellSidebarProps, AppWindowFrame, type AppWindowFrameProps, type AskAnswer, AskBox, type AskBoxProps, type AskDanger, type AskKind, type AskOption, AudienceIcon, Autocomplete, type AutocompleteProps, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarSize, type BarOverflow, type BrandAssetProps, type BrandSize, type BrandTone, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Button, ButtonGroup, type ButtonGroupOrientation, type ButtonGroupProps, type ButtonProps, Card, type CardContentProps, type CardDescriptionProps, type CardFooterProps, type CardHeaderProps, type CardRootProps, type CardTitleProps, CatalogueIcon, ChannelBetaIcon, ChannelReleasedIcon, Checkbox, CheckboxGroup, type CheckboxGroupProps, type CheckboxProps, Chip, type ChipProps, CliToolIcon, Collapsible, type CollapsiblePanelProps, type CollapsibleRootProps, type CollapsibleTriggerProps, Combobox, type ComboboxOption, type ComboboxProps, CommandPalette, type CommandPaletteItem, type CommandPaletteProps, Composer, type ComposerProps, type ComposerSubmitKey, Container, type ContainerProps, type ContainerWidth, ContextMenu, type ContextMenuContentProps, type ContextMenuRootProps, type ContextMenuTriggerProps, type ControlSize, type ControlVariantProps, CopyButton, type CopyButtonProps, CueLogotype, type CueLogotypeProps, CueMark, type CueMarkProps, CuePortalFrame, type CuePortalFrameProps, DEFAULT_STORAGE_KEY, DataRow, type DataRowDisclosure, type DataRowRootProps, type DataRowSlotProps, DataTree, type DataTreeItem, type DataTreeProps, type DataTreeRowState, DelegationCard, type DelegationCardProps, type DelegationDirection, type DelegationStatus, Density, type DensityLevel, type DensityProps, DescriptionList, type DescriptionListDetailProps, type DescriptionListLayout, type DescriptionListRootProps, type DescriptionListTermProps, Dialog, type DialogCloseProps, type DialogContentProps, type DialogDescriptionProps, type DialogFooterProps, type DialogRootProps, type DialogTitleProps, type DialogTriggerProps, Disclosure, type DisclosureProps, Drawer, type DrawerCloseProps, type DrawerContentProps, type DrawerDescriptionProps, type DrawerFooterProps, type DrawerRootProps, type DrawerSwipeDirection, type DrawerTitleProps, type DrawerTriggerProps, DropdownMenu, type DropdownMenuCheckboxItemProps, type DropdownMenuContentProps, type DropdownMenuGroupProps, type DropdownMenuItemProps, type DropdownMenuLabelProps, type DropdownMenuRootProps, type DropdownMenuSeparatorProps, type DropdownMenuTriggerProps, EmptyState, type EmptyStateProps, EnvVarInput, type EnvVarInputProps, Eyebrow, type EyebrowProps, Field, FieldDescription, type FieldDescriptionProps, FieldError, type FieldErrorProps, type FieldIssue, FieldLabel, type FieldLabelProps, type FieldProps, type FilePartition, type FilePartitionOptions, type FileRejectReason, type FileRejection, FileUpload, type FileUploadProps, FolderIcon, type FontFamilies, type FontName, Footer, type FooterProps, type FormControlSize, Grid, type GridColumns, type GridProps, GroupBar, type GroupBarItem, type GroupBarProps, type GroupBarTone, HoverCard, type HoverCardContentProps, type HoverCardRootProps, type HoverCardTriggerProps, IconButton, type IconButtonProps, InfoTip, type InfoTipProps, Input, InputGroup, type InputGroupProps, type InputProps, Item, type ItemProps, Kbd, type KbdProps, Ledger, type LedgerEmptyProps, type LedgerGroupProps, type LedgerRootProps, type LedgerTierProps, Link, type LinkProps, McpServerIcon, Menubar, type MenubarContentProps, type MenubarMenuProps, type MenubarRootProps, type MenubarTriggerProps, Message, MessageList, type MessageListProps, type MessageProps, type MessageRole, Meter, type MeterProps, type MeterProvenance, type MeterTone, type Mode, MultiSelect, type MultiSelectProps, NavigationMenu, type NavigationMenuContentProps, type NavigationMenuItemProps, type NavigationMenuLinkProps, type NavigationMenuListProps, type NavigationMenuRootProps, type NavigationMenuTriggerProps, type NavigationMenuViewportProps, NumberField, type NumberFieldProps, OTPField, type OTPFieldProps, OVERLAY_SIDE_OFFSET, PageShell, type PageShellProps, type PageWidth, Pagination, type PaginationEntry, type PaginationProps, Panel, PanelHeader, type PanelHeaderProps, type PanelProps, PasswordInput, type PasswordInputProps, type PersistedPreferences, Plussie, type PlussieExpression, type PlussieProps, Popover, type PopoverCloseProps, type PopoverContentProps, type PopoverDescriptionProps, type PopoverRootProps, type PopoverTitleProps, type PopoverTriggerProps, type PrepaintDefaults, type PrepaintOptions, Progress, type ProgressProps, Radio, RadioGroup, type RadioGroupProps, type RadioProps, Rating, type RatingProps, type RatingSize, type ResolvedMode, Row, type RowProps, ScrollArea, type ScrollAreaOrientation, type ScrollAreaProps, type ScrollEdges, ScrollableTabsList, type ScrollableTabsListProps, ScrubInput, type ScrubInputProps, SeamCell, type SeamCellProps, SeamGrid, type SeamGridProps, type SeamGround, SeamList, type SeamListProps, SearchInput, type SearchInputProps, SectionHeader, type SectionHeaderProps, SegmentedControl, type SegmentedControlItem, type SegmentedControlProps, type SegmentedControlSize, Select, type SelectOption, type SelectProps, Separator, type SeparatorProps, Sheet, type SheetCloseProps, type SheetContentProps, type SheetDescriptionProps, type SheetFooterProps, type SheetRootProps, type SheetTitleProps, type SheetTriggerProps, Sidebar, type SidebarItemProps, type SidebarRailProps, type SidebarRootProps, type SidebarSectionProps, Skeleton, type SkeletonProps, SkillIcon, Slider, type SliderProps, type SpaceStep, Sparkline, type SparklineProps, Spinner, type SpinnerProps, Stack, type StackAlign, StackIcon, type StackJustify, type StackProps, StacksMatrixIcon, Stat, type StatProps, type StatTone, StatusBar, type StatusBarGroupProps, type StatusBarItemProps, type StatusBarProminence, type StatusBarProps, type StatusBarTone, StatusDot, type StatusDotProps, type StatusTone, Stepper, type StepperProps, type StepperState, type StepperStep, Switch, type SwitchProps, TAB_FADE_PX, TREE_GUIDE_GLYPHS, Table, type TableCaptionProps, type TableCellProps, type TableGroupRowProps, type TableHeadProps, type TableRootProps, type TableRowProps, TableScrollRegion, type TableScrollRegionProps, type TableSectionProps, Tabs, type TabsListProps, type TabsPanelProps, type TabsRootProps, type TabsTabProps, TagsInput, type TagsInputProps, TerminalFrame, type TerminalFrameLine, type TerminalFrameProps, type TerminalLine, type TerminalLineTone, type TerminalScript, type TerminalStep, Textarea, type TextareaProps, type ThemeContextValue, type ThemeName, ThemeProvider, type ThemeProviderProps, Timeline, type TimelineContentProps, type TimelineItemProps, type TimelineMarkerProps, type TimelineRootProps, TitleBar, type TitleBarProps, Toast, type ToastManager, type ToastOptions, type ToastProviderProps, type ToastTone, type ToastViewportProps, Toggle, ToggleGroup, type ToggleGroupProps, type ToggleProps, Toolbar, type ToolbarButtonProps, type ToolbarGroupProps, type ToolbarRootProps, type ToolbarSeparatorProps, Tooltip, type TooltipContentProps, type TooltipProviderProps, type TooltipRootProps, type TooltipTriggerProps, Tree, type TreeGuide, type TreeItem, type TreeProps, type TreeRow, type TreeVisibility, TreeVisibilityToggle, type TreeVisibilityToggleProps, TwoStepButton, type TwoStepButtonProps, type TwoStepTone, type UploadFile, type UploadStatus, UsageChart, type UsageChartPoint, type UsageChartProps, type UsageChartTone, activateRowFromClick, activateRowFromKeyDown, agentColor, agentColorStyle, bareControlClasses, buttonVariants, chipVariants, computeScrollEdges, controlClasses, controlGroupFocusClasses, controlSurface, controlVariants, edgeFadeMask, envReference, flattenTree, itemVariants, linkVariants, menuItemClasses, menuLabelClasses, menuPopupClasses, menuSeparatorClasses, overlayDescriptionClasses, overlayFooterClasses, overlayModalTransitionClasses, overlayPopupTransitionClasses, overlayPositionerClasses, overlaySurfaceClasses, overlayTextClasses, overlayTitleClasses, paginationRange, parseEnvReference, partitionFiles, prepaintScript, rowVariants, scrimClasses, useControlHeight, useCuePortalProps, useDensity, useSidebar, useTheme, useToast };
+import { DensityEntry, DensityLevel, FontEntry, FontName, Mode, ThemeManifest, ThemeName } from "./system/index.js";
+export { AGENT_COLOR_PROPERTY, AGENT_HUES, AGENT_ROOT_COLOR, Accordion, type AccordionHeaderProps, type AccordionItemProps, type AccordionPanelProps, type AccordionRootProps, type AccordionTriggerProps, type AgentColorOptions, AgentPile, type AgentPileEntry, type AgentPileProps, type AgentPileSize, AlertDialog, type AlertDialogActionProps, type AlertDialogCancelProps, type AlertDialogContentProps, type AlertDialogDescriptionProps, type AlertDialogFooterProps, type AlertDialogRootProps, type AlertDialogTitleProps, type AlertDialogTriggerProps, AppBar, type AppBarActionsProps, type AppBarBrandProps, type AppBarLinkProps, type AppBarNavProps, type AppBarRegister, type AppBarRootProps, type AppBarSeparatorProps, AppShell, type AppShellAsideProps, type AppShellBarProps, type AppShellBodyProps, type AppShellContentProps, type AppShellNavTriggerProps, type AppShellRootProps, type AppShellScrollerProps, type AppShellSidebarProps, AppWindowFrame, type AppWindowFrameProps, type AskAnswer, AskBox, type AskBoxProps, type AskDanger, type AskKind, type AskOption, AudienceIcon, Autocomplete, type AutocompleteProps, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarSize, type BarOverflow, type BrandAssetProps, type BrandSize, type BrandTone, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Button, ButtonGroup, type ButtonGroupOrientation, type ButtonGroupProps, type ButtonProps, Card, type CardContentProps, type CardDescriptionProps, type CardFooterProps, type CardHeaderProps, type CardRootProps, type CardTitleProps, CatalogueIcon, ChannelBetaIcon, ChannelReleasedIcon, Checkbox, CheckboxGroup, type CheckboxGroupProps, type CheckboxProps, Chip, type ChipProps, CliToolIcon, Collapsible, type CollapsiblePanelProps, type CollapsibleRootProps, type CollapsibleTriggerProps, Combobox, type ComboboxOption, type ComboboxProps, CommandPalette, type CommandPaletteItem, type CommandPaletteProps, Composer, type ComposerProps, type ComposerSubmitKey, Container, type ContainerProps, type ContainerWidth, ContextMenu, type ContextMenuContentProps, type ContextMenuRootProps, type ContextMenuTriggerProps, type ControlSize, type ControlVariantProps, CopyButton, type CopyButtonProps, CueLogotype, type CueLogotypeProps, CueMark, type CueMarkProps, CuePortalFrame, type CuePortalFrameProps, DEFAULT_STORAGE_KEY, DataRow, type DataRowDisclosure, type DataRowRootProps, type DataRowSlotProps, DataTree, type DataTreeItem, type DataTreeProps, type DataTreeRowState, DelegationCard, type DelegationCardProps, type DelegationDirection, type DelegationStatus, Density, type DensityEntry, type DensityLevel, type DensityProps, DescriptionList, type DescriptionListDetailProps, type DescriptionListLayout, type DescriptionListRootProps, type DescriptionListTermProps, Dialog, type DialogCloseProps, type DialogContentProps, type DialogDescriptionProps, type DialogFooterProps, type DialogRootProps, type DialogTitleProps, type DialogTriggerProps, Disclosure, type DisclosureProps, Drawer, type DrawerCloseProps, type DrawerContentProps, type DrawerDescriptionProps, type DrawerFooterProps, type DrawerRootProps, type DrawerSwipeDirection, type DrawerTitleProps, type DrawerTriggerProps, DropdownMenu, type DropdownMenuCheckboxItemProps, type DropdownMenuContentProps, type DropdownMenuGroupProps, type DropdownMenuItemProps, type DropdownMenuLabelProps, type DropdownMenuRootProps, type DropdownMenuSeparatorProps, type DropdownMenuTriggerProps, EmptyState, type EmptyStateProps, EnvVarInput, type EnvVarInputProps, Eyebrow, type EyebrowProps, Field, FieldDescription, type FieldDescriptionProps, FieldError, type FieldErrorProps, type FieldIssue, FieldLabel, type FieldLabelProps, type FieldProps, type FilePartition, type FilePartitionOptions, type FileRejectReason, type FileRejection, FileUpload, type FileUploadProps, FolderIcon, type FontEntry, type FontFamilies, type FontName, Footer, type FooterProps, type FormControlSize, Grid, type GridColumns, type GridProps, GroupBar, type GroupBarItem, type GroupBarProps, type GroupBarTone, HoverCard, type HoverCardContentProps, type HoverCardRootProps, type HoverCardTriggerProps, IconButton, type IconButtonProps, InfoTip, type InfoTipProps, Input, InputGroup, type InputGroupProps, type InputProps, Item, type ItemProps, Kbd, type KbdProps, Ledger, type LedgerEmptyProps, type LedgerGroupProps, type LedgerRootProps, type LedgerTierProps, Link, type LinkProps, McpServerIcon, Menubar, type MenubarContentProps, type MenubarMenuProps, type MenubarRootProps, type MenubarTriggerProps, Message, MessageList, type MessageListProps, type MessageProps, type MessageRole, Meter, type MeterProps, type MeterProvenance, type MeterTone, type Mode, MultiSelect, type MultiSelectProps, NavigationMenu, type NavigationMenuContentProps, type NavigationMenuItemProps, type NavigationMenuLinkProps, type NavigationMenuListProps, type NavigationMenuRootProps, type NavigationMenuTriggerProps, type NavigationMenuViewportProps, NumberField, type NumberFieldProps, OTPField, type OTPFieldProps, OVERLAY_SIDE_OFFSET, PageShell, type PageShellProps, type PageWidth, Pagination, type PaginationEntry, type PaginationProps, Panel, PanelHeader, type PanelHeaderProps, type PanelProps, PasswordInput, type PasswordInputProps, type PersistedPreferences, Plussie, type PlussieExpression, type PlussieProps, Popover, type PopoverCloseProps, type PopoverContentProps, type PopoverDescriptionProps, type PopoverRootProps, type PopoverTitleProps, type PopoverTriggerProps, type PrepaintDefaults, type PrepaintOptions, Progress, type ProgressProps, Radio, RadioGroup, type RadioGroupProps, type RadioProps, Rating, type RatingProps, type RatingSize, type ResolvedMode, Row, type RowProps, ScrollArea, type ScrollAreaOrientation, type ScrollAreaProps, type ScrollEdges, ScrollableTabsList, type ScrollableTabsListProps, ScrubInput, type ScrubInputProps, SeamCell, type SeamCellProps, SeamGrid, type SeamGridProps, type SeamGround, SeamList, type SeamListProps, SearchInput, type SearchInputProps, SectionHeader, type SectionHeaderProps, SegmentedControl, type SegmentedControlItem, type SegmentedControlProps, type SegmentedControlSize, Select, type SelectOption, type SelectProps, Separator, type SeparatorProps, Sheet, type SheetCloseProps, type SheetContentProps, type SheetDescriptionProps, type SheetFooterProps, type SheetRootProps, type SheetTitleProps, type SheetTriggerProps, Sidebar, type SidebarItemProps, type SidebarRailProps, type SidebarRootProps, type SidebarSectionProps, Skeleton, type SkeletonProps, SkillIcon, Slider, type SliderProps, type SpaceStep, Sparkline, type SparklineProps, Spinner, type SpinnerProps, Stack, type StackAlign, StackIcon, type StackJustify, type StackProps, StacksMatrixIcon, Stat, type StatProps, type StatTone, StatusBar, type StatusBarGroupProps, type StatusBarItemProps, type StatusBarProminence, type StatusBarProps, type StatusBarTone, StatusDot, type StatusDotProps, type StatusTone, Stepper, type StepperProps, type StepperState, type StepperStep, Switch, type SwitchProps, TAB_FADE_PX, TREE_GUIDE_GLYPHS, Table, type TableCaptionProps, type TableCellProps, type TableGroupRowProps, type TableHeadProps, type TableRootProps, type TableRowProps, TableScrollRegion, type TableScrollRegionProps, type TableSectionProps, Tabs, type TabsListProps, type TabsPanelProps, type TabsRootProps, type TabsTabProps, TagsInput, type TagsInputProps, TerminalFrame, type TerminalFrameLine, type TerminalFrameProps, type TerminalLine, type TerminalLineTone, type TerminalScript, type TerminalStep, Textarea, type TextareaProps, type ThemeContextValue, type ThemeManifest, type ThemeName, ThemeProvider, type ThemeProviderProps, type ThemeRegistry, Timeline, type TimelineContentProps, type TimelineItemProps, type TimelineMarkerProps, type TimelineRootProps, TitleBar, type TitleBarProps, Toast, type ToastManager, type ToastOptions, type ToastProviderProps, type ToastTone, type ToastViewportProps, Toggle, ToggleGroup, type ToggleGroupProps, type ToggleProps, type TokenOverrides, Toolbar, type ToolbarButtonProps, type ToolbarGroupProps, type ToolbarRootProps, type ToolbarSeparatorProps, Tooltip, type TooltipContentProps, type TooltipProviderProps, type TooltipRootProps, type TooltipTriggerProps, Tree, type TreeGuide, type TreeItem, type TreeProps, type TreeRow, type TreeVisibility, TreeVisibilityToggle, type TreeVisibilityToggleProps, TwoStepButton, type TwoStepButtonProps, type TwoStepTone, type UploadFile, type UploadStatus, UsageChart, type UsageChartPoint, type UsageChartProps, type UsageChartTone, activateRowFromClick, activateRowFromKeyDown, agentColor, agentColorStyle, bareControlClasses, buttonVariants, chipVariants, computeScrollEdges, controlClasses, controlGroupFocusClasses, controlSurface, controlVariants, edgeFadeMask, envReference, flattenTree, itemVariants, linkVariants, menuItemClasses, menuLabelClasses, menuPopupClasses, menuSeparatorClasses, overlayDescriptionClasses, overlayFooterClasses, overlayModalTransitionClasses, overlayPopupTransitionClasses, overlayPositionerClasses, overlaySurfaceClasses, overlayTextClasses, overlayTitleClasses, paginationRange, parseEnvReference, partitionFiles, prepaintScript, rowVariants, scrimClasses, useControlHeight, useCuePortalProps, useDensities, useDensity, useFonts, useSidebar, useTheme, useThemes, useToast };

package/dist/index.js

@@ -25,6 +25,7 @@ import { AppBar } from "./chrome/app-bar.js";
 import { Sidebar, useSidebar } from "./layout/sidebar.js";
 import { Density } from "./system/density.js";
 import { DEFAULT_STORAGE_KEY, prepaintScript } from "./system/prepaint.js";
+import { useDensities, useFonts, useThemes } from "./system/theme-registry.js";
 import { ThemeProvider } from "./system/theme-provider.js";
 import { CuePortalFrame, useCuePortalProps } from "./system/portal.js";
 import { OVERLAY_SIDE_OFFSET, menuItemClasses, menuLabelClasses, menuPopupClasses, menuSeparatorClasses, overlayDescriptionClasses, overlayFooterClasses, overlayModalTransitionClasses, overlayPopupTransitionClasses, overlayPositionerClasses, overlaySurfaceClasses, overlayTextClasses, overlayTitleClasses, scrimClasses } from "./overlays/_surface.js";
@@ -112,4 +113,4 @@ import { Kbd } from "./primitives/kbd.js";
 import { Skeleton } from "./primitives/skeleton.js";
 import { useControlHeight, useDensity } from "./system/use-density.js";
 import { useTheme } from "./system/use-theme.js";
-export { AGENT_COLOR_PROPERTY, AGENT_HUES, AGENT_ROOT_COLOR, Accordion, AgentPile, AlertDialog, AppBar, AppShell, AppWindowFrame, AskBox, AudienceIcon, Autocomplete, Avatar, AvatarGroup, Breadcrumb, Button, ButtonGroup, Card, CatalogueIcon, ChannelBetaIcon, ChannelReleasedIcon, Checkbox, CheckboxGroup, Chip, CliToolIcon, Collapsible, Combobox, CommandPalette, Composer, Container, ContextMenu, CopyButton, CueLogotype, CueMark, CuePortalFrame, DEFAULT_STORAGE_KEY, DataRow, DataTree, DelegationCard, Density, DescriptionList, Dialog, Disclosure, Drawer, DropdownMenu, EmptyState, EnvVarInput, Eyebrow, Field, FieldDescription, FieldError, FieldLabel, FileUpload, FolderIcon, Footer, Grid, GroupBar, HoverCard, IconButton, InfoTip, Input, InputGroup, Item, Kbd, Ledger, Link, McpServerIcon, Menubar, Message, MessageList, Meter, MultiSelect, NavigationMenu, NumberField, OTPField, OVERLAY_SIDE_OFFSET, PageShell, Pagination, Panel, PanelHeader, PasswordInput, Plussie, Popover, Progress, Radio, RadioGroup, Rating, Row, ScrollArea, ScrollableTabsList, ScrubInput, SeamCell, SeamGrid, SeamList, SearchInput, SectionHeader, SegmentedControl, Select, Separator, Sheet, Sidebar, Skeleton, SkillIcon, Slider, Sparkline, Spinner, Stack, StackIcon, StacksMatrixIcon, Stat, StatusBar, StatusDot, Stepper, Switch, TAB_FADE_PX, TREE_GUIDE_GLYPHS, Table, TableScrollRegion, Tabs, TagsInput, TerminalFrame, Textarea, ThemeProvider, Timeline, TitleBar, Toast, Toggle, ToggleGroup, Toolbar, Tooltip, Tree, TreeVisibilityToggle, TwoStepButton, UsageChart, activateRowFromClick, activateRowFromKeyDown, agentColor, agentColorStyle, bareControlClasses, buttonVariants, chipVariants, computeScrollEdges, controlClasses, controlGroupFocusClasses, controlSurface, controlVariants, edgeFadeMask, envReference, flattenTree, itemVariants, linkVariants, menuItemClasses, menuLabelClasses, menuPopupClasses, menuSeparatorClasses, overlayDescriptionClasses, overlayFooterClasses, overlayModalTransitionClasses, overlayPopupTransitionClasses, overlayPositionerClasses, overlaySurfaceClasses, overlayTextClasses, overlayTitleClasses, paginationRange, parseEnvReference, partitionFiles, prepaintScript, rowVariants, scrimClasses, useControlHeight, useCuePortalProps, useDensity, useSidebar, useTheme, useToast };
+export { AGENT_COLOR_PROPERTY, AGENT_HUES, AGENT_ROOT_COLOR, Accordion, AgentPile, AlertDialog, AppBar, AppShell, AppWindowFrame, AskBox, AudienceIcon, Autocomplete, Avatar, AvatarGroup, Breadcrumb, Button, ButtonGroup, Card, CatalogueIcon, ChannelBetaIcon, ChannelReleasedIcon, Checkbox, CheckboxGroup, Chip, CliToolIcon, Collapsible, Combobox, CommandPalette, Composer, Container, ContextMenu, CopyButton, CueLogotype, CueMark, CuePortalFrame, DEFAULT_STORAGE_KEY, DataRow, DataTree, DelegationCard, Density, DescriptionList, Dialog, Disclosure, Drawer, DropdownMenu, EmptyState, EnvVarInput, Eyebrow, Field, FieldDescription, FieldError, FieldLabel, FileUpload, FolderIcon, Footer, Grid, GroupBar, HoverCard, IconButton, InfoTip, Input, InputGroup, Item, Kbd, Ledger, Link, McpServerIcon, Menubar, Message, MessageList, Meter, MultiSelect, NavigationMenu, NumberField, OTPField, OVERLAY_SIDE_OFFSET, PageShell, Pagination, Panel, PanelHeader, PasswordInput, Plussie, Popover, Progress, Radio, RadioGroup, Rating, Row, ScrollArea, ScrollableTabsList, ScrubInput, SeamCell, SeamGrid, SeamList, SearchInput, SectionHeader, SegmentedControl, Select, Separator, Sheet, Sidebar, Skeleton, SkillIcon, Slider, Sparkline, Spinner, Stack, StackIcon, StacksMatrixIcon, Stat, StatusBar, StatusDot, Stepper, Switch, TAB_FADE_PX, TREE_GUIDE_GLYPHS, Table, TableScrollRegion, Tabs, TagsInput, TerminalFrame, Textarea, ThemeProvider, Timeline, TitleBar, Toast, Toggle, ToggleGroup, Toolbar, Tooltip, Tree, TreeVisibilityToggle, TwoStepButton, UsageChart, activateRowFromClick, activateRowFromKeyDown, agentColor, agentColorStyle, bareControlClasses, buttonVariants, chipVariants, computeScrollEdges, controlClasses, controlGroupFocusClasses, controlSurface, controlVariants, edgeFadeMask, envReference, flattenTree, itemVariants, linkVariants, menuItemClasses, menuLabelClasses, menuPopupClasses, menuSeparatorClasses, overlayDescriptionClasses, overlayFooterClasses, overlayModalTransitionClasses, overlayPopupTransitionClasses, overlayPositionerClasses, overlaySurfaceClasses, overlayTextClasses, overlayTitleClasses, paginationRange, parseEnvReference, partitionFiles, prepaintScript, rowVariants, scrimClasses, useControlHeight, useCuePortalProps, useDensities, useDensity, useFonts, useSidebar, useTheme, useThemes, useToast };

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>>;