@cueplusplus/ui 0.9.0 → 0.11.0

package/dist/layout/preview.js

@@ -0,0 +1,459 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { useIsomorphicLayoutEffect } from "../system/use-isomorphic-layout-effect.js";
+import { AmbientThemeContext, DensityContext } from "../system/density.js";
+import { OverridesContext } from "../system/overrides.js";
+import { ThemeContext } from "../system/theme-provider.js";
+import * as React from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/layout/preview.tsx
+const RESIZE_DEFAULTS = {
+	axis: "both",
+	minWidth: 160,
+	maxWidth: 1280,
+	minHeight: 96,
+	maxHeight: 960
+};
+/** One arrow press, in px, and one Shift+arrow press. */
+const STEP = 8;
+const BIG_STEP = 64;
+const ROOT_CLASS = "relative flex min-w-0 flex-col rounded-(--radius-surface) border border-border bg-surface-1 text-fg";
+const BENCH_CLASS = "relative flex min-w-0 flex-1 overflow-auto rounded-t-(--radius-surface)";
+/**
+* The stage: centred, dotted in the stage's own `--cue-hair-strong`, and at
+* least three top rungs of the space ladder tall so a preview reserves its room
+* before its specimen arrives. Static literals, because Tailwind scans text.
+*
+* Centred **safely** (`place-items: safe center`): a specimen wider than the
+* stage starts at the stage's edge and overflows at its end, where the bench
+* scrolls to it. Plain `center` split the overflow across both sides, and the
+* left half sat before the scroll origin, where nothing reaches it.
+*/
+const STAGE_CLASS = "grid h-full w-full min-h-[calc(var(--cue-space-8)*3)] place-items-center-safe bg-surface-1 bg-[radial-gradient(circle,var(--cue-hair-strong)_1px,transparent_1.3px)] bg-[length:14px_14px] p-(--cue-space-6) text-fg";
+const TOOLS_CLASS = "absolute top-(--cue-space-2) right-(--cue-space-2) z-10 flex items-center gap-px rounded-(--radius-control) border border-border bg-surface-2 p-px";
+/**
+* The room the tools take, kept clear on the stage — only when there are tools.
+*
+* The tools sit over the stage's top right, so a specimen that reached that
+* corner sat under them, and its own controls there with it: the index's
+* Calendar paged by an arrow the wrench was drawn over. So a Preview with tools
+* pads its stage's top by the tools' whole depth — their offset, their height
+* (an `sm` control, plus the one-pixel border and padding on each side), and one
+* rung of space below them.
+*
+* **Declared on the bench and read on the stage**, because the two sit in
+* different densities: the tools are drawn in the page's, and the stage may set
+* its own. A custom property's `var()`s are resolved where it is declared, so
+* the stage inherits the depth measured at the page's rung — a compact stage
+* still clears tools drawn at the page's size. And **only with tools**: a bare
+* Preview carries none of it, which is the one the docs' front page draws
+* seventeen times under a byte ceiling.
+*/
+const TOOLS_RESERVE_BENCH = "[--preview-tools-clear:calc(var(--cue-space-2)*2+var(--cue-control-sm)+4px)]";
+const TOOLS_RESERVE_STAGE = "pt-(--preview-tools-clear)";
+const FOOTER_CLASS = "flex min-w-0 items-center gap-(--cue-space-2) border-t border-border px-(--cue-space-4) py-(--cue-space-2)";
+const GRIP_FOCUS = "touch-none outline-none hover:bg-(--cue-border-strong) focus-visible:bg-accent";
+const GRIP_X_CLASS = `absolute top-0 right-0 z-10 h-full w-(--cue-space-2) cursor-col-resize ${GRIP_FOCUS}`;
+const GRIP_Y_CLASS = `absolute bottom-0 left-0 z-10 h-(--cue-space-2) w-full cursor-row-resize ${GRIP_FOCUS}`;
+const GRIP_CORNER_CLASS = "absolute right-0 bottom-0 z-20 size-(--cue-space-4) cursor-nwse-resize touch-none";
+const READOUT_CLASS = "pointer-events-none absolute right-(--cue-space-5) bottom-(--cue-space-5) z-20 rounded-(--radius-control) bg-surface-3 px-(--cue-space-2) py-px font-mono text-(length:--cue-text-label) text-fg-muted";
+function clamp(value, min, max) {
+	return Math.min(max, Math.max(min, value));
+}
+/** The bounds a `resizable` prop means, or `null` for a fixed stage. */
+function resolveResize(resizable) {
+	if (resizable === void 0 || resizable === false) return null;
+	const given = resizable === true ? {} : resizable;
+	return {
+		axis: given.axis ?? RESIZE_DEFAULTS.axis,
+		minWidth: given.minWidth ?? RESIZE_DEFAULTS.minWidth,
+		maxWidth: given.maxWidth ?? RESIZE_DEFAULTS.maxWidth,
+		minHeight: given.minHeight ?? RESIZE_DEFAULTS.minHeight,
+		maxHeight: given.maxHeight ?? RESIZE_DEFAULTS.maxHeight
+	};
+}
+/**
+* The room the stage has: the bench's inline size in whole px, measured at
+* mount and again whenever a `ResizeObserver` says the bench changed — the
+* viewport resizing, a grid track reflowing around it.
+*
+* `null` means "no bound from the room". That covers a fixed Preview, which
+* measures and observes nothing, so a frame without `resizable` costs no
+* observer. It covers a bench that measures 0, which is not laid out
+* (`display: none`, detached, or jsdom). And it covers the first render, which
+* is also the server's, so the markup a server writes and the first client
+* render agree. A host with no `ResizeObserver` gets the measurement at mount
+* and nothing after, as `elements/clamp.tsx` does.
+*/
+function useAvailableWidth(bench, enabled) {
+	const [available, setAvailable] = React.useState(null);
+	useIsomorphicLayoutEffect(() => {
+		const node = bench.current;
+		if (!enabled || node === null) return;
+		const measure = () => {
+			const width = Math.floor(node.getBoundingClientRect().width);
+			setAvailable(width > 0 ? width : null);
+		};
+		measure();
+		if (typeof ResizeObserver === "undefined") return;
+		const observer = new ResizeObserver(measure);
+		observer.observe(node);
+		return () => observer.disconnect();
+	}, [bench, enabled]);
+	return available;
+}
+/**
+* The bounds in force: the given ones, with the widest narrowed to the room
+* the bench has, so a stage never outgrows the frame — or the grid track — it
+* sits in. A room narrower than `minWidth` brings the floor down with it,
+* because a floor wider than the room is a stage that overhangs its tile.
+* Height takes no bound from the room: a taller stage grows its frame.
+*/
+function effectiveBounds(options, available) {
+	if (available === null) return options;
+	const maxWidth = Math.min(options.maxWidth, available);
+	return {
+		...options,
+		maxWidth,
+		minWidth: Math.min(options.minWidth, maxWidth)
+	};
+}
+/**
+* The attributes the stage carries — and, when nothing is asked, none at all.
+*
+* Inheriting is the *absence* of attributes, which is why every branch below
+* is conditional. Three branches add a second attribute, each for a reason in
+* the stylesheets rather than in taste.
+*
+* A theme's light block is the compound selector
+* `[data-theme="t"][data-mode="light"]`, so a mode with no theme restates the
+* page's theme on the same element. Read the other way, a theme with no mode
+* repeats the page's mode. Otherwise the stage would match the theme's dark
+* block under a light page, while every popup opened on it came up light:
+* popups are stamped from the context `StageScope` publishes, which carries
+* the page's mode.
+*
+* A theme's density overrides are addressed through `data-cue-theme`, the
+* stamp `<Density>` writes, so a density names the nearest theme the same way.
+*/
+function stageAttributes(asked, page) {
+	const attributes = {};
+	const scoped = asked.theme ?? (asked.mode === void 0 ? null : page?.theme ?? null);
+	if (scoped !== null) attributes["data-theme"] = scoped;
+	const moded = asked.mode ?? (asked.theme === void 0 ? void 0 : page?.mode);
+	if (moded !== void 0) attributes["data-mode"] = moded;
+	if (asked.density !== void 0) {
+		attributes["data-density"] = asked.density;
+		const nearest = asked.theme ?? page?.theme ?? null;
+		if (nearest !== null) attributes["data-cue-theme"] = nearest;
+	}
+	if (asked.font !== void 0) attributes["data-font"] = asked.font;
+	return attributes;
+}
+/**
+* The contexts the stage republishes, so an overlay opened on it follows it.
+*
+* `useCuePortalProps()` stamps a portal container from `ThemeContext` and
+* `DensityContext`; a popup mounts on `<body>` and inherits nothing from the
+* stage's DOM. So the stage's subtree reads a theme context with the stage's
+* theme and mode, and a density context with the stage's rung. The tools and
+* footer are outside this subtree, so what they open follows the page. A theme
+* the provider did not register leaves `manifest` null, which is what
+* `useTheme()` already reports for a name nobody registered.
+*/
+function StageScope({ theme, mode, density, children }) {
+	const outer = React.useContext(ThemeContext);
+	const outerOverrides = React.useContext(OverridesContext);
+	const outerDensity = React.useContext(DensityContext);
+	const outerAmbient = React.useContext(AmbientThemeContext);
+	const value = React.useMemo(() => {
+		if (outer === null || theme === void 0 && mode === void 0) return outer;
+		const scoped = theme ?? outer.theme;
+		return {
+			...outer,
+			theme: scoped,
+			manifest: scoped === outer.theme ? outer.manifest : null,
+			mode: mode ?? outer.mode,
+			resolvedMode: mode === "dark" || mode === "light" ? mode : outer.resolvedMode
+		};
+	}, [
+		outer,
+		theme,
+		mode
+	]);
+	const stamped = theme !== void 0 || mode !== void 0;
+	return /* @__PURE__ */ jsx(AmbientThemeContext.Provider, {
+		value: theme ?? outerAmbient,
+		children: /* @__PURE__ */ jsx(DensityContext.Provider, {
+			value: density ?? outerDensity,
+			children: /* @__PURE__ */ jsx(OverridesContext.Provider, {
+				value: stamped ? null : outerOverrides,
+				children: /* @__PURE__ */ jsx(ThemeContext.Provider, {
+					value,
+					children
+				})
+			})
+		})
+	});
+}
+/**
+* The stage's size: explicit per axis once a reader has moved it, and the size
+* the layout gives it before that — `null` on an axis, which is also what a
+* double-click returns an axis to.
+*
+* An axis nobody set is measured live, not once. Its value is what the grip
+* announces on focus, before any key, and where the first key or drag starts
+* from, so it has to follow the sizer at rest: the track widening under it, the
+* specimen growing after mount (every listing specimen loads behind a
+* skeleton), a Preview mounted hidden and shown later. Observing the bench is
+* not enough for that. The bench reports a width, and a specimen that grows
+* moves only the height, so the sizer is observed as well, for as long as any
+* axis is unset.
+*/
+function useStageSize(options) {
+	const sizer = React.useRef(null);
+	const [width, setWidth] = React.useState(null);
+	const [height, setHeight] = React.useState(null);
+	const [natural, setNatural] = React.useState({
+		width: 0,
+		height: 0
+	});
+	const [drag, setDrag] = React.useState(null);
+	const enabled = options !== null;
+	const widthSet = width !== null;
+	const heightSet = height !== null;
+	useIsomorphicLayoutEffect(() => {
+		const node = sizer.current;
+		if (!enabled || node === null || widthSet && heightSet) return;
+		const measure = () => {
+			const rect = node.getBoundingClientRect();
+			setNatural((previous) => {
+				const next = {
+					width: widthSet ? previous.width : Math.round(rect.width),
+					height: heightSet ? previous.height : Math.round(rect.height)
+				};
+				return next.width === previous.width && next.height === previous.height ? previous : next;
+			});
+		};
+		measure();
+		if (typeof ResizeObserver === "undefined") return;
+		const observer = new ResizeObserver(measure);
+		observer.observe(node);
+		return () => observer.disconnect();
+	}, [
+		enabled,
+		widthSet,
+		heightSet
+	]);
+	return {
+		sizer,
+		width,
+		height,
+		setWidth,
+		setHeight,
+		shownWidth: options === null ? 0 : clamp(width ?? natural.width, options.minWidth, options.maxWidth),
+		shownHeight: options === null ? 0 : clamp(height ?? natural.height, options.minHeight, options.maxHeight),
+		drag,
+		setDrag
+	};
+}
+/** The two keyboard-operable edges, the corner, and the readout. Chrome, never stage. */
+function Grips({ label, options, size }) {
+	const { shownWidth, shownHeight, drag, setDrag, setWidth, setHeight } = size;
+	const stepWidth = (event) => {
+		const step = event.shiftKey ? BIG_STEP : STEP;
+		let next = null;
+		if (event.key === "ArrowRight") next = shownWidth + step;
+		else if (event.key === "ArrowLeft") next = shownWidth - step;
+		else if (event.key === "Home") next = options.minWidth;
+		else if (event.key === "End") next = options.maxWidth;
+		if (next === null) return;
+		event.preventDefault();
+		setWidth(clamp(next, options.minWidth, options.maxWidth));
+	};
+	const stepHeight = (event) => {
+		const step = event.shiftKey ? BIG_STEP : STEP;
+		let next = null;
+		if (event.key === "ArrowDown") next = shownHeight + step;
+		else if (event.key === "ArrowUp") next = shownHeight - step;
+		else if (event.key === "Home") next = options.minHeight;
+		else if (event.key === "End") next = options.maxHeight;
+		if (next === null) return;
+		event.preventDefault();
+		setHeight(clamp(next, options.minHeight, options.maxHeight));
+	};
+	const pointer = (axis) => ({
+		onPointerDown: (event) => {
+			if (event.button !== 0) return;
+			event.preventDefault();
+			event.currentTarget.setPointerCapture?.(event.pointerId);
+			setDrag({
+				axis,
+				x: event.clientX,
+				y: event.clientY,
+				width: shownWidth,
+				height: shownHeight
+			});
+		},
+		onPointerMove: (event) => {
+			if (drag === null) return;
+			if (drag.axis !== "y") setWidth(clamp(drag.width + event.clientX - drag.x, options.minWidth, options.maxWidth));
+			if (drag.axis !== "x") setHeight(clamp(drag.height + event.clientY - drag.y, options.minHeight, options.maxHeight));
+		},
+		onPointerUp: (event) => {
+			if (drag === null) return;
+			event.currentTarget.releasePointerCapture?.(event.pointerId);
+			setDrag(null);
+		},
+		onPointerCancel: () => setDrag(null)
+	});
+	return /* @__PURE__ */ jsxs(Fragment, { children: [
+		options.axis === "y" ? null : /* @__PURE__ */ jsx("div", {
+			role: "separator",
+			tabIndex: 0,
+			"aria-orientation": "vertical",
+			"aria-label": `Resize ${label} width`,
+			"aria-valuenow": shownWidth,
+			"aria-valuemin": options.minWidth,
+			"aria-valuemax": options.maxWidth,
+			"aria-valuetext": `${shownWidth} pixels wide`,
+			"data-slot": "preview-grip-x",
+			className: GRIP_X_CLASS,
+			onKeyDown: stepWidth,
+			onDoubleClick: () => setWidth(null),
+			...pointer("x")
+		}),
+		options.axis === "x" ? null : /* @__PURE__ */ jsx("div", {
+			role: "separator",
+			tabIndex: 0,
+			"aria-orientation": "horizontal",
+			"aria-label": `Resize ${label} height`,
+			"aria-valuenow": shownHeight,
+			"aria-valuemin": options.minHeight,
+			"aria-valuemax": options.maxHeight,
+			"aria-valuetext": `${shownHeight} pixels tall`,
+			"data-slot": "preview-grip-y",
+			className: GRIP_Y_CLASS,
+			onKeyDown: stepHeight,
+			onDoubleClick: () => setHeight(null),
+			...pointer("y")
+		}),
+		options.axis === "both" ? /* @__PURE__ */ jsx("div", {
+			"aria-hidden": "true",
+			"data-slot": "preview-grip-corner",
+			className: GRIP_CORNER_CLASS,
+			onDoubleClick: () => {
+				setWidth(null);
+				setHeight(null);
+			},
+			...pointer("both")
+		}) : null,
+		drag === null ? null : /* @__PURE__ */ jsx("span", {
+			"aria-hidden": "true",
+			"data-slot": "preview-readout",
+			className: READOUT_CLASS,
+			children: `${shownWidth} × ${shownHeight}`
+		})
+	] });
+}
+/**
+* A frame for one component: a stage that is its own theme island, a slot for
+* tools at the top right, and a footer.
+*
+* **The stage is the island; the chrome is not.** `theme`, `mode`, `density`
+* and `font` land on the stage element only, and the stage republishes the
+* theme and density contexts so an overlay opened on it follows it. The tools,
+* the footer, the grips and anything they open stay in the scope around the
+* Preview — a `terminal` preview's own controls do not turn cyan. With none of
+* the four set, the stage carries no attribute and costs what a `<div>` costs.
+* A stage `theme` with no `mode` repeats the page's mode beside it.
+*
+* **`resizable` is handles of its own**, both axes by default: an edge grip per
+* axis that is a keyboard-operable `separator` valued in pixels, and a corner
+* grip for the pointer. Double-click resets an axis. The width never outgrows
+* the frame: its bound in force is the frame's own width, observed live, when
+* that is under `maxWidth`. Not `Resizable`, which is split panes on an
+* optional peer.
+*
+* Props, not a compound: one stage and two slots, each saying what it is.
+*
+* @example
+* <Preview label="Button preview" tools={<IconButton aria-label="Configure Button" icon={Wrench} />}>
+*   <Button variant="primary">Take cue</Button>
+* </Preview>
+* @example
+* <Preview label="Chip preview" theme="terminal" density="compact" resizable>
+*   <Chip tone="accent">Standby</Chip>
+* </Preview>
+*/
+const Preview = React.forwardRef(function Preview({ children, label, theme, mode, density, font, resizable, tools, footer, className, ...elementProps }, ref) {
+	const outer = React.useContext(ThemeContext);
+	const bench = React.useRef(null);
+	const given = resolveResize(resizable);
+	const available = useAvailableWidth(bench, given !== null);
+	const options = given === null ? null : effectiveBounds(given, available);
+	const size = useStageSize(options);
+	const attributes = stageAttributes({
+		theme,
+		mode,
+		density,
+		font
+	}, outer);
+	const stage = /* @__PURE__ */ jsx("div", {
+		"data-slot": "preview-stage",
+		...attributes,
+		className: cn(STAGE_CLASS, options !== null && "flex-1", tools !== void 0 && TOOLS_RESERVE_STAGE),
+		style: size.height === null ? void 0 : { minHeight: 0 },
+		children: /* @__PURE__ */ jsx(StageScope, {
+			theme,
+			mode,
+			density,
+			children
+		})
+	});
+	return /* @__PURE__ */ jsxs("div", {
+		...elementProps,
+		ref,
+		role: "group",
+		"aria-label": label,
+		"data-slot": "preview",
+		className: cn(ROOT_CLASS, options !== null && "w-full", className),
+		children: [
+			/* @__PURE__ */ jsx("div", {
+				ref: bench,
+				"data-slot": "preview-bench",
+				className: cn(BENCH_CLASS, footer === void 0 && "rounded-b-(--radius-surface)", tools !== void 0 && TOOLS_RESERVE_BENCH),
+				children: options === null ? stage : /* @__PURE__ */ jsxs("div", {
+					ref: size.sizer,
+					"data-slot": "preview-sizer",
+					className: cn("relative flex flex-col", size.width === null && "w-full"),
+					style: {
+						width: size.width === null ? void 0 : `${size.shownWidth}px`,
+						height: size.height === null ? void 0 : `${size.shownHeight}px`,
+						minWidth: `${options.minWidth}px`,
+						maxWidth: `${options.maxWidth}px`,
+						minHeight: `${options.minHeight}px`,
+						maxHeight: `${options.maxHeight}px`
+					},
+					children: [stage, /* @__PURE__ */ jsx(Grips, {
+						label,
+						options,
+						size
+					})]
+				})
+			}),
+			tools === void 0 ? null : /* @__PURE__ */ jsx("div", {
+				"data-slot": "preview-tools",
+				className: TOOLS_CLASS,
+				children: tools
+			}),
+			footer === void 0 ? null : /* @__PURE__ */ jsx("div", {
+				"data-slot": "preview-footer",
+				className: FOOTER_CLASS,
+				children: footer
+			})
+		]
+	});
+});
+//#endregion
+export { Preview };

package/dist/primitives/button.d.ts

@@ -26,6 +26,18 @@ interface ButtonProps extends React.ComponentPropsWithoutRef<"button">, VariantP
    * level without the caller passing a pixel size.
    */
   icon?: React.ElementType;
+  /**
+   * The label. A button with no children and no other accessible name is a
+   * control a screen reader announces as nothing.
+   *
+   * Declared explicitly, although `React.ComponentPropsWithoutRef<"button">`
+   * already carries it, for the reason `Card.Header` and `Bento.Tile` declare
+   * theirs: docgen documents a prop only where the library *declares* it, so
+   * without this line the manifest files no `children` for the system's most
+   * used control — the props table omits it, and a propSet cannot name it,
+   * which is how `/play/button` came to preview an unlabelled `<button>`.
+   */
+  children?: React.ReactNode;
 }
 /**
  * The system's primary action control.

package/dist/primitives/chip.d.ts

@@ -30,7 +30,7 @@ import * as React from "react";
  * <span className={chipVariants({ variant: "tag" })}>mcp</span>
  */
 declare const chipVariants: (props?: ({
-  tone?: "info" | "warn" | "danger" | "accent" | "ok" | "busy" | "neutral" | null | undefined;
+  tone?: "danger" | "info" | "warn" | "accent" | "ok" | "busy" | "neutral" | null | undefined;
   variant?: "outline" | "tinted" | "tag" | null | undefined;
   interactive?: boolean | null | undefined;
 } & ClassProp) | undefined) => string;

package/dist/system/index.d.ts

@@ -1,4 +1,4 @@
-import { TokenOverrides } from "./overrides.js";
+import { TokenOverrides, isSafeTokenValue } from "./overrides.js";
 import { FontFamilies, ResolvedMode, ThemeContextValue, ThemeProvider, ThemeProviderProps } from "./theme-provider.js";
 import { Density, DensityProps } from "./density.js";
 import { CuePortalFrame, CuePortalFrameProps, useCuePortalProps } from "./portal.js";
@@ -8,4 +8,4 @@ import { useDensities, useFonts, useThemes } from "./theme-registry.js";
 import { ControlSize, useControlHeight, useDensity } from "./use-density.js";
 import { useTheme } from "./use-theme.js";
 import { Density as DensityLevel, DensityEntry, FontEntry, FontName, Mode, ThemeManifest, ThemeName } from "@cueplusplus/theme-base";
-export { type ControlSize, CuePortalFrame, type CuePortalFrameProps, DEFAULT_STORAGE_KEY, Density, type DensityEntry, type DensityLevel, type DensityProps, type FontEntry, type FontFamilies, type FontName, type Mode, type PersistedPreferences, type PrepaintDefaults, type PrepaintOptions, type ResolvedMode, type ThemeContextValue, type ThemeManifest, type ThemeName, ThemeProvider, type ThemeProviderProps, type ThemeRegistry, type TokenOverrides, prepaintScript, useControlHeight, useCuePortalProps, useDensities, useDensity, useFonts, useTheme, useThemes };
+export { type ControlSize, CuePortalFrame, type CuePortalFrameProps, DEFAULT_STORAGE_KEY, Density, type DensityEntry, type DensityLevel, type DensityProps, type FontEntry, type FontFamilies, type FontName, type Mode, type PersistedPreferences, type PrepaintDefaults, type PrepaintOptions, type ResolvedMode, type ThemeContextValue, type ThemeManifest, type ThemeName, ThemeProvider, type ThemeProviderProps, type ThemeRegistry, type TokenOverrides, isSafeTokenValue, prepaintScript, useControlHeight, useCuePortalProps, useDensities, useDensity, useFonts, useTheme, useThemes };

package/dist/system/index.js

@@ -1,8 +1,9 @@
 import { Density } from "./density.js";
+import { isSafeTokenValue } from "./overrides.js";
 import { DEFAULT_STORAGE_KEY, prepaintScript } from "./prepaint.js";
 import { useDensities, useFonts, useThemes } from "./theme-registry.js";
 import { ThemeProvider } from "./theme-provider.js";
 import { CuePortalFrame, useCuePortalProps } from "./portal.js";
 import { useControlHeight, useDensity } from "./use-density.js";
 import { useTheme } from "./use-theme.js";
-export { CuePortalFrame, DEFAULT_STORAGE_KEY, Density, ThemeProvider, prepaintScript, useControlHeight, useCuePortalProps, useDensities, useDensity, useFonts, useTheme, useThemes };
+export { CuePortalFrame, DEFAULT_STORAGE_KEY, Density, ThemeProvider, isSafeTokenValue, prepaintScript, useControlHeight, useCuePortalProps, useDensities, useDensity, useFonts, useTheme, useThemes };

package/dist/system/overrides.d.ts

@@ -39,5 +39,42 @@ interface TokenOverrides {
     display: string;
   }>;
 }
+/**
+ * Whether a string may be written into the density stylesheet this module
+ * builds.
+ *
+ * The same rule {@link overridesCss} applies at `SAFE_VALUE`, exported because a
+ * caller that builds a {@link TokenOverrides} wants to refuse a value at the
+ * *input* rather than watch it be dropped, silently and one warning later, at
+ * the sheet. A panel that cannot ask the question has two bad answers open to
+ * it: keep a second copy of this regex, which stops being this regex the first
+ * time either moves, or write the value anyway and let a reader wonder why the
+ * picture did not change.
+ *
+ * `@cueplusplus/ui/configurator` exports `isSafeCssValue` (`configurator/_overrides.ts:239`)
+ * for the configurator's own snapshot, and this is deliberately **not** that
+ * function: same rule, asked from the module that owns it, without dragging in
+ * a subpath that also carries `ThemeConfigurator`, `ExportDialog` and an
+ * optional `react-aria-components` peer. Neither imports the other, and the
+ * test beside this file is what holds them to one answer.
+ *
+ * **The one thing the rule does not cover, said out loud: an unterminated
+ * `/*`.** It carries none of the five refused characters, so it is accepted and
+ * written, and everything after it in that stylesheet — the closing brace and
+ * any later declaration — is inside a comment. That is a value of the caller's
+ * own that stops their *other* overrides applying, not an injection: with `;`,
+ * `{`, `}`, `<` and `\` all refused, no second value can close the comment and
+ * open a rule. A caller that wants to refuse it as well can say so on top of
+ * this; tightening `SAFE_VALUE` itself would change what `overridesCss` writes,
+ * which is a different release note from this one.
+ *
+ * @param value - The proposed declaration value.
+ * @returns `true` when it cannot close its declaration, its block or the
+ *   `<style>` element — see the comment case above for what that does not mean.
+ * @example
+ * isSafeTokenValue("Iosevka, monospace"); // → true
+ * isSafeTokenValue("red;}"); // → false
+ */
+declare function isSafeTokenValue(value: string): boolean;
 //#endregion
-export { TokenOverrides };
+export { TokenOverrides, isSafeTokenValue };

package/dist/system/overrides.js

@@ -102,6 +102,45 @@ function inlineOverrides(overrides, mode) {
 */
 const SAFE_VALUE = /^[^;{}<>\\]+$/;
 /**
+* Whether a string may be written into the density stylesheet this module
+* builds.
+*
+* The same rule {@link overridesCss} applies at `SAFE_VALUE`, exported because a
+* caller that builds a {@link TokenOverrides} wants to refuse a value at the
+* *input* rather than watch it be dropped, silently and one warning later, at
+* the sheet. A panel that cannot ask the question has two bad answers open to
+* it: keep a second copy of this regex, which stops being this regex the first
+* time either moves, or write the value anyway and let a reader wonder why the
+* picture did not change.
+*
+* `@cueplusplus/ui/configurator` exports `isSafeCssValue` (`configurator/_overrides.ts:239`)
+* for the configurator's own snapshot, and this is deliberately **not** that
+* function: same rule, asked from the module that owns it, without dragging in
+* a subpath that also carries `ThemeConfigurator`, `ExportDialog` and an
+* optional `react-aria-components` peer. Neither imports the other, and the
+* test beside this file is what holds them to one answer.
+*
+* **The one thing the rule does not cover, said out loud: an unterminated
+* `/*`.** It carries none of the five refused characters, so it is accepted and
+* written, and everything after it in that stylesheet — the closing brace and
+* any later declaration — is inside a comment. That is a value of the caller's
+* own that stops their *other* overrides applying, not an injection: with `;`,
+* `{`, `}`, `<` and `\` all refused, no second value can close the comment and
+* open a rule. A caller that wants to refuse it as well can say so on top of
+* this; tightening `SAFE_VALUE` itself would change what `overridesCss` writes,
+* which is a different release note from this one.
+*
+* @param value - The proposed declaration value.
+* @returns `true` when it cannot close its declaration, its block or the
+*   `<style>` element — see the comment case above for what that does not mean.
+* @example
+* isSafeTokenValue("Iosevka, monospace"); // → true
+* isSafeTokenValue("red;}"); // → false
+*/
+function isSafeTokenValue(value) {
+	return SAFE_VALUE.test(value);
+}
+/**
 * The document-scoped stylesheet text for the density layer.
 *
 * **Why the selector says the attribute twice.** A rung a theme retunes ships
@@ -235,4 +274,4 @@ function reportOverrides(manifest, mode, overrides, theme) {
 	for (const check of after.advisories) if (caused(check)) noteOnce(`overrides: ${check.id} at ${check.ratio.toFixed(2)}:1 misses its ${check.minimum} advisory floor under theme "${theme}"`);
 }
 //#endregion
-export { OverridesContext, inlineOverrides, overridesCss, reportOverrides };
+export { OverridesContext, inlineOverrides, isSafeTokenValue, overridesCss, reportOverrides };

package/manifest/components/accordion.json

@@ -26,7 +26,10 @@
           "type": "string",
           "required": false,
           "defaultValue": null,
-          "description": "Extra classes for the accordion frame."
+          "description": "Extra classes for the accordion frame.",
+          "control": {
+            "kind": "string"
+          }
         }
       ],
       "typeReferences": [
@@ -43,7 +46,10 @@
           "type": "string",
           "required": false,
           "defaultValue": null,
-          "description": "Extra classes for the section."
+          "description": "Extra classes for the section.",
+          "control": {
+            "kind": "string"
+          }
         }
       ],
       "typeReferences": [
@@ -60,7 +66,10 @@
           "type": "string",
           "required": false,
           "defaultValue": null,
-          "description": "Extra classes for the heading."
+          "description": "Extra classes for the heading.",
+          "control": {
+            "kind": "string"
+          }
         }
       ],
       "typeReferences": [
@@ -77,7 +86,10 @@
           "type": "string",
           "required": false,
           "defaultValue": null,
-          "description": "Extra classes for the summary row."
+          "description": "Extra classes for the summary row.",
+          "control": {
+            "kind": "string"
+          }
         }
       ],
       "typeReferences": [
@@ -94,14 +106,20 @@
           "type": "string",
           "required": false,
           "defaultValue": null,
-          "description": "Extra classes for the animating box. Padding belongs on `bodyClassName`."
+          "description": "Extra classes for the animating box. Padding belongs on `bodyClassName`.",
+          "control": {
+            "kind": "string"
+          }
         },
         {
           "name": "bodyClassName",
           "type": "string",
           "required": false,
           "defaultValue": null,
-          "description": "Extra classes for the padded body inside it."
+          "description": "Extra classes for the padded body inside it.",
+          "control": {
+            "kind": "string"
+          }
         }
       ],
       "typeReferences": [