@cueplusplus/ui 0.1.0

package/dist/configurator/_overrides.js

@@ -0,0 +1,514 @@
+import { BASE_FONT_STACKS, DEFAULT_DENSITY_LEVEL, DENSITY_RADIUS_SCALE, THEME_COLOR_TOKENS, THEME_PRESETS } from "../theming/_presets.js";
+import { THEME_NAME_PATTERN, assertCssValue, serializeThemeBlock, tokenProperty } from "../theming/serialize.js";
+//#region src/configurator/_overrides.ts
+/**
+* The override model behind the theme configurator: what a user may move, where
+* the declaration has to land for it to win, and how the whole thing survives a
+* reload.
+*
+* Everything here is a pure function of an immutable `ThemeOverrides` value,
+* apart from the three functions at the bottom that talk to the document and to
+* `localStorage`. That split is deliberate — the panel is a view over this
+* model, the export dialog is a second view over the same model, and neither is
+* allowed a private opinion about what the tokens are.
+*
+* ## Why the scoping is this fussy
+*
+* The token layer declares its values under *attribute* selectors on two
+* disjoint axes (`[data-theme]` for colour, `[data-density]` for geometry), and
+* both axes are re-declared at every element that carries the attribute — the
+* `<html>` element, the provider root, a `<Density>` island, a portal container.
+* An override is therefore not "set the variable on `:root`": that loses in
+* three separate ways.
+*
+* - A colour written under a bare `[data-theme="x"]` (0,1,0) is outranked by the
+*   shipped `[data-theme="x"][data-mode="light"]` block (0,2,0), so the moment
+*   the user switches to light the override vanishes. Colours are therefore
+*   written **crossed with the mode**, which is also honest: a theme's two modes
+*   are two palettes, and editing one should not silently edit the other.
+* - A geometry multiplier written flat outranks the density block that set it,
+*   freezing `ultra-compact`'s 0.75 radius scale at 1 — the same trap
+*   `createTheme()` documents. Multipliers are therefore **crossed with the
+*   density ladder**, one rule per level, with the level's own value folded in.
+* - `--cue-font-scale` is published by `<ThemeProvider>` as an *inline* custom
+*   property, and no stylesheet outranks an inline declaration. It is the one
+*   token here that needs `!important`, and it gets its own rule so that the
+*   flag never spreads to anything that does not need it.
+*
+* @internal Not part of the public API; `./configurator` re-exports what a host
+*   app needs.
+*/
+/** The one style element the configurator writes into. */
+const OVERRIDE_STYLE_ID = "cue-configurator-overrides";
+/** Default `localStorage` key for the persisted snapshot. */
+const DEFAULT_CONFIGURATOR_STORAGE_KEY = "cue-configurator";
+/**
+* Schema version of the persisted snapshot.
+*
+* A blob from another version is discarded rather than migrated: the payload is
+* a design preference a user can rebuild in a minute, and a wrong migration
+* would paint a page with values nobody chose.
+*/
+const CONFIGURATOR_VERSION = 1;
+/** Banner printed at the top of the applied — and exported — stylesheet. */
+const OVERRIDE_BANNER = "@cueplusplus/ui — theme configurator overrides";
+/**
+* The unitless density multiplier each level publishes.
+*
+* A copy of `packages/tokens/src/density/*.tokens.json`, for the same reason
+* `theming/_presets.ts` copies the palettes: the tokens package emits CSS, and a
+* value this module has to *multiply* cannot be read out of a stylesheet.
+* `test/configurator/overrides.test.ts` re-reads the DTCG sources and fails on
+* the first number that has drifted.
+*/
+const DENSITY_FACTOR = {
+	"ultra-compact": .85,
+	"normal": 1,
+	"large": 1.3
+};
+/** The authored label tracking, and the value the "reset" arrow returns to. */
+const BASE_TRACKING_LABEL = "0.12em";
+/** The colour tokens the panel edits — the same list a theme block declares. */
+const COLOR_TOKENS = THEME_COLOR_TOKENS;
+/** The type stacks the panel edits. Mode-independent: a typeface is not a palette. */
+const FONT_TOKENS = [
+	"font-sans",
+	"font-mono",
+	"font-display"
+];
+/**
+* The multipliers that have to be crossed with the density ladder, and the
+* per-level values they are crossed with.
+*/
+const SCALED_TOKENS = {
+	"radius-scale": DENSITY_RADIUS_SCALE,
+	"density": DENSITY_FACTOR
+};
+/** Axis-free tokens: one declaration covers every level. */
+const FLAT_TOKENS = ["tracking-label"];
+/** Tokens the provider publishes inline, which a stylesheet can only reach with `!important`. */
+const INLINE_TOKENS = ["font-scale"];
+/** Every token the configurator is allowed to write, as `--cue-*` properties, in contract order. */
+const MANAGED_TOKENS = [
+	...COLOR_TOKENS,
+	...FONT_TOKENS,
+	...Object.keys(SCALED_TOKENS),
+	...FLAT_TOKENS,
+	...INLINE_TOKENS
+].map(tokenProperty);
+const KINDS = Object.fromEntries([
+	...COLOR_TOKENS.map((token) => [tokenProperty(token), "color"]),
+	...FONT_TOKENS.map((token) => [tokenProperty(token), "font"]),
+	...Object.keys(SCALED_TOKENS).map((token) => [tokenProperty(token), "scaled"]),
+	...FLAT_TOKENS.map((token) => [tokenProperty(token), "flat"]),
+	...INLINE_TOKENS.map((token) => [tokenProperty(token), "inline"])
+]);
+/** The density levels, default first — the order the crossed rules are emitted in. */
+const DENSITY_LEVELS = [DEFAULT_DENSITY_LEVEL, ...Object.keys(DENSITY_FACTOR).filter((level) => level !== DEFAULT_DENSITY_LEVEL)];
+/** The nothing-has-moved state. Frozen: it is shared by every caller. */
+const EMPTY_OVERRIDES = Object.freeze({
+	themes: Object.freeze({}),
+	global: Object.freeze({})
+});
+/** Which of the five buckets a token belongs to, or `null` if it is not ours to write. */
+function tokenKind(token) {
+	return KINDS[tokenProperty(token)] ?? null;
+}
+/** The key a theme+mode pair is stored under. */
+function scopeKey(scope) {
+	return `${scope.theme}/${scope.mode}`;
+}
+/** The inverse of {@link scopeKey}, rejecting anything that would not be safe in a selector. */
+function parseScopeKey(key) {
+	const slash = key.lastIndexOf("/");
+	if (slash === -1) return null;
+	const theme = key.slice(0, slash);
+	const mode = key.slice(slash + 1);
+	if (!THEME_NAME_PATTERN.test(theme)) return null;
+	if (mode !== "dark" && mode !== "light") return null;
+	return {
+		theme,
+		mode
+	};
+}
+/**
+* Whether a value can be printed into a declaration without escaping it.
+*
+* Colours arrive from the picker already re-formatted, but a font stack is free
+* text a user typed, and it ends up inside a stylesheet. This is the same check
+* `theming/serialize.ts` makes — asked as a question instead of thrown as an
+* error, so a field can mark itself invalid while the user is still typing.
+*
+* @param value - The proposed declaration value.
+* @returns `true` when it stays inside its declaration.
+* @example
+* isSafeCssValue("Iosevka, monospace"); // → true
+*/
+function isSafeCssValue(value) {
+	try {
+		assertCssValue("value", value);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* The value a token has before the user touches anything.
+*
+* Colours come from the preset for *this mode*; fonts from the preset's own
+* override, else the base stack; the multipliers are 1 by definition, because
+* what the panel edits is the multiplier and not the ladder underneath it.
+*
+* @param scope - Theme and mode being edited.
+* @param token - A bare token name or a `--cue-*` property.
+* @returns The shipped value, as a CSS string.
+* @example
+* baseValue({ theme: "terminal", mode: "dark" }, "accent"); // → "hsl(180 100% 50%)"
+*/
+function baseValue(scope, token) {
+	const property = tokenProperty(token);
+	const name = property.slice(6);
+	const preset = THEME_PRESETS[scope.theme];
+	switch (tokenKind(property)) {
+		case "color": return ((scope.mode === "light" ? preset?.light : preset?.dark) ?? preset?.dark)?.[name] ?? "";
+		case "font": return preset?.fonts[name] ?? BASE_FONT_STACKS[name] ?? "";
+		case "scaled":
+		case "inline": return "1";
+		case "flat": return BASE_TRACKING_LABEL;
+		default: return "";
+	}
+}
+/** The scope keys a token's declaration is stored under: both modes for a font, else one. */
+function storageScopes(scope, kind) {
+	if (kind === "font") return [scopeKey({
+		...scope,
+		mode: "dark"
+	}), scopeKey({
+		...scope,
+		mode: "light"
+	})];
+	return [scopeKey(scope)];
+}
+/** A shallow clone deep enough to edit one scope without aliasing the rest. */
+function cloneOverrides(overrides) {
+	const themes = {};
+	for (const [key, entries] of Object.entries(overrides.themes)) themes[key] = { ...entries };
+	return {
+		themes,
+		global: { ...overrides.global }
+	};
+}
+/** Drop scopes that no longer hold anything, so `serializeOverrideCss` emits no empty rules. */
+function prune(overrides) {
+	for (const [key, entries] of Object.entries(overrides.themes)) if (Object.keys(entries).length === 0) delete overrides.themes[key];
+	return overrides;
+}
+/**
+* Move a token, returning a new state.
+*
+* Setting a token back to the value the preset ships is a *reset*, not an
+* override — otherwise "I put it back" would still export a declaration and the
+* user would carry a no-op forever.
+*
+* @param overrides - Current state. Never mutated.
+* @param scope - Theme and mode being edited.
+* @param token - A bare token name or a `--cue-*` property.
+* @param value - The new CSS value.
+* @returns The new state.
+* @throws TypeError if the token is not one the configurator manages, or the
+*   value could break out of its declaration.
+* @example
+* setOverride(overrides, { theme: "terminal", mode: "dark" }, "accent", "#ff8800");
+*/
+function setOverride(overrides, scope, token, value) {
+	const property = tokenProperty(token);
+	const kind = tokenKind(property);
+	if (kind === null) throw new TypeError(`${property} is not a token the configurator manages`);
+	assertCssValue(property, value);
+	if (value === baseValue(scope, property)) return clearOverride(overrides, scope, property);
+	const next = cloneOverrides(overrides);
+	if (kind === "color" || kind === "font") for (const key of storageScopes(scope, kind)) next.themes[key] = {
+		...next.themes[key],
+		[property]: value
+	};
+	else next.global[property] = value;
+	return prune(next);
+}
+/**
+* Put a token back to its shipped value, returning a new state.
+*
+* @param overrides - Current state. Never mutated.
+* @param scope - Theme and mode being edited.
+* @param token - A bare token name or a `--cue-*` property.
+* @returns The new state.
+* @example
+* clearOverride(overrides, scope, "--cue-accent");
+*/
+function clearOverride(overrides, scope, token) {
+	const property = tokenProperty(token);
+	const kind = tokenKind(property);
+	if (kind === null) return overrides;
+	const next = cloneOverrides(overrides);
+	if (kind === "color" || kind === "font") for (const key of storageScopes(scope, kind)) delete next.themes[key]?.[property];
+	else delete next.global[property];
+	return prune(next);
+}
+/** Whether a token currently carries an override in this scope. */
+function isOverridden(overrides, scope, token) {
+	const property = tokenProperty(token);
+	const kind = tokenKind(property);
+	if (kind === null) return false;
+	if (kind === "color" || kind === "font") return overrides.themes[scopeKey(scope)]?.[property] !== void 0;
+	return overrides.global[property] !== void 0;
+}
+/**
+* How many declarations the user has made.
+*
+* Counted as declarations rather than as decisions: a font family is one choice
+* that produces two declarations, one per mode, and the number in the panel is
+* the number that will appear in the export.
+*/
+function overrideCount(overrides) {
+	let total = Object.keys(overrides.global).length;
+	for (const entries of Object.values(overrides.themes)) total += Object.keys(entries).length;
+	return total;
+}
+/** The value a token has right now: the override if there is one, else the shipped value. */
+function resolveValue(overrides, scope, token) {
+	const property = tokenProperty(token);
+	const kind = tokenKind(property);
+	if (kind === null) return "";
+	return (kind === "color" || kind === "font" ? overrides.themes[scopeKey(scope)]?.[property] : overrides.global[property]) ?? baseValue(scope, property);
+}
+/**
+* Every token the configurator manages, resolved for one scope.
+*
+* This is what `onChange` hands a host app and what the registry export writes:
+* a complete picture, not a diff, so a consumer never has to know which preset
+* the values came from.
+*
+* @param overrides - Current state.
+* @param scope - Theme and mode to resolve for.
+* @returns `--cue-*` property → CSS value.
+*/
+function resolvedTokens(overrides, scope) {
+	return Object.fromEntries(MANAGED_TOKENS.map((property) => [property, resolveValue(overrides, scope, property)]));
+}
+/** Declarations of one scope, ordered by the token contract rather than by edit order. */
+function orderedDeclarations(entries) {
+	return MANAGED_TOKENS.filter((property) => entries[property] !== void 0).map((property) => [property, entries[property]]);
+}
+/**
+* The selector a theme-scoped declaration lands under.
+*
+* Not `themeSelector()` from the theming group, which emits the *authoring*
+* form: a bare `[data-theme="x"]` for dark, because that is the block a
+* stylesheet writes first. An override has to beat that block **and** the light
+* block above it, so it always names the mode.
+*/
+function overrideSelector(theme, mode) {
+	return `[data-theme="${theme}"][data-mode="${mode}"]`;
+}
+/** Round a product of two scales to something a stylesheet can print. */
+const scaled = (a, b) => String(Number((a * b).toFixed(4)));
+/** A multiplier, crossed with one density level's own value. */
+function crossed(property, value, level) {
+	const ladder = SCALED_TOKENS[property.slice(6)];
+	const factor = Number(value);
+	if (ladder === void 0 || !Number.isFinite(factor)) return value;
+	return scaled(factor, ladder[level]);
+}
+const THEME_COMMENT = "the mode is named so the override outranks the shipped light block";
+const CROSSED_COMMENT = "crossed with the density ladder — flat would freeze ultra-compact's 0.75";
+const INLINE_COMMENT = "the provider inlines this one; !important is the only lever left";
+/**
+* Print the overrides as a stylesheet.
+*
+* Returns `""` when nothing has moved — an empty stylesheet is not a stylesheet
+* with an empty rule in it, and the runtime uses the empty string as its signal
+* to remove the style element entirely.
+*
+* @param overrides - Current state.
+* @param options - Banner text.
+* @returns The stylesheet, newline-terminated, or `""`.
+* @example
+* serializeOverrideCss(overrides, { banner: OVERRIDE_BANNER });
+*/
+function serializeOverrideCss(overrides, options = {}) {
+	const blocks = [];
+	for (const key of Object.keys(overrides.themes).toSorted()) {
+		const scope = parseScopeKey(key);
+		const declarations = orderedDeclarations(overrides.themes[key] ?? {});
+		if (scope === null || declarations.length === 0) continue;
+		blocks.push({
+			selector: overrideSelector(scope.theme, scope.mode),
+			sections: [{
+				comment: blocks.length === 0 ? THEME_COMMENT : void 0,
+				declarations
+			}]
+		});
+	}
+	const global = orderedDeclarations(overrides.global);
+	const scaledDeclarations = global.filter(([property]) => tokenKind(property) === "scaled");
+	const flatDeclarations = global.filter(([property]) => tokenKind(property) === "flat");
+	const inlineDeclarations = global.filter(([property]) => tokenKind(property) === "inline");
+	if (scaledDeclarations.length > 0) for (const level of DENSITY_LEVELS) {
+		const isDefault = level === DEFAULT_DENSITY_LEVEL;
+		blocks.push({
+			selector: isDefault ? `:root,\n[data-density="${level}"]` : `[data-density="${level}"]`,
+			sections: [{
+				comment: isDefault ? CROSSED_COMMENT : void 0,
+				declarations: scaledDeclarations.map(([property, value]) => [property, crossed(property, value, level)])
+			}]
+		});
+	}
+	if (flatDeclarations.length > 0) blocks.push({
+		selector: ":root,\n[data-density]",
+		sections: [{ declarations: flatDeclarations }]
+	});
+	if (inlineDeclarations.length > 0) blocks.push({
+		selector: ":root,\n[data-cue-root],\n[data-cue-portal]",
+		sections: [{
+			comment: INLINE_COMMENT,
+			declarations: inlineDeclarations.map(([property, value]) => [property, `${value} !important`])
+		}]
+	});
+	if (blocks.length === 0) return "";
+	return `${[...options.banner === void 0 ? [] : [`/*! ${options.banner}\n * Written by <ThemeConfigurator>. Paste it, do not edit it.\n */`], ...blocks.map(serializeThemeBlock)].join("\n\n")}\n`;
+}
+/**
+* The stylesheet the panel applies — and, byte for byte, the one its CSS export
+* hands you. One function so the two can never drift.
+*
+* @param overrides - Current state.
+* @returns The banner-topped stylesheet, or `""` when nothing has moved.
+*/
+function configuratorCss(overrides) {
+	return serializeOverrideCss(overrides, { banner: OVERRIDE_BANNER });
+}
+/**
+* Put the stylesheet into the document, creating the style element if needed.
+*
+* One element, identified by {@link OVERRIDE_STYLE_ID}, appended to `<head>`
+* after everything else — later in the cascade is half of how these overrides
+* win. An empty stylesheet removes the element instead of leaving an empty one
+* behind, so "reset all" leaves the document exactly as it found it.
+*
+* @param css - The stylesheet, from {@link configuratorCss}.
+* @param doc - Document to write into. Defaults to the ambient one.
+* @returns The style element, or `null` when there was nothing to apply.
+*/
+function applyOverrideCss(css, doc = globalThis.document) {
+	if (doc === void 0) return null;
+	if (css === "") {
+		removeOverrideStyles(doc);
+		return null;
+	}
+	let element = doc.getElementById(OVERRIDE_STYLE_ID);
+	if (element === null) {
+		element = doc.createElement("style");
+		element.id = OVERRIDE_STYLE_ID;
+		doc.head.appendChild(element);
+	}
+	if (element.textContent !== css) element.textContent = css;
+	return element;
+}
+/** Take the override stylesheet back out of the document. */
+function removeOverrideStyles(doc = globalThis.document) {
+	doc?.getElementById(OVERRIDE_STYLE_ID)?.remove();
+}
+/** Keep only the entries this module is willing to print into a stylesheet. */
+function sanitizeEntries(input) {
+	const entries = {};
+	if (input === null || typeof input !== "object") return entries;
+	for (const [property, value] of Object.entries(input)) {
+		if (typeof value !== "string") continue;
+		if (!MANAGED_TOKENS.includes(property)) continue;
+		if (!isSafeCssValue(value)) continue;
+		entries[property] = value;
+	}
+	return entries;
+}
+/** The persisted blob, read defensively — it is user-editable text that becomes CSS. */
+function sanitizeOverrides(input) {
+	const overrides = {
+		themes: {},
+		global: {}
+	};
+	if (input === null || typeof input !== "object") return overrides;
+	const source = input;
+	if (source.themes !== null && typeof source.themes === "object") for (const [key, entries] of Object.entries(source.themes)) {
+		if (parseScopeKey(key) === null) continue;
+		const clean = sanitizeEntries(entries);
+		if (Object.keys(clean).length > 0) overrides.themes[key] = clean;
+	}
+	overrides.global = sanitizeEntries(source.global);
+	return overrides;
+}
+/** The snapshot a first-time visitor gets. */
+function defaultSnapshot() {
+	return {
+		version: 1,
+		overrides: EMPTY_OVERRIDES,
+		zoom: 1,
+		panel: {
+			position: "floating",
+			x: 24,
+			y: 24,
+			collapsed: false
+		}
+	};
+}
+/**
+* Read the persisted snapshot.
+*
+* Every field is validated, and anything that fails validation is dropped
+* rather than repaired — the blob is text a user can edit in devtools, and its
+* values are printed straight into a stylesheet.
+*
+* @param storageKey - The `localStorage` key.
+* @returns The snapshot, or `null` when there is nothing usable stored.
+*/
+function readSnapshot(storageKey) {
+	if (typeof localStorage === "undefined") return null;
+	let parsed;
+	try {
+		const raw = localStorage.getItem(storageKey);
+		if (raw === null) return null;
+		parsed = JSON.parse(raw);
+	} catch {
+		return null;
+	}
+	if (parsed === null || typeof parsed !== "object") return null;
+	const stored = parsed;
+	if (stored.version !== 1) return null;
+	const fallback = defaultSnapshot();
+	const panel = stored.panel ?? {};
+	const number = (value, or) => typeof value === "number" && Number.isFinite(value) ? value : or;
+	return {
+		version: 1,
+		overrides: sanitizeOverrides(stored.overrides),
+		zoom: number(stored.zoom, fallback.zoom),
+		panel: {
+			position: panel["position"] === "docked-right" ? "docked-right" : "floating",
+			x: number(panel["x"], fallback.panel.x),
+			y: number(panel["y"], fallback.panel.y),
+			collapsed: panel["collapsed"] === true
+		}
+	};
+}
+/**
+* Persist the snapshot. A full quota or a private-mode failure is swallowed —
+* a preference is a nicety, never a hard failure.
+*
+* @param storageKey - The `localStorage` key.
+* @param snapshot - What to store.
+*/
+function writeSnapshot(storageKey, snapshot) {
+	if (typeof localStorage === "undefined") return;
+	try {
+		localStorage.setItem(storageKey, JSON.stringify(snapshot));
+	} catch {}
+}
+//#endregion
+export { BASE_TRACKING_LABEL, COLOR_TOKENS, CONFIGURATOR_VERSION, DEFAULT_CONFIGURATOR_STORAGE_KEY, DENSITY_FACTOR, EMPTY_OVERRIDES, FLAT_TOKENS, FONT_TOKENS, INLINE_TOKENS, MANAGED_TOKENS, OVERRIDE_BANNER, OVERRIDE_STYLE_ID, SCALED_TOKENS, applyOverrideCss, baseValue, clearOverride, configuratorCss, defaultSnapshot, isOverridden, isSafeCssValue, overrideCount, readSnapshot, removeOverrideStyles, resolveValue, resolvedTokens, scopeKey, serializeOverrideCss, setOverride, tokenKind, writeSnapshot };

package/dist/configurator/configurator.d.ts

@@ -0,0 +1,71 @@
+import { ConfiguratorPosition } from "./_overrides.js";
+import * as React from "react";
+//#region src/configurator/configurator.d.ts
+interface ThemeConfiguratorProps {
+  /** Placement, controlled. Pair with `onPositionChange`. */
+  position?: ConfiguratorPosition;
+  /** Initial placement. A stored one wins. Defaults to `"floating"`. */
+  defaultPosition?: ConfiguratorPosition;
+  /** Called when the user docks or floats the panel. */
+  onPositionChange?: (position: ConfiguratorPosition) => void;
+  /** Start furled to the title bar. A stored value wins. Defaults to `false`. */
+  defaultCollapsed?: boolean;
+  /**
+   * `localStorage` key holding the overrides, the placement and the zoom.
+   * Defaults to `"cue-configurator"`.
+   */
+  storageKey?: string;
+  /**
+   * Called with the full resolved `--cue-*` map — never a diff — whenever the
+   * overrides, the theme or the mode change, and once on mount.
+   */
+  onChange?: (tokens: Record<string, string>) => void;
+  /** Bind ⌘/Ctrl with `+`, `-` and `0` to the zoom valve. Defaults to `true`. */
+  zoomShortcuts?: boolean;
+  /** Panel heading. Defaults to `"Theme"`. */
+  title?: React.ReactNode;
+  /** Extra classes for the panel. */
+  className?: string;
+}
+/**
+ * The floating theme configurator: the panel that edits the design system it is
+ * drawn with.
+ *
+ * It is a **component**, not a devtool bolted onto the kitchensink — mount it in
+ * any app behind a flag and a designer can retune that app's theme in place. The
+ * whole thing rests on one rule, and the rule is what keeps it from being a toy:
+ * *everything it does is a `--cue-*` declaration in one stylesheet.* No inline
+ * styles on the root, no parallel token vocabulary, no runtime theme engine. The
+ * CSS it exports is byte for byte the CSS the page is wearing, which is the only
+ * reason the export dialog can promise a round trip at all.
+ *
+ * What it owns:
+ *
+ * - **Preset, mode and density** are the provider's, driven through `useTheme()`
+ *   so a switch restamps `<html>`, every portal, and the persisted preference.
+ * - **Colour, type and geometry overrides** go into
+ *   `<style id="cue-configurator-overrides">`, scoped so they win where they
+ *   have to and lose where they should — the cascade reasoning is in
+ *   `_overrides.ts`, and it is the interesting part of this group.
+ * - **Text scale and root zoom**, the two relief valves the density ladder is
+ *   paired with.
+ * - **Its own placement**, furled state and every override, in `localStorage`
+ *   under one key.
+ *
+ * Renders in place as a `position: fixed` region, so mount it inside the
+ * provider — it needs the theme context — but outside any transformed ancestor,
+ * which would turn `fixed` into `absolute` and take the panel with the page.
+ *
+ * @throws If rendered outside a `<ThemeProvider>`: there is no theme to
+ *   configure, which is a wiring bug rather than a fallback situation.
+ * @example
+ * <ThemeProvider>
+ *   <App />
+ *   {devMode ? <ThemeConfigurator /> : null}
+ * </ThemeProvider>
+ * @example
+ * <ThemeConfigurator position="docked-right" onChange={(tokens) => report(tokens)} />
+ */
+declare function ThemeConfigurator({ position: positionProp, defaultPosition, onPositionChange, defaultCollapsed, storageKey, onChange, zoomShortcuts, title, className }: ThemeConfiguratorProps): React.JSX.Element;
+//#endregion
+export { ThemeConfigurator, ThemeConfiguratorProps };