@cueplusplus/ui 0.14.0 → 0.15.0

package/dist/system/theme-provider.js

@@ -1,14 +1,15 @@
 "use client";
 import { cn } from "../lib/cn.js";
 import { useIsomorphicInsertionEffect, useIsomorphicLayoutEffect } from "./use-isomorphic-layout-effect.js";
-import { AmbientThemeContext, DensityContext, StyleSetContext } from "./density.js";
-import { buildRegistry, isStyleSet, vocabulary, warnOnce } from "./vocabulary.js";
+import { AmbientThemeContext, DensityContext, PaintContext, StyleSetContext } from "./density.js";
+import { buildRegistry, isPaint, isStyleSet, vocabulary, warnOnce } from "./vocabulary.js";
 import { OverridesContext, inlineOverrides, overridesCss, reportOverrides } from "./overrides.js";
 import { DEFAULT_STORAGE_KEY } from "./prepaint.js";
 import { ThemeRegistryContext } from "./theme-registry.js";
 import * as React from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { MODES, THEME_NAME_PATTERN, validateManifest } from "@cueplusplus/theme-base";
+import { CSPProvider } from "@base-ui/react/csp-provider";
 //#region src/system/theme-provider.tsx
 /**
 * The empty registry, at module scope so the default is referentially stable.
@@ -116,16 +117,21 @@ function acceptedPreferences(vocab, stored, fallback) {
 		density: vocab.acceptsDensity(theme, stored.density) ? stored.density : vocab.acceptsDensity(theme, fallback.density) ? fallback.density : vocab.preferredDensity(theme),
 		font: vocab.acceptsFont(theme, stored.font) ? stored.font : vocab.acceptsFont(theme, fallback.font) ? fallback.font : vocab.preferredFont(theme),
 		mode: isOneOf(MODES, stored.mode) ? stored.mode : fallback.mode,
-		styleSet: isStyleSet(stored.style) ? stored.style : fallback.styleSet
+		styleSet: isStyleSet(stored.style) ? stored.style : fallback.styleSet,
+		paint: isPaint(stored.paint) ? stored.paint : fallback.paint
 	};
 }
 function writePreferences(storageKey, preferences) {
 	if (typeof localStorage === "undefined") return;
-	const { styleSet, ...axes } = preferences;
-	const payload = styleSet === null ? axes : {
+	const { styleSet, paint, ...axes } = preferences;
+	const withStyle = styleSet === null ? axes : {
 		...axes,
 		style: styleSet
 	};
+	const payload = paint === null ? withStyle : {
+		...withStyle,
+		paint
+	};
 	try {
 		localStorage.setItem(storageKey, JSON.stringify(payload));
 	} catch {}
@@ -170,10 +176,11 @@ function writePreferences(storageKey, preferences) {
 *   <App />
 * </ThemeProvider>
 */
-function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityProp, mode: modeProp = DEFAULT_MODE, font: fontProp, styleSet: styleSetProp, fontScale = 1, fontFamilies, overrides, storageKey = DEFAULT_STORAGE_KEY, persistPreferences = true, nonce, asChild = false, className, style: styleProp, children }) {
+function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityProp, mode: modeProp = DEFAULT_MODE, font: fontProp, styleSet: styleSetProp, paint: paintProp, fontScale = 1, fontFamilies, overrides, storageKey = DEFAULT_STORAGE_KEY, persistPreferences = true, nonce, asChild = false, className, style: styleProp, children }) {
 	const ambient = React.useContext(ThemeContext);
 	const isRoot = ambient === null;
 	const outerStyleSet = React.useContext(StyleSetContext);
+	const outerPaint = React.useContext(PaintContext);
 	const ambientRegistry = React.useContext(ThemeRegistryContext);
 	const themes = themesProp ?? ambientRegistry?.themes ?? EMPTY;
 	const vocab = React.useMemo(() => vocabulary(themes), [themes]);
@@ -199,10 +206,12 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 	const initialDensity = densityProp ?? vocab.preferredDensity(initialTheme);
 	const initialFont = fontProp ?? vocab.preferredFont(initialTheme);
 	const initialStyleSet = styleSetProp ?? (isRoot ? null : outerStyleSet);
+	const initialPaint = paintProp ?? (isRoot ? null : outerPaint);
 	const [theme, setThemeState] = React.useState(initialTheme);
 	const [densityState, setDensityState] = React.useState(initialDensity);
 	const [mode, setModeState] = React.useState(modeProp);
 	const [styleSet, setStyleSetState] = React.useState(initialStyleSet);
+	const [paint, setPaintState] = React.useState(initialPaint);
 	const [storedSeed] = React.useState(() => {
 		if (!isRoot || !persistPreferences) return {
 			theme: initialTheme,
@@ -244,14 +253,16 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 			density,
 			font,
 			mode,
-			styleSet
+			styleSet,
+			paint
 		});
 		setThemeState(next.theme);
 		setDensityState(next.density);
 		setRootFontState(next.font);
 		setModeState(next.mode);
 		setStyleSetState(next.styleSet);
-		if (stored.theme !== void 0 && stored.theme !== next.theme || stored.density !== void 0 && stored.density !== next.density || stored.font !== void 0 && stored.font !== next.font || stored.mode !== void 0 && stored.mode !== next.mode || stored.style !== void 0 && !isStyleSet(stored.style)) writePreferences(storageKey, next);
+		setPaintState(next.paint);
+		if (stored.theme !== void 0 && stored.theme !== next.theme || stored.density !== void 0 && stored.density !== next.density || stored.font !== void 0 && stored.font !== next.font || stored.mode !== void 0 && stored.mode !== next.mode || stored.style !== void 0 && !isStyleSet(stored.style) || stored.paint !== void 0 && !isPaint(stored.paint)) writePreferences(storageKey, next);
 	}, [
 		isRoot,
 		persistPreferences,
@@ -262,7 +273,8 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 		density: densityProp,
 		mode: modeProp,
 		font: fontProp,
-		styleSet: styleSetProp
+		styleSet: styleSetProp,
+		paint: paintProp
 	});
 	React.useEffect(() => {
 		const previous = lastProps.current;
@@ -271,19 +283,22 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 			density: densityProp,
 			mode: modeProp,
 			font: fontProp,
-			styleSet: styleSetProp
+			styleSet: styleSetProp,
+			paint: paintProp
 		};
 		if (previous.theme !== themeProp && themeProp !== void 0) setThemeState(themeProp);
 		if (previous.density !== densityProp && densityProp !== void 0) setDensityState(densityProp);
 		if (previous.mode !== modeProp) setModeState(modeProp);
 		if (previous.font !== fontProp && fontProp !== void 0) setRootFontState(fontProp);
 		if (previous.styleSet !== styleSetProp && styleSetProp !== void 0) setStyleSetState(styleSetProp);
+		if (previous.paint !== paintProp && paintProp !== void 0) setPaintState(paintProp);
 	}, [
 		themeProp,
 		densityProp,
 		modeProp,
 		fontProp,
-		styleSetProp
+		styleSetProp,
+		paintProp
 	]);
 	useIsomorphicLayoutEffect(() => {
 		if (typeof window === "undefined" || typeof window.matchMedia !== "function") return;
@@ -298,7 +313,8 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 		density: densityState,
 		mode,
 		font: rawFont,
-		styleSet
+		styleSet,
+		paint
 	});
 	useIsomorphicLayoutEffect(() => {
 		stateRef.current = {
@@ -306,7 +322,8 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 			density: densityState,
 			mode,
 			font: rawFont,
-			styleSet
+			styleSet,
+			paint
 		};
 	});
 	const persist = React.useCallback((patch) => {
@@ -344,6 +361,10 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 		setStyleSetState(next);
 		persist({ styleSet: next });
 	}, [persist]);
+	const setPaint = React.useCallback((next) => {
+		setPaintState(next);
+		persist({ paint: next });
+	}, [persist]);
 	const originalStamp = React.useRef(null);
 	useIsomorphicInsertionEffect(() => {
 		if (!isRoot || typeof document === "undefined") return;
@@ -353,7 +374,8 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 			density,
 			font,
 			mode,
-			styleSet
+			styleSet,
+			paint
 		};
 		const next = restored || !persistPreferences ? current : acceptedPreferences(vocab, readPreferences(storageKey), current);
 		originalStamp.current ??= {
@@ -362,6 +384,7 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 			font: root.getAttribute("data-font"),
 			mode: root.getAttribute("data-mode"),
 			style: root.getAttribute("data-style"),
+			paint: root.getAttribute("data-paint"),
 			colorScheme: root.style.colorScheme
 		};
 		const write = (name, value) => {
@@ -374,6 +397,9 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 		if (next.styleSet === null) {
 			if (root.hasAttribute("data-style")) root.removeAttribute("data-style");
 		} else write("data-style", next.styleSet);
+		if (next.paint === null) {
+			if (root.hasAttribute("data-paint")) root.removeAttribute("data-paint");
+		} else write("data-paint", next.paint);
 		const scheme = (themes.find((m) => m.name === next.theme) ?? null)?.supportsLight === false ? "dark" : next.mode === "system" ? "light dark" : next.mode;
 		if (root.style.colorScheme !== scheme) root.style.colorScheme = scheme;
 	}, [
@@ -403,9 +429,19 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 		restore("data-font", original.font);
 		restore("data-mode", original.mode);
 		restore("data-style", original.style);
+		restore("data-paint", original.paint);
 		root.style.colorScheme = original.colorScheme;
 	}, []);
 	const effectiveStyleSet = styleSet ?? outerStyleSet;
+	/**
+	* The pack in force, for the same reason and with the same caveat: it is what
+	* `useTheme().paint` reports, and it does NOT feed the `data-paint` stamp.
+	* That stays on this provider's own `paint` state, so a root that named none
+	* stamps nothing on itself and nothing on `<html>` however much is stamped
+	* around it — which keeps a `<Density paint>` island out of the document-wide
+	* attribute and out of the storage the pre-paint script reads back.
+	*/
+	const effectivePaint = paint ?? outerPaint;
 	const contextValue = React.useMemo(() => ({
 		theme,
 		manifest,
@@ -413,12 +449,14 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 		mode,
 		font,
 		styleSet: effectiveStyleSet,
+		paint: effectivePaint,
 		resolvedMode,
 		setTheme,
 		setDensity,
 		setMode,
 		setFont,
-		setStyleSet
+		setStyleSet,
+		setPaint
 	}), [
 		theme,
 		manifest,
@@ -426,12 +464,14 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 		mode,
 		font,
 		effectiveStyleSet,
+		effectivePaint,
 		resolvedMode,
 		setTheme,
 		setDensity,
 		setMode,
 		setFont,
-		setStyleSet
+		setStyleSet,
+		setPaint
 	]);
 	/** The axes on offer under the theme that is actually active. */
 	const registry = React.useMemo(() => buildRegistry(themes, theme), [themes, theme]);
@@ -490,7 +530,8 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 		"data-theme": theme,
 		"data-density": density,
 		"data-mode": mode,
-		...styleSet === null ? null : { "data-style": styleSet }
+		...styleSet === null ? null : { "data-style": styleSet },
+		...paint === null ? null : { "data-paint": paint }
 	};
 	let root;
 	if (asChild) {
@@ -514,7 +555,31 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 		"data-cue-overrides": "",
 		children: overridesStyle
 	});
-	return /* @__PURE__ */ jsx(ThemeRegistryContext.Provider, {
+	/**
+	* Base UI's own style elements, which this provider's nonce also has to reach.
+	*
+	* `@base-ui/react` renders one style element — a hoisted
+	* `<style precedence>` carrying `.base-ui-disable-scrollbar` — from
+	* `utils/styles.mjs`. `ScrollAreaRoot` and `SelectPopup` pass it a nonce they
+	* read from Base UI's own `CSPContext`, and nothing fills that context unless
+	* a `CSPProvider` is rendered above them. Without one it ships bare and a
+	* `style-src-elem` policy refuses it by content hash, on every page that
+	* renders a Select, a Popover or a ScrollArea — which is most authenticated
+	* pages of a real application, and no page of its sign-in screen. A consumer
+	* cannot reasonably guess that the fix lives in a peer dependency's provider,
+	* and this library already takes the nonce and already sits at the root.
+	*
+	* Rendered **only when a nonce was given**, and that is not tidiness. A
+	* consumer that wraps its own application in `CSPProvider` is the case this
+	* must not break: an unconditional inner provider would overwrite that outer
+	* context with `undefined` and un-nonce every Base UI style element in the
+	* tree — turning this into the bug it exists to fix.
+	*/
+	const withCspContext = (tree) => nonce === void 0 ? tree : /* @__PURE__ */ jsx(CSPProvider, {
+		nonce,
+		children: tree
+	});
+	return withCspContext(/* @__PURE__ */ jsx(ThemeRegistryContext.Provider, {
 		value: registry,
 		children: /* @__PURE__ */ jsx(ThemeContext.Provider, {
 			value: contextValue,
@@ -538,7 +603,7 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 				})
 			})
 		})
-	});
+	}));
 }
 //#endregion
 export { FontFamiliesContext, FontScaleContext, ThemeContext, ThemeProvider };

package/dist/system/vocabulary.d.ts

@@ -1,4 +1,4 @@
-import { StyleSet } from "@cueplusplus/tokens";
+import { Paint, StyleSet } from "@cueplusplus/tokens";
 import { Density as Density$1, DensityEntry, FontEntry, FontName, ThemeManifest } from "@cueplusplus/theme-base";
 //#region src/system/vocabulary.d.ts
 /** What the three registry hooks read: the manifests, and the axes the ACTIVE theme offers. */

package/dist/system/vocabulary.js

@@ -1,4 +1,4 @@
-import { DEFAULT_DENSITY, DEFAULT_FONT, STYLE_SETS } from "@cueplusplus/tokens";
+import { DEFAULT_DENSITY, DEFAULT_FONT, PAINTS, STYLE_SETS } from "@cueplusplus/tokens";
 import { DENSITIES, FONTS, THEME_NAME_PATTERN, resolveDensities, resolveFonts } from "@cueplusplus/theme-base";
 //#region src/system/vocabulary.ts
 /**
@@ -82,6 +82,18 @@ function vocabulary(themes) {
 function isStyleSet(value) {
 	return typeof value === "string" && STYLE_SETS.includes(value);
 }
+/**
+* Whether a value is one of the look packs.
+*
+* Standalone for exactly the reason {@link isStyleSet} is, and the reason reads
+* the same one axis over: no theme can add a pack. The vocabulary is emitted by
+* `@cueplusplus/tokens`, no manifest field describes it, so there is nothing
+* per-theme to ask and a per-theme signature would be parameters pretending to
+* be a rule.
+*/
+function isPaint(value) {
+	return typeof value === "string" && PAINTS.includes(value);
+}
 /** Derive the context value. Pure; the provider memoises it on `themes` and the active name. */
 function buildRegistry(themes, active) {
 	return {
@@ -122,4 +134,4 @@ function noteOnce(message) {
 	console.info(`[cue] ${message}`);
 }
 //#endregion
-export { buildRegistry, isStyleSet, noteOnce, vocabulary, warnOnce };
+export { buildRegistry, isPaint, isStyleSet, noteOnce, vocabulary, warnOnce };

package/manifest/components/accordion.json

@@ -145,7 +145,7 @@
     "--cue-space-4",
     "--cue-text-ui"
   ],
-  "summary": "A stack of sections, one (or several) open at a time.",
+  "summary": "A stack of sections, one or several open at a time.",
   "examples": [
     {
       "title": "Usage",
@@ -153,10 +153,23 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/accordion",
   "mdUrl": "/docs/components/accordion.md",
   "jsonUrl": "/r/components/accordion.json",
+  "whenToUse": [
+    "Several peer sections where the reader only needs one at a time: a settings page, a long form split by topic.",
+    "Anywhere the closed titles are themselves a useful table of contents."
+  ],
+  "whenNotToUse": [
+    "Exactly one section. Use `Collapsible` — it wears the same skin, so a lone section and a stack of them look alike by design.",
+    "Optional detail inside a form. Use `Disclosure`; a summary row that looks like a section header makes a form read as twice as long as it is.",
+    "Content the reader must compare side by side. Hiding one to see the other defeats the task."
+  ],
+  "commonMistakes": [
+    "Opening every section by default, which is a page with extra clicks in it.",
+    "Reimplementing the open-state bookkeeping. The disclosure ARIA and keyboard handling are Base UI's; this layer only adds the console skin."
+  ],
   "specimens": [
     {
       "title": "Accordion",
@@ -168,6 +181,5 @@
       "note": "Hairline-separated items with mono summary rows. Several can be open at once.",
       "interaction": "the whole header row is the trigger; the panel animates its height and stills under prefers-reduced-motion."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/activity-graph.json

@@ -84,10 +84,23 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/activity-graph",
   "mdUrl": "/docs/components/activity-graph.md",
   "jsonUrl": "/r/components/activity-graph.json",
+  "whenToUse": [
+    "Run volume over a date window, where the question is which days were busy rather than the exact number on any one of them.",
+    "A header that needs what is being counted on one side and a pre-formatted total opposite it."
+  ],
+  "whenNotToUse": [
+    "A window you need to fit a fixed width. Cells are fixed-size, so a long range scrolls horizontally rather than shrinking.",
+    "Anything that is not a date-and-count series: `data` is date and count pairs, and every gap in the window is filled as an empty cell."
+  ],
+  "commonMistakes": [
+    "Leaving `start` and `end` unset. heat-graph then draws a full year ending today, which will not match your data.",
+    "Bucketing the counts into levels yourself. Levels are classified for you from `data`.",
+    "Passing a raw number to `total`. It is printed as given, so format it first."
+  ],
   "specimens": [
     {
       "title": "ActivityGraph",
@@ -99,6 +112,5 @@
       "note": "Half a year of runs as a calendar of cells, dense where the work was. It is the one element in the family with a runtime dependency of its own — `heat-graph`, an optional peer — which does the calendar arithmetic and the levelling; everything you can see here is cue's, from the five-step ramp in the streaming hue down to the legend. Cells are a fixed size, so a long window scrolls sideways rather than shrinking into a smudge.",
       "interaction": "none. The five legend swatches are `aria-hidden` and sit between the words less and more, which is what carries the scale."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/agent-card.json

@@ -130,10 +130,23 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/agent-card",
   "mdUrl": "/docs/components/agent-card.md",
   "jsonUrl": "/r/components/agent-card.json",
+  "whenToUse": [
+    "A directory or picker where someone chooses an agent before the conversation starts.",
+    "Advertising named capabilities alongside the provider, version, model and endpoint behind them."
+  ],
+  "whenNotToUse": [
+    "Reporting what an agent is doing right now. The card is a standing description of the agent, not a live state.",
+    "An endpoint that has to be read in full. `endpoint` truncates rather than wraps."
+  ],
+  "commonMistakes": [
+    "Rendering your own Connected label beside the action. `connected` already swaps the action for a settled Connected state and disables it.",
+    "Writing a paragraph into `description`. It is sized for one or two sentences.",
+    "Leaving `onConnect` off while `connected` is false, which shows an action with nowhere to go."
+  ],
   "specimens": [
     {
       "title": "AgentCard",
@@ -145,6 +158,5 @@
       "note": "Who you are about to talk to, before you talk to it: the name and who publishes it, one paragraph on what it is for, the skills it advertises, and — in mono along the bottom — the model and the endpoint actually behind it. Those last two are the line that separates a card from a marketing tile.",
       "interaction": "the action is the only control. Connected disables it and swaps the ink button for a settled field row with a tick, rather than greying out a button that still looks pressable."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/agent-handoff.json

@@ -84,10 +84,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/agent-handoff",
   "mdUrl": "/docs/components/agent-handoff.md",
   "jsonUrl": "/r/components/agent-handoff.json",
+  "whenToUse": [
+    "The moment one agent gives the baton to another in a transcript that would otherwise jump.",
+    "Showing which pieces of context travelled across with it."
+  ],
+  "whenNotToUse": [
+    "A handoff you cannot explain. `reason` is required because without it a handoff reads as an unexplained jump.",
+    "A step inside a single agent's own work — this element is about the boundary between two of them."
+  ],
+  "commonMistakes": [
+    "Omitting `carried` to hide the context section. Pass an empty array instead; it is a required prop.",
+    "Leaving `settled` false once the receiving agent is underway, so the arrow and the receiving badge keep signalling a transition that already finished."
+  ],
   "specimens": [
     {
       "title": "AgentHandoff",
@@ -99,6 +111,5 @@
       "note": "The baton moving, with the reason attached. Two badges and an arrow: while the handoff is live the receiving agent and the arrow take the streaming hue, and `settled` cools both once the new agent is actually underway. What travelled across is listed under it against a rule — a handoff with no carried context is a handoff you cannot audit.",
       "interaction": "none. It is a record of something that happened, not a control; the only thing that moves is the colour, over half a second."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/agent-mode-badge.json

@@ -82,10 +82,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/agent-mode-badge",
   "mdUrl": "/docs/components/agent-mode-badge.md",
   "jsonUrl": "/r/components/agent-mode-badge.json",
+  "whenToUse": [
+    "Anywhere a person needs the run's authority from the corner of their eye — the fact every catalogue leaves to prose.",
+    "As the source for mode-aware styling elsewhere: put the same `data-agent-mode` on a composer and its focus ring, send button and rail tint from one place."
+  ],
+  "whenNotToUse": [
+    "A status. Use `AgentStatus` — authority and activity are different questions."
+  ],
+  "commonMistakes": [
+    "Threading a mode prop through components instead of reusing the attribute. `elements.css` declares four custom properties under `data-agent-mode`, so a console adds a mode-aware surface by reading a property rather than by branching."
+  ],
   "specimens": [
     {
       "title": "AgentModeBadge",
@@ -97,6 +107,5 @@
       "note": "How much authority the run is holding, which is the fact a person most needs from the corner of their eye and the one every catalogue leaves to prose. The ladder is four rungs — will it ask me, is it writing, is it only planning, are the guardrails off — because that is how many accents every product in the study paints, whatever it calls its six or seven or nine modes. The chip is the readout; `data-agent-mode` is the part that travels.",
       "interaction": "press the chip to cycle the rung. The second specimen is the whole point: one attribute on the box, and the rail, the border and the send button all re-derive from `var(--cue-elements-mode-icon)` with no prop threading and no branch in any component. Colour is never alone — each rung has its own glyph and its own word, so the ladder survives a monochrome screenshot."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/agent-pile.json

@@ -127,10 +127,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/agent-pile",
   "mdUrl": "/docs/components/agent-pile.md",
   "jsonUrl": "/r/components/agent-pile.json",
+  "whenToUse": [
+    "A multi-agent run where who is involved matters more than what each is doing right now.",
+    "Anywhere the states must be legible without colour — crown, spinning arc and `?` badge each also go into the accessible name."
+  ],
+  "whenNotToUse": [
+    "One agent. An `Avatar` says it with less.",
+    "A list the reader must act on. A pile is a summary."
+  ],
+  "commonMistakes": [
+    "Adding a colour-only state of your own, which breaks the rule the three built-in states follow."
+  ],
   "specimens": [
     {
       "title": "AgentPile",
@@ -142,6 +153,5 @@
       "note": "Faces at −12px overlap, fanning to +4px on hover. The crown marks the orchestrator, an arc marks work in flight and a `?` marks an agent waiting on an answer.",
       "interaction": "every face is a button with the agent's name; the pile is one tab stop and arrow keys move inside it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/agent-plan.json

@@ -54,10 +54,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/agent-plan",
   "mdUrl": "/docs/components/agent-plan.md",
   "jsonUrl": "/r/components/agent-plan.json",
+  "whenToUse": [
+    "An ordered set of steps the agent walks front to back, with one of them currently running."
+  ],
+  "whenNotToUse": [
+    "Work that fans out and rejoins. `steps` is a flat array worked through in order.",
+    "A checklist a person ticks. Progress is driven entirely by `activeIndex`, not by input."
+  ],
+  "commonMistakes": [
+    "Clamping `activeIndex` before passing it. Values past the end already mark every step done, and values before the start mark none.",
+    "Passing rich nodes as steps. `steps` is `readonly string[]`."
+  ],
   "specimens": [
     {
       "title": "AgentPlan",
@@ -69,6 +80,5 @@
       "note": "The checklist the agent published before it started, with one index driving the whole thing: steps before it are done, the step at it is running, steps after it are waiting. An index past the end marks every step done.",
       "interaction": "none. A plan is a readout; the agent moves it, not the reader."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/agent-status.json

@@ -67,10 +67,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/agent-status",
   "mdUrl": "/docs/components/agent-status.md",
   "jsonUrl": "/r/components/agent-status.json",
+  "whenToUse": [
+    "A standing status pill beside a run: working, waiting, or done with a check.",
+    "Showing how long it has been going, which renders in mono when `elapsed` is provided."
+  ],
+  "whenNotToUse": [
+    "A failure. The three states are working, waiting and done — there is no error mode.",
+    "A multi-line explanation. `label` is a short status line."
+  ],
+  "commonMistakes": [
+    "Formatting the clock into `label`. `elapsed` is its own prop and gets the mono treatment.",
+    "Leaving `state=\"working\"` on a finished run, which keeps the pill signalling activity after there is nothing left to do."
+  ],
   "specimens": [
     {
       "title": "AgentStatus",
@@ -82,6 +94,5 @@
       "note": "One pill that always answers the two questions a run raises: what is it doing, and for how long. Working shimmers, waiting is still and marked, done carries a check and the elapsed total.",
       "interaction": "the trailing control is a labelled icon button that pauses a run and offers to run it again once it is done."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/agent-surface.json

@@ -73,10 +73,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/agent-surface",
   "mdUrl": "/docs/components/agent-surface.md",
   "jsonUrl": "/r/components/agent-surface.json",
+  "whenToUse": [
+    "A region of the elements family that must repaint wholesale — a different skin or fidelity — with no prop threading and no branch in any component."
+  ],
+  "whenNotToUse": [
+    "One component's appearance. Use that component's own props.",
+    "Density. Use `Density`."
+  ],
+  "commonMistakes": [
+    "Reading the React context to style something. The attributes do the work — `elements.css` re-declares the `--cue-*` tokens under them and custom properties inherit. The context exists for the one place that cannot see the DOM: an overlay portalled to `<body>` from inside the island."
+  ],
   "specimens": [
     {
       "title": "AgentSurface",
@@ -88,6 +98,5 @@
       "note": "One DOM, three paint jobs. The same three tool calls sit in all three specimens; the only difference is the pair of attributes on the box around them. skin='aui' re-points the colour set to assistant-ui's own inks and grounds, and fidelity='upstream' re-points the metrics too, which is what stops cue's density ladder at the island edge. Without @cueplusplus/ui/elements.css imported, all three would look alike.",
       "interaction": "none of its own. The island is a values-set, not a control: everything inside keeps the behaviour it has outside."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/alert-dialog.json

@@ -185,7 +185,8 @@
     "--cue-surface-2",
     "--cue-text-emphasis",
     "--cue-text-label",
-    "--cue-text-ui"
+    "--cue-text-ui",
+    "--cue-tracking-caps"
   ],
   "summary": "A modal that asks one question with two answers, for anything irreversible.",
   "examples": [
@@ -195,10 +196,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/alert-dialog",
   "mdUrl": "/docs/components/alert-dialog.md",
   "jsonUrl": "/r/components/alert-dialog.json",
+  "whenToUse": [
+    "A rare, expensive, irreversible action — dropping a database, discarding unsaved work.",
+    "Anywhere an accidental outside click must not dismiss the question."
+  ],
+  "whenNotToUse": [
+    "A routine destructive action. Use `TwoStepButton`: a dialog in front of something people do twenty times an hour only teaches them to dismiss dialogs.",
+    "Anything with more than two answers. Use `Dialog`."
+  ],
+  "commonMistakes": [
+    "Reaching for `Dialog` instead. The difference is not cosmetic — this takes `role=\"alertdialog\"` and refuses outside-press dismissal, which is the whole point.",
+    "Labelling the buttons 'OK' and 'Cancel'. Name the action: 'Delete patch' says what OK does."
+  ],
   "specimens": [
     {
       "title": "AlertDialog",
@@ -210,6 +223,5 @@
       "note": "The destructive twin: no scrim dismissal, no close button, and an explicit pair of Cancel and Action.",
       "interaction": "Escape is deliberately not enough on its own; the action has to be chosen."
     }
-  ],
-  "todo": true
+  ]
 }