@cueplusplus/ui 0.9.0 → 0.10.0

package/dist/layout/bento.js

@@ -0,0 +1,266 @@
+import { cn } from "../lib/cn.js";
+import { GAP_CLASSES } from "./stack.js";
+import * as React from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/layout/bento.tsx
+/**
+* Static class per count — Tailwind scans source text, not computed strings.
+*
+* One column below `sm`, two from `sm`, the asked-for count only from `lg`:
+* three fixed columns at 640 px would be ~200 px per tile, narrower than the
+* `18rem` minimum measure every grid this replaces already declares.
+*/
+const COLUMN_CLASSES = {
+	2: "grid-cols-1 sm:grid-cols-2",
+	3: "grid-cols-1 sm:grid-cols-2 lg:grid-cols-3",
+	4: "grid-cols-1 sm:grid-cols-2 lg:grid-cols-4"
+};
+/** Static class per row count, from `sm` up — below it the bento is one column. */
+const ROW_CLASSES = {
+	1: "sm:grid-rows-1",
+	2: "sm:grid-rows-2",
+	3: "sm:grid-rows-3",
+	4: "sm:grid-rows-4"
+};
+/**
+* Static class per span, clamped at `sm` because every container is two tracks
+* wide between 640 px and 1024 px whatever its `cols`.
+*
+* So there is no `sm:col-span-3` and no `sm:col-span-4` in this table at all,
+* and no unprefixed `col-span-*` either: an unprefixed span in the one-track
+* base grid grows an implicit second column, which is the same defect one
+* breakpoint down. A span of 1 or 2 carries through from `sm` and needs no
+* `lg:` rung.
+*/
+const SPAN_CLASSES = {
+	1: "sm:col-span-1",
+	2: "sm:col-span-2",
+	3: "sm:col-span-2 lg:col-span-3",
+	4: "sm:col-span-2 lg:col-span-4"
+};
+/** Static class per row span, from `sm` up for the same reason as the columns. */
+const ROW_SPAN_CLASSES = {
+	1: "sm:row-span-1",
+	2: "sm:row-span-2"
+};
+/**
+* Static class per reserved height, spent off the space ladder's top rung so a
+* hero tile shrinks with the rest of the console at ultra-compact.
+*/
+const MIN_HEIGHT_CLASSES = {
+	none: "",
+	half: "min-h-[calc(var(--cue-space-8)*4)]",
+	hero: "min-h-[calc(var(--cue-space-8)*8)]"
+};
+/** The tile surface, shared by both variants so a link tile is not a second look. */
+const TILE_CLASS = "flex flex-col gap-(--cue-space-3) overflow-hidden rounded-(--radius-surface) border border-border bg-surface-1 p-(--cue-space-5)";
+/** What a link tile adds: the hover tint and the focus ring the whole surface takes. */
+const LINK_TILE_CLASS = "no-underline transition-colors duration-150 outline-none hover:bg-surface-2 focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-2 focus-visible:outline-accent";
+/** The host elements a link tile may not contain, plus anything carrying `tabIndex`. */
+const INTERACTIVE_TAGS = /* @__PURE__ */ new Set([
+	"a",
+	"button",
+	"input",
+	"select",
+	"textarea"
+]);
+/**
+* The first interactive child a link tile was given, named, or `undefined`.
+*
+* Shallow by design — it walks `React.Children` and not the rendered tree,
+* because it must run in a server render as well as a client one and a hook is
+* not available in either. What it cannot see (a control behind a component
+* boundary) is what each converted grid's own DOM assertion catches.
+*/
+function interactiveChild(children) {
+	let found;
+	React.Children.forEach(children, (child) => {
+		if (found !== void 0 || !React.isValidElement(child)) return;
+		const { tabIndex } = child.props;
+		if (typeof child.type === "string" && INTERACTIVE_TAGS.has(child.type)) found = child.type;
+		else if (tabIndex !== void 0) found = typeof child.type === "string" ? child.type : "child";
+	});
+	return found;
+}
+/** The tile's name as a log line can carry it, for a `title` that is not a string. */
+function tileLabel(title) {
+	return typeof title === "string" || typeof title === "number" ? String(title) : "an untitled tile";
+}
+/**
+* The bento container: a responsive grid that clamps the spans of its tiles.
+*
+* It maps `React.Children` and clones every child whose type is the tile,
+* narrowing that tile's `span` to its own `cols`; anything else passes through
+* with its props untouched, so a `<section>` or a bare `<div>` may sit in a
+* band beside the tiles.
+*
+* **The clamp reaches direct children only, and that is a contract rather than
+* an oversight.** `React.Children` does not descend into a component element,
+* so a tile rendered by a child — `<Bento.Root><MyTiles /></Bento.Root>` — is
+* whatever `span` it declared, and an over-wide one grows an implicit column
+* exactly as an unclamped tile would. Reading through a component would mean
+* rendering it, which a container may not do. So: **keep a tile a child
+* component renders at `span={1}`, or clamp it in that component.** The same
+* hazard in fragment form is why an authored `node` fixture of tiles is an
+* array and not a `<>…</>`.
+*
+* Static markup — no `"use client"`.
+*/
+const BentoRoot = React.forwardRef(function BentoRoot({ className, cols = 3, rows, dense = false, gap = 4, children, ...elementProps }, ref) {
+	return /* @__PURE__ */ jsx("div", {
+		ref,
+		"data-slot": "bento",
+		className: cn("grid", COLUMN_CLASSES[cols], rows === void 0 ? null : ROW_CLASSES[rows], dense ? "grid-flow-row-dense" : null, GAP_CLASSES[gap], className),
+		...elementProps,
+		children: React.Children.map(children, (child) => clampTile(child, cols, rows))
+	});
+});
+/**
+* Clamp one child's spans to the container's tracks, and leave everything else
+* exactly as it was written.
+*
+* CSS Grid does not clamp: auto-placement grows the implicit grid to fit the
+* largest definite span, so one `span={4}` in a `cols={3}` bento silently adds
+* a fourth column and shifts every row. The tile cannot do this for itself —
+* reading its container would need a hook, and this component is static markup
+* on purpose — so the container does it, on the way past.
+*
+* **Both axes, and the row axis only where there is something to clamp to.**
+* The column clamp always applies because `cols` always has a value; `rows` is
+* optional, and a container that declares none is one whose rows are all
+* implicit — there is no track count for `rowSpan` to be too large for, and the
+* tile's own docblock already says that spanning rows there sizes the span to
+* the tile's own content. So an undeclared `rows` leaves `rowSpan` alone, and a
+* declared one is a promise the tile is held to.
+*/
+function clampTile(child, cols, rows) {
+	if (!React.isValidElement(child) || child.type !== BentoTile) return child;
+	const tile = child;
+	const span = tile.props.span ?? 1;
+	const rowSpan = tile.props.rowSpan ?? 1;
+	return React.cloneElement(tile, {
+		span: Math.min(span, cols),
+		...rows === void 0 ? {} : { rowSpan: Math.min(rowSpan, rows) }
+	});
+}
+/**
+* One cell of a bento: a link, or a surface with an `action`.
+*
+* The two are a discriminated union rather than one shape with a runtime
+* branch, because half of the rule is something a compiler can hold: `href`
+* and `action` are mutually exclusive in the type. The other half — that a
+* link tile's content is static — is held by a dev-time check here and by a
+* DOM assertion in each grid that draws one.
+*
+* Static markup — no `"use client"`.
+*/
+const BentoTile = React.forwardRef(function BentoTile(props, ref) {
+	const { className, span = 1, rowSpan = 1, minHeight = "none", eyebrow, title, meta, action, href, render, children, ...elementProps } = props;
+	if (process.env.NODE_ENV !== "production" && href !== void 0) {
+		if (render !== void 0 && render.props.href === void 0) console.error(`Bento.Tile (${tileLabel(title)}): \`render\` was given an element with no \`href\` of its own. The clone does not pass the tile's, so the link would go nowhere — put the href on the element, as \`next/link\` requires anyway.`);
+		const offender = interactiveChild(children) ?? interactiveChild(action);
+		if (offender !== void 0) console.error(`Bento.Tile (${tileLabel(title)}): a link tile contains an interactive <${offender}>. An <a> admits no interactive descendant, so use a panel tile and put the control in \`action\` instead of nesting it here.`);
+	}
+	const head = eyebrow !== void 0 || title !== void 0;
+	const tail = meta !== void 0 || action !== void 0;
+	const content = /* @__PURE__ */ jsxs(Fragment, { children: [head || tail ? /* @__PURE__ */ jsxs("div", {
+		className: "flex items-start justify-between gap-(--cue-space-3)",
+		children: [head ? /* @__PURE__ */ jsxs("div", {
+			className: "flex min-w-0 flex-col gap-(--cue-space-1)",
+			children: [eyebrow === void 0 ? null : /* @__PURE__ */ jsx("span", {
+				"data-slot": "bento-tile-eyebrow",
+				className: "font-mono text-(length:--cue-text-meta) text-fg-muted",
+				children: eyebrow
+			}), title === void 0 ? null : /* @__PURE__ */ jsx("span", {
+				"data-slot": "bento-tile-title",
+				className: "font-mono text-(length:--cue-text-emphasis) font-medium text-fg",
+				children: title
+			})]
+		}) : null, tail ? /* @__PURE__ */ jsxs("div", {
+			className: "flex shrink-0 items-center gap-(--cue-space-2)",
+			children: [meta === void 0 ? null : /* @__PURE__ */ jsx("span", {
+				"data-slot": "bento-tile-meta",
+				children: meta
+			}), action === void 0 ? null : /* @__PURE__ */ jsx("span", {
+				"data-slot": "bento-tile-action",
+				children: action
+			})]
+		}) : null]
+	}) : null, children] });
+	const surface = {
+		"data-slot": "bento-tile",
+		"data-span": String(span),
+		className: cn(TILE_CLASS, href === void 0 ? null : LINK_TILE_CLASS, SPAN_CLASSES[span], ROW_SPAN_CLASSES[rowSpan], MIN_HEIGHT_CLASSES[minHeight], className),
+		...elementProps
+	};
+	if (href === void 0) return /* @__PURE__ */ jsx("div", {
+		...surface,
+		ref,
+		children: content
+	});
+	const anchorSurface = surface;
+	if (render !== void 0) {
+		const routerLink = render;
+		return React.cloneElement(routerLink, {
+			...anchorSurface,
+			className: cn(routerLink.props.className, anchorSurface.className),
+			ref
+		}, content);
+	}
+	return /* @__PURE__ */ jsx("a", {
+		...anchorSurface,
+		href,
+		ref,
+		children: content
+	});
+});
+/**
+* A grid of unequal tiles: per-item spans, clamped to the container's columns.
+*
+* Where `Grid` lays out cells it never touches, a bento's whole content is
+* per-item — so the span is a prop on the tile, from a closed set, and the
+* container clamps it on the way past. One column below `sm`, two from `sm`,
+* the asked-for count from `lg`; the clamp is per breakpoint and not per
+* `cols`, because every container is two tracks wide in between whatever it
+* was asked for.
+*
+* **Static markup — no hooks, no `"use client"`, and it must stay that way.**
+* A directive is per *module*, so a `Bento` built on `useRender` would open a
+* client boundary in every server page that draws one. That is why the router
+* escape hatch is `render`, an *element* that is cloned, rather than a render
+* function; and why {@link Bento.Tile} is a discriminated union rather than a
+* tile that decides at runtime what it is.
+*
+* `BentoTileProps` omits the native `title` from its `<div>` props, the same
+* omission `PanelHeader` and `Item` make: `React.ComponentPropsWithoutRef<"div">`
+* already declares `title?: string`, and narrowing it to a `ReactNode` without
+* the `Omit` is TS2430.
+*
+* @example
+* <Bento.Root cols={3} rows={2} gap={5}>
+*   <Bento.Tile span={2} rowSpan={2} minHeight="hero" title="Kitchen sink">
+*     Every component, on one page.
+*   </Bento.Tile>
+*   <Bento.Tile title="Themes" meta={<Chip variant="outline">10</Chip>} />
+*   <Bento.Tile title="Density" meta={<Chip variant="outline">5</Chip>} />
+* </Bento.Root>
+* @example
+* <Bento.Tile
+*   href="/docs/components/grid"
+*   render={<NextLink href="/docs/components/grid" />}
+*   eyebrow="@cueplusplus/ui"
+*   title="Grid"
+* >
+*   Equal columns, or as many as fit.
+* </Bento.Tile>
+* @example
+* <Bento.Tile title="Signal" action={<Button onClick={apply}>Apply</Button>}>
+*   <ThemeSwatches theme="signal" />
+* </Bento.Tile>
+*/
+const Bento = {
+	Root: BentoRoot,
+	Tile: BentoTile
+};
+//#endregion
+export { Bento };

package/dist/layout/index.d.ts

@@ -2,14 +2,15 @@ import { Link, LinkProps, linkVariants } from "./link.js";
 import { Sidebar, SidebarItemProps, SidebarRailProps, SidebarRootProps, SidebarSectionProps, useSidebar } from "./sidebar.js";
 import { Container, ContainerProps, ContainerWidth } from "./container.js";
 import { Accordion, AccordionHeaderProps, AccordionItemProps, AccordionPanelProps, AccordionRootProps, AccordionTriggerProps } from "./accordion.js";
+import { SpaceStep, Stack, StackAlign, StackJustify, StackProps } from "./stack.js";
+import { Bento, BentoColumns, BentoMinHeight, BentoRootProps, BentoRowSpan, BentoRows, BentoSpan, BentoTileProps } from "./bento.js";
 import { Breadcrumb, BreadcrumbItem, BreadcrumbProps } from "./breadcrumb.js";
 import { Card, CardContentProps, CardDescriptionProps, CardFooterProps, CardHeaderProps, CardRootProps, CardTitleProps } from "./card.js";
 import { Collapsible, CollapsiblePanelProps, CollapsibleRootProps, CollapsibleTriggerProps, Disclosure, DisclosureProps } from "./collapsible.js";
 import { DescriptionList, DescriptionListDetailProps, DescriptionListLayout, DescriptionListRootProps, DescriptionListTermProps } from "./description-list.js";
-import { SpaceStep, Stack, StackAlign, StackJustify, StackProps } from "./stack.js";
 import { Grid, GridColumns, GridProps } from "./grid.js";
 import { Item, ItemProps, itemVariants } from "./item.js";
 import { Pagination, PaginationEntry, PaginationProps, paginationRange } from "./pagination.js";
 import { Stepper, StepperProps, StepperState, StepperStep } from "./stepper.js";
 import { Timeline, TimelineContentProps, TimelineItemProps, TimelineMarkerProps, TimelineRootProps } from "./timeline.js";
-export { Accordion, type AccordionHeaderProps, type AccordionItemProps, type AccordionPanelProps, type AccordionRootProps, type AccordionTriggerProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Card, type CardContentProps, type CardDescriptionProps, type CardFooterProps, type CardHeaderProps, type CardRootProps, type CardTitleProps, Collapsible, type CollapsiblePanelProps, type CollapsibleRootProps, type CollapsibleTriggerProps, Container, type ContainerProps, type ContainerWidth, DescriptionList, type DescriptionListDetailProps, type DescriptionListLayout, type DescriptionListRootProps, type DescriptionListTermProps, Disclosure, type DisclosureProps, Grid, type GridColumns, type GridProps, Item, type ItemProps, Link, type LinkProps, Pagination, type PaginationEntry, type PaginationProps, Sidebar, type SidebarItemProps, type SidebarRailProps, type SidebarRootProps, type SidebarSectionProps, type SpaceStep, Stack, type StackAlign, type StackJustify, type StackProps, Stepper, type StepperProps, type StepperState, type StepperStep, Timeline, type TimelineContentProps, type TimelineItemProps, type TimelineMarkerProps, type TimelineRootProps, itemVariants, linkVariants, paginationRange, useSidebar };
+export { Accordion, type AccordionHeaderProps, type AccordionItemProps, type AccordionPanelProps, type AccordionRootProps, type AccordionTriggerProps, Bento, type BentoColumns, type BentoMinHeight, type BentoRootProps, type BentoRowSpan, type BentoRows, type BentoSpan, type BentoTileProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Card, type CardContentProps, type CardDescriptionProps, type CardFooterProps, type CardHeaderProps, type CardRootProps, type CardTitleProps, Collapsible, type CollapsiblePanelProps, type CollapsibleRootProps, type CollapsibleTriggerProps, Container, type ContainerProps, type ContainerWidth, DescriptionList, type DescriptionListDetailProps, type DescriptionListLayout, type DescriptionListRootProps, type DescriptionListTermProps, Disclosure, type DisclosureProps, Grid, type GridColumns, type GridProps, Item, type ItemProps, Link, type LinkProps, Pagination, type PaginationEntry, type PaginationProps, Sidebar, type SidebarItemProps, type SidebarRailProps, type SidebarRootProps, type SidebarSectionProps, type SpaceStep, Stack, type StackAlign, type StackJustify, type StackProps, Stepper, type StepperProps, type StepperState, type StepperStep, Timeline, type TimelineContentProps, type TimelineItemProps, type TimelineMarkerProps, type TimelineRootProps, itemVariants, linkVariants, paginationRange, useSidebar };

package/dist/layout/index.js

@@ -2,14 +2,15 @@ import { Link, linkVariants } from "./link.js";
 import { Sidebar, useSidebar } from "./sidebar.js";
 import { Container } from "./container.js";
 import { Accordion } from "./accordion.js";
+import { Stack } from "./stack.js";
+import { Bento } from "./bento.js";
 import { Breadcrumb } from "./breadcrumb.js";
 import { Card } from "./card.js";
 import { Collapsible, Disclosure } from "./collapsible.js";
 import { DescriptionList } from "./description-list.js";
-import { Stack } from "./stack.js";
 import { Grid } from "./grid.js";
 import { Item, itemVariants } from "./item.js";
 import { Pagination, paginationRange } from "./pagination.js";
 import { Stepper } from "./stepper.js";
 import { Timeline } from "./timeline.js";
-export { Accordion, Breadcrumb, Card, Collapsible, Container, DescriptionList, Disclosure, Grid, Item, Link, Pagination, Sidebar, Stack, Stepper, Timeline, itemVariants, linkVariants, paginationRange, useSidebar };
+export { Accordion, Bento, Breadcrumb, Card, Collapsible, Container, DescriptionList, Disclosure, Grid, Item, Link, Pagination, Sidebar, Stack, Stepper, Timeline, itemVariants, linkVariants, paginationRange, useSidebar };

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": [

package/manifest/components/activity-graph.json

@@ -14,35 +14,50 @@
       "type": "readonly DataPoint[]",
       "required": true,
       "defaultValue": null,
-      "description": "Date and count pairs from the heat-graph package. Levels are classified for you;\ngaps are filled as empty cells."
+      "description": "Date and count pairs from the heat-graph package. Levels are classified for you;\ngaps are filled as empty cells.",
+      "control": {
+        "kind": "array"
+      }
     },
     {
       "name": "start",
       "type": "string | Date",
       "required": true,
       "defaultValue": null,
-      "description": "First day of the window. Pass it explicitly: left unset, heat-graph draws a full\nyear ending today, which will not match your data."
+      "description": "First day of the window. Pass it explicitly: left unset, heat-graph draws a full\nyear ending today, which will not match your data.",
+      "control": {
+        "kind": "opaque"
+      }
     },
     {
       "name": "end",
       "type": "string | Date",
       "required": true,
       "defaultValue": null,
-      "description": "Last day of the window. Cells are fixed-size, so a long window scrolls\nhorizontally rather than shrinking."
+      "description": "Last day of the window. Cells are fixed-size, so a long window scrolls\nhorizontally rather than shrinking.",
+      "control": {
+        "kind": "opaque"
+      }
     },
     {
       "name": "title",
       "type": "string",
       "required": true,
       "defaultValue": null,
-      "description": "What is being counted."
+      "description": "What is being counted.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "total",
       "type": "string",
       "required": true,
       "defaultValue": null,
-      "description": "Pre-formatted summary shown opposite the title."
+      "description": "Pre-formatted summary shown opposite the title.",
+      "control": {
+        "kind": "string"
+      }
     }
   ],
   "typeReferences": [