@cueplusplus/ui 0.13.0

package/dist/configurator/panel-sections.js

@@ -0,0 +1,352 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { Input } from "../forms/input.js";
+import { useDensities, useThemes } from "../system/theme-registry.js";
+import { SectionHeader } from "../chrome/section-header.js";
+import { SegmentedControl } from "../chrome/segmented-control.js";
+import { Field, FieldLabel } from "../forms/field.js";
+import { Slider } from "../forms/slider.js";
+import { Kbd } from "../primitives/kbd.js";
+import { useTheme } from "../system/use-theme.js";
+import { tokenProperty } from "../theming/serialize.js";
+import { COLOR_TOKENS, FONT_TOKENS, isSafeCssValue } from "./_overrides.js";
+import { TokenEditor } from "./token-editor.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { resolve } from "@cueplusplus/theme-base";
+//#region src/configurator/panel-sections.tsx
+/** The five colours a preset is recognisable from, in reading order. */
+const SWATCH_TOKENS = [
+	"bg",
+	"surface-2",
+	"fg",
+	"accent",
+	"danger"
+];
+const MODE_ITEMS = [
+	{
+		value: "dark",
+		label: "Dark"
+	},
+	{
+		value: "light",
+		label: "Light"
+	},
+	{
+		value: "system",
+		label: "System"
+	}
+];
+/**
+* Labels for a 19rem panel. Five rungs will not fit as words — `Ultra-compact`
+* and `Ultra-large` alone are 25 characters — so the segmented control wears
+* the garment sizes and the value it sets is still the ladder's own name.
+*/
+const BASE_DENSITY_LABELS = {
+	"ultra-compact": "XS",
+	"compact": "S",
+	"normal": "M",
+	"large": "L",
+	"ultra-large": "XL"
+};
+/**
+* What a rung is called in the panel.
+*
+* A lookup rather than a table, because the ladder is open now: a theme may add
+* a rung, and this package has no garment size to give it. Its own name is the
+* only label that is certainly true — longer than a letter, and honest about
+* being the theme's rather than the ladder's. The base five keep their sizes,
+* so nothing a user has learned moves.
+*/
+function densityLabel(rung) {
+	return BASE_DENSITY_LABELS[rung] ?? rung;
+}
+/** Bounds of the text-scale knob, from spec §6's `fontScale`. */
+const FONT_SCALE = {
+	min: .8,
+	max: 1.3,
+	step: .05
+};
+/** Bounds of the corner-radius multiplier. Below 0.5 a control stops reading as a control. */
+const RADIUS_SCALE = {
+	min: .5,
+	max: 2,
+	step: .05
+};
+/** Bounds of the density nudge, either side of the ladder's own 0.85 / 1 / 1.3. */
+const DENSITY_NUDGE = {
+	min: .8,
+	max: 1.25,
+	step: .05
+};
+/** What each type stack is called in the panel. */
+const FONT_LABELS = {
+	"font-sans": "Sans stack",
+	"font-mono": "Mono stack",
+	"font-display": "Display stack"
+};
+/** Base UI hands a range slider an array; every slider here has one thumb. */
+const single = (value) => Array.isArray(value) ? value[0] ?? 0 : value;
+/**
+* A number knob wired to one token, live on drag and persisted on release.
+*
+* The three it is used for are `--cue-radius-scale` and `--cue-density`, both
+* crossed with the density ladder when they are written, and `--cue-font-scale`,
+* which the provider publishes inline. Naming them here is not decoration: the
+* package manifest's token list is scraped for literal `--cue-*` spellings, and
+* a token whose only spelling in this file is the bare `token="radius-scale"`
+* prop is a token the docs page for this section does not list.
+*/
+function ScaleSlider({ label, token, edits, bounds }) {
+	const value = Number(edits.value(token));
+	return /* @__PURE__ */ jsx(Slider, {
+		label,
+		"aria-label": label,
+		showValue: true,
+		min: bounds.min,
+		max: bounds.max,
+		step: bounds.step,
+		value: Number.isFinite(value) ? value : 1,
+		onValueChange: (next) => edits.set(token, String(single(next))),
+		onCommit: () => edits.commit()
+	});
+}
+/** A free-text token (a font stack, a tracking value) with a draft the user can fix. */
+function TextTokenField({ label, token, edits, placeholder }) {
+	const value = edits.value(token);
+	const [draft, setDraft] = React.useState(value);
+	const [invalid, setInvalid] = React.useState(false);
+	React.useEffect(() => {
+		setDraft(value);
+		setInvalid(false);
+	}, [value]);
+	const commit = () => {
+		if (draft === value) return;
+		if (!isSafeCssValue(draft)) {
+			setInvalid(true);
+			return;
+		}
+		setInvalid(false);
+		edits.set(token, draft);
+		edits.commit();
+	};
+	return /* @__PURE__ */ jsxs(Field, {
+		className: "gap-(--cue-space-1)",
+		children: [/* @__PURE__ */ jsx(FieldLabel, {
+			className: "font-mono text-(length:--cue-text-micro) tracking-[0.15em] uppercase",
+			children: label
+		}), /* @__PURE__ */ jsx(Input, {
+			size: "sm",
+			value: draft,
+			placeholder,
+			spellCheck: false,
+			autoComplete: "off",
+			"aria-invalid": invalid ? "true" : void 0,
+			onValueChange: (next) => setDraft(next),
+			onBlur: commit,
+			onKeyDown: (event) => {
+				if (event.key !== "Enter") return;
+				event.preventDefault();
+				commit();
+			}
+		})]
+	});
+}
+/**
+* Section 1 — the four choices that are not token edits at all.
+*
+* Preset, mode and density are *provider* state: picking one restamps the
+* document and every portal under it, which is why they live here rather than
+* in the colour list. Text scale and zoom are the two relief valves the spec
+* pairs with the density ladder — one scales the type ramp inside the layout,
+* the other scales the finished layout itself.
+*
+* @example
+* <PresetSection edits={edits} zoom={zoom} />
+*/
+function PresetSection({ edits, zoom, className }) {
+	const { theme, density, mode, resolvedMode, setTheme, setDensity, setMode } = useTheme();
+	const themes = useThemes();
+	const densities = useDensities();
+	return /* @__PURE__ */ jsxs(SectionHeader, {
+		label: "Preset",
+		collapsible: true,
+		className,
+		children: [
+			themes.length === 0 ? /* @__PURE__ */ jsxs("p", {
+				className: "text-fg-muted text-ui",
+				children: [
+					"No themes registered — pass ",
+					/* @__PURE__ */ jsx("code", { children: "themes" }),
+					" to ",
+					/* @__PURE__ */ jsx("code", { children: "ThemeProvider" }),
+					"."
+				]
+			}) : /* @__PURE__ */ jsx("div", {
+				className: "grid grid-cols-2 gap-(--cue-space-2)",
+				children: themes.map((manifest) => {
+					const name = manifest.name;
+					const palette = resolve(manifest, { mode: resolvedMode }).colors;
+					const active = name === theme;
+					return /* @__PURE__ */ jsxs("button", {
+						type: "button",
+						"aria-pressed": active,
+						"data-slot": "configurator-preset",
+						onClick: () => setTheme(name),
+						className: cn("flex cursor-pointer flex-col gap-(--cue-space-2) rounded-(--radius-control) border p-(--cue-space-2) text-left outline-none focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-1 focus-visible:outline-accent", active ? "border-accent text-accent" : "border-border text-fg-muted hover:border-border-strong hover:text-fg"),
+						children: [/* @__PURE__ */ jsx("span", {
+							className: "truncate font-mono text-(length:--cue-text-label)",
+							children: name
+						}), /* @__PURE__ */ jsx("span", {
+							className: "flex h-(--cue-space-4) overflow-hidden rounded-[2px]",
+							children: SWATCH_TOKENS.map((token) => /* @__PURE__ */ jsx("span", {
+								"data-slot": "configurator-swatch",
+								className: "flex-1 bg-(--swatch)",
+								style: { "--swatch": palette[token] }
+							}, token))
+						})]
+					}, name);
+				})
+			}),
+			/* @__PURE__ */ jsx(SegmentedControl, {
+				"aria-label": "Mode",
+				size: "sm",
+				className: "w-full",
+				itemClassName: "flex-1",
+				value: mode,
+				onValueChange: (next) => setMode(next),
+				items: MODE_ITEMS.map((item) => ({
+					value: item.value,
+					label: item.label
+				}))
+			}),
+			/* @__PURE__ */ jsx(SegmentedControl, {
+				"aria-label": "Density",
+				size: "sm",
+				className: "w-full",
+				itemClassName: "flex-1",
+				value: density,
+				onValueChange: (next) => setDensity(next),
+				items: densities.map((rung) => ({
+					value: rung.name,
+					label: densityLabel(rung.name)
+				}))
+			}),
+			/* @__PURE__ */ jsx(ScaleSlider, {
+				label: "Text scale",
+				token: "font-scale",
+				edits,
+				bounds: FONT_SCALE
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "flex flex-col gap-(--cue-space-2)",
+				children: [/* @__PURE__ */ jsx(Slider, {
+					label: "Zoom",
+					"aria-label": "Zoom",
+					showValue: true,
+					min: zoom.min,
+					max: zoom.max,
+					step: zoom.step,
+					value: zoom.zoom,
+					onValueChange: (next) => zoom.setZoom(single(next))
+				}), /* @__PURE__ */ jsxs("span", {
+					className: "flex items-center gap-(--cue-space-2) font-mono text-(length:--cue-text-micro) text-fg-subtle",
+					children: [
+						/* @__PURE__ */ jsx(Kbd, { children: "⌘" }),
+						/* @__PURE__ */ jsx(Kbd, { children: "+" }),
+						/* @__PURE__ */ jsx(Kbd, { children: "−" }),
+						/* @__PURE__ */ jsx(Kbd, { children: "0" }),
+						"scales the whole page, not the tokens"
+					]
+				})]
+			})
+		]
+	});
+}
+/**
+* Section 2 — every colour the active theme declares, one row each.
+*
+* The rows are grouped by what the colour does; the editing itself lives in
+* {@link TokenEditor}, which is stateless and reusable.
+*
+* @example
+* <ColorsSection edits={edits} />
+*/
+function ColorsSection({ edits, className }) {
+	const values = Object.fromEntries(COLOR_TOKENS.map((token) => [tokenProperty(token), edits.value(token)]));
+	const overridden = new Set(COLOR_TOKENS.filter((token) => edits.overridden(token)).map(tokenProperty));
+	return /* @__PURE__ */ jsx(SectionHeader, {
+		label: "Colors",
+		collapsible: true,
+		count: overridden.size || void 0,
+		className,
+		children: /* @__PURE__ */ jsx(TokenEditor, {
+			values,
+			overridden,
+			onTokenChange: (token, value) => {
+				edits.set(token, value);
+				edits.commit();
+			},
+			onTokenReset: (token) => {
+				edits.reset(token);
+				edits.commit();
+			}
+		})
+	});
+}
+/**
+* Section 3 — the geometry and type knobs, which belong to the *density* axis
+* rather than to the theme.
+*
+* Both multipliers are crossed with the density ladder when they are written, so
+* nudging the radius keeps `ultra-compact` tighter than `large` instead of
+* flattening the two. The density knob is the published `--cue-density` escape
+* hatch (spec §6): the shipped control ladder is three hand-authored blocks, not
+* a multiplier, so this scales bespoke app geometry — `calc(200px *
+* var(--cue-density))` — and the picker above is what moves the controls.
+*
+* @example
+* <ShapeSection edits={edits} />
+*/
+function ShapeSection({ edits, className }) {
+	return /* @__PURE__ */ jsxs(SectionHeader, {
+		label: "Shape & type",
+		collapsible: true,
+		className,
+		children: [
+			/* @__PURE__ */ jsx(ScaleSlider, {
+				label: "Corner radius",
+				token: "radius-scale",
+				edits,
+				bounds: RADIUS_SCALE
+			}),
+			/* @__PURE__ */ jsx(ScaleSlider, {
+				label: "Density factor",
+				token: "density",
+				edits,
+				bounds: DENSITY_NUDGE
+			}),
+			/* @__PURE__ */ jsxs("p", {
+				className: "font-mono text-(length:--cue-text-micro) leading-(--cue-leading-ui) text-fg-subtle",
+				children: [
+					"Density factor scales app geometry that reads ",
+					/* @__PURE__ */ jsx("code", { children: "var(--cue-density)" }),
+					". The control ladder itself is three authored blocks — use the density picker for it."
+				]
+			}),
+			FONT_TOKENS.map((token) => /* @__PURE__ */ jsx(TextTokenField, {
+				label: FONT_LABELS[token],
+				token,
+				edits
+			}, token)),
+			/* @__PURE__ */ jsx(TextTokenField, {
+				label: "Label tracking",
+				token: "tracking-label",
+				edits,
+				placeholder: "0.12em"
+			})
+		]
+	});
+}
+//#endregion
+export { ColorsSection, PresetSection, ShapeSection };

package/dist/configurator/token-editor.d.ts

@@ -0,0 +1,74 @@
+import { COLOR_TOKENS } from "./_overrides.js";
+import * as React from "react";
+//#region src/configurator/token-editor.d.ts
+/**
+ * The colour half of the configurator: every token a theme block declares, as a
+ * row you can pick a colour into.
+ *
+ * Two decisions worth stating.
+ *
+ * **The row is named by its property, not by a friendly label.** `--cue-fg-muted`
+ * is uglier than "Secondary text" and far more useful: it is the string that
+ * goes into the export, the string an app overrides in its own stylesheet, and
+ * the string the docs index by. A configurator that teaches a second vocabulary
+ * would leave the user to translate it back by hand.
+ *
+ * **Every row is alpha-capable.** Half the shipped presets author their ink and
+ * their borders as `rgba(255,255,255,0.10)` — translucency is how a theme keeps
+ * a border tied to whatever surface it lands on — so a picker that quietly
+ * dropped alpha would break those themes on the first edit.
+ */
+/** One labelled run of token rows. */
+interface TokenGroup {
+  /** Stable id, used as the React key. */
+  id: string;
+  /** What the group is called in the panel. */
+  label: string;
+  /** Bare token names, in display order. */
+  tokens: readonly string[];
+}
+/**
+ * The colour tokens, grouped the way the panel shows them.
+ *
+ * Grouped by *what the colour does* rather than by where it sits in the token
+ * file: a user opening the panel is looking for "the accent" or "the status
+ * colours", not for declaration seventeen. Covers `THEME_COLOR_TOKENS` exactly —
+ * a test enforces it, because a token missing from this list is a theme the
+ * configurator silently cannot express.
+ */
+declare const COLOR_TOKEN_GROUPS: readonly TokenGroup[];
+interface TokenEditorProps {
+  /** Current values, keyed by `--cue-*` property. */
+  values: Record<string, string>;
+  /** Which properties carry an override rather than the preset's value. */
+  overridden: ReadonlySet<string>;
+  /** Called with the `--cue-*` property and its new value. */
+  onTokenChange: (token: string, value: string) => void;
+  /** Called with the `--cue-*` property to put back to the preset's value. */
+  onTokenReset: (token: string) => void;
+  /** Groups to render. Defaults to {@link COLOR_TOKEN_GROUPS}. */
+  groups?: readonly TokenGroup[];
+  /** Extra classes for the list. */
+  className?: string;
+}
+/**
+ * The grouped colour rows.
+ *
+ * Stateless by design: it renders the values it is handed and reports edits
+ * back. The configurator owns the override model, and so does anything else
+ * that wants to reuse these rows.
+ *
+ * `react-aria-components` is an **optional peer** (it arrives with
+ * `ColorPicker`): import this from `@cueplusplus/ui/configurator`.
+ *
+ * @example
+ * <TokenEditor
+ *   values={resolvedTokens(overrides, scope)}
+ *   overridden={new Set(Object.keys(overrides.themes[scopeKey(scope)] ?? {}))}
+ *   onTokenChange={(token, value) => setOverrides(setOverride(overrides, scope, token, value))}
+ *   onTokenReset={(token) => setOverrides(clearOverride(overrides, scope, token))}
+ * />
+ */
+declare function TokenEditor({ values, overridden, onTokenChange, onTokenReset, groups, className }: TokenEditorProps): React.JSX.Element;
+//#endregion
+export { COLOR_TOKEN_GROUPS, TokenEditor, TokenEditorProps, TokenGroup };

package/dist/configurator/token-editor.js

@@ -0,0 +1,152 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { IconButton } from "../primitives/icon-button.js";
+import { tokenProperty } from "../theming/serialize.js";
+import { ColorPicker } from "../color/color-picker.js";
+import "./_overrides.js";
+import { ResetGlyph } from "./_glyphs.js";
+import "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/configurator/token-editor.tsx
+/**
+* The colour tokens, grouped the way the panel shows them.
+*
+* Grouped by *what the colour does* rather than by where it sits in the token
+* file: a user opening the panel is looking for "the accent" or "the status
+* colours", not for declaration seventeen. Covers `THEME_COLOR_TOKENS` exactly —
+* a test enforces it, because a token missing from this list is a theme the
+* configurator silently cannot express.
+*/
+const COLOR_TOKEN_GROUPS = [
+	{
+		id: "ground",
+		label: "Ground & surfaces",
+		tokens: [
+			"bg",
+			"sunken",
+			"surface-1",
+			"surface-2",
+			"surface-3",
+			"data-ground",
+			"scrim"
+		]
+	},
+	{
+		id: "ink",
+		label: "Ink",
+		tokens: [
+			"fg",
+			"fg-muted",
+			"fg-subtle"
+		]
+	},
+	{
+		id: "borders",
+		label: "Borders",
+		tokens: [
+			"border",
+			"border-strong",
+			"border-overlay"
+		]
+	},
+	{
+		id: "accent",
+		label: "Accent",
+		tokens: [
+			"accent",
+			"accent-hover",
+			"accent-fg",
+			"focus",
+			"selection"
+		]
+	},
+	{
+		id: "status",
+		label: "Status",
+		tokens: [
+			"ok",
+			"busy",
+			"warn",
+			"warn-fg",
+			"danger",
+			"danger-fg",
+			"info",
+			"stream"
+		]
+	}
+];
+/** One token: its name, its swatch, and — once it has moved — its way back. */
+function TokenRow({ property, value, overridden, onTokenChange, onTokenReset }) {
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "configurator-token",
+		"data-token": property,
+		"data-overridden": overridden ? "true" : void 0,
+		className: "flex items-center gap-(--cue-space-2)",
+		children: [
+			/* @__PURE__ */ jsx("span", {
+				className: cn("min-w-0 flex-1 truncate font-mono text-(length:--cue-text-label)", overridden ? "text-accent" : "text-fg-muted"),
+				children: property
+			}),
+			/* @__PURE__ */ jsx(ColorPicker, {
+				label: property,
+				value,
+				onValueChange: (next) => onTokenChange(property, next),
+				size: "sm",
+				alpha: true,
+				className: "max-w-[9rem] shrink-0"
+			}),
+			overridden ? /* @__PURE__ */ jsx(IconButton, {
+				"aria-label": `Reset ${property}`,
+				icon: ResetGlyph,
+				size: "sm",
+				onClick: () => onTokenReset(property)
+			}) : /* @__PURE__ */ jsx("span", {
+				"aria-hidden": "true",
+				className: "size-control-sm shrink-0"
+			})
+		]
+	});
+}
+/**
+* The grouped colour rows.
+*
+* Stateless by design: it renders the values it is handed and reports edits
+* back. The configurator owns the override model, and so does anything else
+* that wants to reuse these rows.
+*
+* `react-aria-components` is an **optional peer** (it arrives with
+* `ColorPicker`): import this from `@cueplusplus/ui/configurator`.
+*
+* @example
+* <TokenEditor
+*   values={resolvedTokens(overrides, scope)}
+*   overridden={new Set(Object.keys(overrides.themes[scopeKey(scope)] ?? {}))}
+*   onTokenChange={(token, value) => setOverrides(setOverride(overrides, scope, token, value))}
+*   onTokenReset={(token) => setOverrides(clearOverride(overrides, scope, token))}
+* />
+*/
+function TokenEditor({ values, overridden, onTokenChange, onTokenReset, groups = COLOR_TOKEN_GROUPS, className }) {
+	return /* @__PURE__ */ jsx("div", {
+		"data-slot": "configurator-token-editor",
+		className: cn("flex flex-col gap-(--cue-space-4)", className),
+		children: groups.map((group) => /* @__PURE__ */ jsxs("div", {
+			"data-slot": "configurator-token-group",
+			className: "flex flex-col gap-(--cue-space-2)",
+			children: [/* @__PURE__ */ jsx("span", {
+				className: "font-mono text-(length:--cue-text-micro) tracking-[0.15em] text-fg-subtle uppercase",
+				children: group.label
+			}), group.tokens.map((token) => {
+				const property = tokenProperty(token);
+				return /* @__PURE__ */ jsx(TokenRow, {
+					property,
+					value: values[property] ?? "",
+					overridden: overridden.has(property),
+					onTokenChange,
+					onTokenReset
+				}, property);
+			})]
+		}, group.id))
+	});
+}
+//#endregion
+export { COLOR_TOKEN_GROUPS, TokenEditor };

package/dist/configurator/use-zoom.d.ts

@@ -0,0 +1,87 @@
+//#region src/configurator/use-zoom.d.ts
+/**
+ * The root zoom valve — luma's relief mechanism, adopted system-wide.
+ *
+ * Density is a *design* decision made in discrete, hand-authored steps; zoom is
+ * a *comfort* decision the person at the keyboard makes, continuously, about
+ * this screen at this distance. Conflating the two is how systems end up with a
+ * naive multiplier and blurry half-pixel geometry, so this is deliberately not a
+ * token: it sets the CSS `zoom` property on one element and lets the browser
+ * scale the finished layout, which keeps every hairline crisp and every rem
+ * ratio intact.
+ *
+ * The range is 0.7–1.5 because that is the band luma's console shipped and the
+ * spec adopted: below 0.7 the 9px type stops being type, above 1.5 the
+ * ultra-compact ladder has stopped being ultra-compact and the density picker is
+ * the better tool.
+ *
+ * @example
+ * const zoom = useZoom();
+ * <Slider aria-label="Zoom" min={zoom.min} max={zoom.max} value={zoom.zoom} onValueChange={zoom.setZoom} />
+ */
+/** Floor of the valve — below this the type ladder stops being legible. */
+declare const MIN_ZOOM = 0.7;
+/** Ceiling of the valve — above this, pick a larger density instead. */
+declare const MAX_ZOOM = 1.5;
+/** One notch of the valve, and of ⌘+ / ⌘−. */
+declare const ZOOM_STEP = 0.1;
+interface UseZoomOptions {
+  /** Current zoom, for a controlled valve. Pair with `onZoomChange`. */
+  zoom?: number;
+  /** Starting zoom for an uncontrolled valve. Defaults to `1`. */
+  defaultZoom?: number;
+  /** Called with every new value, clamped and rounded. */
+  onZoomChange?: (zoom: number) => void;
+  /** Floor. Defaults to {@link MIN_ZOOM}. */
+  min?: number;
+  /** Ceiling. Defaults to {@link MAX_ZOOM}. */
+  max?: number;
+  /** Size of one notch. Defaults to {@link ZOOM_STEP}. */
+  step?: number;
+  /**
+   * Element to scale. Defaults to `<html>`, which is the point of a *root* zoom;
+   * pass `null` to run the valve as state only and apply it yourself.
+   */
+  target?: HTMLElement | null;
+  /**
+   * Bind ⌘/Ctrl with `+`, `-` and `0`, taking those combinations away from the
+   * browser's own zoom. Defaults to `true`.
+   */
+  shortcuts?: boolean;
+}
+/** What {@link useZoom} hands back. */
+interface ZoomValve {
+  /** Current zoom. */
+  zoom: number;
+  /** Set it, clamped into range and rounded to two decimals. */
+  setZoom: (zoom: number) => void;
+  /** One notch up. */
+  zoomIn: () => void;
+  /** One notch down. */
+  zoomOut: () => void;
+  /** Back to 1, which also takes the declaration out of the document. */
+  reset: () => void;
+  /** The floor in force. */
+  min: number;
+  /** The ceiling in force. */
+  max: number;
+  /** The notch in force. */
+  step: number;
+}
+/**
+ * A bounded, stepped root-zoom valve with the usual keyboard shortcuts.
+ *
+ * Controlled or uncontrolled, the same way every other control in this system
+ * is: pass `zoom` to own the value, `defaultZoom` to let the hook own it.
+ *
+ * The declaration belongs to the hook while it is mounted — unmounting takes it
+ * back off, so a configurator that is closed does not leave the page at 1.4.
+ *
+ * @param options - Range, target, controlled value, shortcut opt-out.
+ * @returns The valve: the value and the four ways to move it.
+ * @example
+ * const { zoom, zoomIn, zoomOut, reset } = useZoom({ shortcuts: false });
+ */
+declare function useZoom(options?: UseZoomOptions): ZoomValve;
+//#endregion
+export { MAX_ZOOM, MIN_ZOOM, UseZoomOptions, ZOOM_STEP, ZoomValve, useZoom };