@cube-dev/ui-kit 0.152.0 → 0.154.0

package/dist/tokens/palette-config.js

@@ -0,0 +1,309 @@
+/** @license MIT | @cube-dev/ui-kit v0.154.0 | Cube Dev Team */
+import { useSyncExternalStore } from "react";
+
+//#region src/tokens/palette-config.ts
+/**
+* Runtime configuration for the Glaze-generated color palette.
+*
+* The palette recipe itself lives in `./palette.ts`; this module owns only the
+* *seeds* it is built from, plus a version counter the token caches watch. It
+* deliberately imports nothing else — not the token modules, not `glaze` — so
+* there is no import cycle and no ordering hazard.
+*
+* Reading is free; writing rebuilds the palette on the next token read. See
+* `Getting Started/Theming` in Storybook for the full contract.
+*/
+/** Brand hue. Drives the `default`, `primary`, `purple` and `special` themes. */
+const DEFAULT_HUE = 280.3;
+const DEFAULT_SUCCESS_HUE = 156.9;
+const DEFAULT_DANGER_HUE = 23.1;
+const DEFAULT_WARNING_HUE = 84.3;
+const DEFAULT_NOTE_HUE = 302.3;
+/** Seed saturation. Per-color `saturation` in the recipe is a 0–1 factor of it. */
+const DEFAULT_SATURATION = 80;
+const DEFAULT_THEME_HUES = {
+	success: DEFAULT_SUCCESS_HUE,
+	danger: DEFAULT_DANGER_HUE,
+	warning: DEFAULT_WARNING_HUE,
+	note: DEFAULT_NOTE_HUE
+};
+function resolveConfig(input) {
+	const saturation = input.saturation ?? DEFAULT_SATURATION;
+	const themes = input.themes ?? {};
+	const hue = input.hue ?? DEFAULT_HUE;
+	return {
+		hue,
+		baseHue: input.baseHue ?? hue,
+		saturation,
+		pastel: input.pastel ?? false,
+		contrastLevel: input.contrastLevel ?? "auto",
+		themes: {
+			success: {
+				hue: themes.success?.hue ?? DEFAULT_THEME_HUES.success,
+				saturation: themes.success?.saturation ?? saturation
+			},
+			danger: {
+				hue: themes.danger?.hue ?? DEFAULT_THEME_HUES.danger,
+				saturation: themes.danger?.saturation ?? saturation
+			},
+			warning: {
+				hue: themes.warning?.hue ?? DEFAULT_THEME_HUES.warning,
+				saturation: themes.warning?.saturation ?? saturation
+			},
+			note: {
+				hue: themes.note?.hue ?? DEFAULT_THEME_HUES.note,
+				saturation: themes.note?.saturation ?? saturation
+			},
+			code: { saturation: themes.code?.saturation ?? DEFAULT_SATURATION }
+		}
+	};
+}
+/**
+* The palette as it ships, with no tuning applied. Frozen — it is the baseline
+* every resolution falls back to, so a stray write to it would move the defaults
+* for the whole process.
+*/
+const DEFAULT_PALETTE_CONFIG = freezeConfig(resolveConfig({}));
+/**
+* The last config *as written*, sparse — not the resolved one. Keeping the sparse
+* form is what makes inheritance live: a `saturation` with no `themes.danger.
+* saturation` beside it means danger genuinely follows the palette, rather than
+* having been frozen at whatever the palette read when it was set.
+*/
+let input = {};
+let resolved = DEFAULT_PALETTE_CONFIG;
+let version = 0;
+const listeners = /* @__PURE__ */ new Set();
+function mergeSeed(base, patch) {
+	if (!base) return patch;
+	if (!patch) return base;
+	return {
+		...base,
+		...patch
+	};
+}
+/**
+* Layer a patch over a base config. Used by {@link resolvePaletteConfig} for
+* previews — *not* by {@link setPaletteConfig}, which replaces.
+*/
+function mergeInput(base, patch) {
+	const next = {
+		...base,
+		...patch
+	};
+	if (base.themes || patch.themes) next.themes = {
+		success: mergeSeed(base.themes?.success, patch.themes?.success),
+		danger: mergeSeed(base.themes?.danger, patch.themes?.danger),
+		warning: mergeSeed(base.themes?.warning, patch.themes?.warning),
+		note: mergeSeed(base.themes?.note, patch.themes?.note),
+		code: mergeSeed(base.themes?.code, patch.themes?.code)
+	};
+	return next;
+}
+function isSameConfig(a, b) {
+	return a.hue === b.hue && a.baseHue === b.baseHue && a.saturation === b.saturation && a.pastel === b.pastel && a.contrastLevel === b.contrastLevel && a.themes.code.saturation === b.themes.code.saturation && [
+		"success",
+		"danger",
+		"warning",
+		"note"
+	].every((name) => a.themes[name].hue === b.themes[name].hue && a.themes[name].saturation === b.themes[name].saturation);
+}
+/**
+* Which fields are *explicitly set*, as an order-independent signature.
+*
+* Two configs can resolve to identical values yet differ in which of those values
+* are pinned rather than inherited — pinning `primary.saturation` to the number it
+* already inherited is the obvious case. That difference is invisible to
+* {@link isSameConfig} but visible through {@link getPaletteConfigInput}, so it has
+* to count as a change or a settings UI reading it would never re-render.
+*/
+function pinSignature(config) {
+	const set = (value) => value === void 0 ? "0" : "1";
+	return [
+		set(config.hue),
+		set(config.baseHue),
+		set(config.saturation),
+		set(config.pastel),
+		set(config.contrastLevel),
+		set(config.themes?.code?.saturation),
+		...[
+			"success",
+			"danger",
+			"warning",
+			"note"
+		].flatMap((name) => [set(config.themes?.[name]?.hue), set(config.themes?.[name]?.saturation)])
+	].join("");
+}
+/**
+* Snapshot a config so the store owns it outright.
+*
+* Two hazards this closes. The caller's object stays theirs, so mutating it after
+* the call cannot desync `input` from `resolved`. And what we hand back from
+* {@link getPaletteConfig} / {@link getPaletteConfigInput} is frozen, so a caller
+* who writes to it gets a clear failure rather than silently corrupting the store
+* — the version would not bump, and every token cache would go on serving values
+* that no longer match the config.
+*/
+function freezeConfig(config) {
+	const themes = config.themes;
+	if (themes) {
+		for (const seed of Object.values(themes)) if (seed) Object.freeze(seed);
+		Object.freeze(themes);
+	}
+	return Object.freeze(config);
+}
+/** {@link freezeConfig} on a copy, for a config we did not create ourselves. */
+function snapshotConfig(config) {
+	const themes = config.themes;
+	return freezeConfig({
+		...config,
+		...themes ? { themes: {
+			...themes.success ? { success: { ...themes.success } } : null,
+			...themes.danger ? { danger: { ...themes.danger } } : null,
+			...themes.warning ? { warning: { ...themes.warning } } : null,
+			...themes.note ? { note: { ...themes.note } } : null,
+			...themes.code ? { code: { ...themes.code } } : null
+		} } : null
+	});
+}
+function commit(nextInput) {
+	const nextResolved = resolveConfig(nextInput);
+	if (isSameConfig(resolved, nextResolved) && pinSignature(input) === pinSignature(nextInput)) return;
+	input = snapshotConfig(nextInput);
+	resolved = freezeConfig(nextResolved);
+	version++;
+	listeners.forEach((listener) => listener());
+}
+/**
+* Set the palette config.
+*
+* **Replaces**, like `useState` — the config you pass *is* the config, resolved
+* against the shipped defaults. Nothing accumulates, so a field you leave out is a
+* field you do not have: dropping a customization means dropping it from the
+* object, and re-applying the same object twice is the same as applying it once.
+*
+* ```ts
+* setPaletteConfig({ hue: 200, baseHue: 60 });
+* setPaletteConfig({ hue: 200 }); // baseHue is gone — back to inheriting `hue`
+* ```
+*
+* To adjust one field of the config already in place — a slider in a settings UI —
+* pass an updater. It receives the config as written, sparse, so spreading it
+* preserves which fields are pinned and which still inherit:
+*
+* ```ts
+* setPaletteConfig((config) => ({ ...config, hue: 200 }));
+* ```
+*
+* The palette is rebuilt lazily on the next token read, and any mounted `<Root>`
+* re-injects the token block — no component re-render is involved, because every
+* color in the kit resolves through a CSS custom property.
+*/
+function setPaletteConfig(config) {
+	commit(typeof config === "function" ? config(input) : config);
+}
+/**
+* Drop all tuning and restore the palette the kit ships with. Identical to
+* `setPaletteConfig({})`; it exists to be readable at a call site.
+*/
+function resetPaletteConfig() {
+	commit({});
+}
+/**
+* Force every token to re-resolve without changing the palette config.
+*
+* Only needed if you drive Glaze directly — `glaze.configure({ darkTone })` and
+* the like. Glaze invalidates its own caches, but the kit's token maps are
+* memoized against *this* module's version, so they need telling. Calling it
+* before the first paint is unnecessary; nothing has been resolved yet.
+*/
+function invalidatePaletteTokens() {
+	version++;
+	listeners.forEach((listener) => listener());
+}
+/** The current config, with every field resolved to a concrete value. */
+function getPaletteConfig() {
+	return resolved;
+}
+/**
+* The config **as set**, sparse — omitted fields are the ones still inheriting.
+*
+* {@link getPaletteConfig} resolves everything to concrete values, which loses the
+* distinction between "explicitly 80" and "80 because it follows the brand". A
+* settings UI needs that distinction to show an inherited value as inherited, and
+* to offer a way back:
+*
+* ```ts
+* const pinned = getPaletteConfigInput().baseHue !== undefined;
+*
+* // Re-link it to the brand by dropping the field.
+* setPaletteConfig(({ baseHue, ...config }) => config);
+* ```
+*
+* It is also the value handed to a {@link setPaletteConfig} updater.
+*/
+function getPaletteConfigInput() {
+	return input;
+}
+/**
+* Resolve a patch **over** the current config, without applying it.
+*
+* This one layers, unlike {@link setPaletteConfig}: a preview wants "the theme in
+* use, but in dark", so the fields it does not mention have to come from the live
+* config rather than from the defaults. The store is not touched and no listener
+* fires.
+*/
+function resolvePaletteConfig(config) {
+	if (!config) return resolved;
+	return resolveConfig(mergeInput(input, config));
+}
+/**
+* Increments whenever the resolved config changes. The token caches in
+* `./palette.ts`, `./colors.ts` and `./index.ts` compare against it instead of
+* memoizing forever — the same idiom Glaze uses for its own config version.
+*/
+function getPaletteVersion() {
+	return version;
+}
+/** Subscribe to palette config changes. Returns an unsubscribe function. */
+function subscribePaletteConfig(listener) {
+	listeners.add(listener);
+	return () => {
+		listeners.delete(listener);
+	};
+}
+/**
+* Re-render on palette config changes. Returns the version, not the config, so
+* the snapshot is a primitive and React never warns about an uncached snapshot.
+*/
+function usePaletteVersion() {
+	return useSyncExternalStore(subscribePaletteConfig, getPaletteVersion, getPaletteVersion);
+}
+/**
+* Read and tune the palette from React, `useState`-style — including the part
+* where the setter *replaces*. A control that changes one field wants the updater
+* form, or it will drop every other field:
+*
+* ```tsx
+* const [palette, setPalette] = usePaletteConfig();
+*
+* <HueSlider
+*   value={palette.hue}
+*   onChange={(hue) => setPalette((config) => ({ ...config, hue }))}
+* />
+* ```
+*
+* The first element is the *resolved* config, so `palette.hue` is always a number.
+* The updater's argument is the sparse one — see {@link getPaletteConfigInput}.
+*
+* The config is global process state, so every consumer of this hook — and every
+* mounted `<Root>` — sees the same palette.
+*/
+function usePaletteConfig() {
+	usePaletteVersion();
+	return [getPaletteConfig(), setPaletteConfig];
+}
+
+//#endregion
+export { DEFAULT_PALETTE_CONFIG, getPaletteConfig, getPaletteConfigInput, getPaletteVersion, invalidatePaletteTokens, resetPaletteConfig, resolvePaletteConfig, setPaletteConfig, subscribePaletteConfig, usePaletteConfig, usePaletteVersion };
+//# sourceMappingURL=palette-config.js.map

package/dist/tokens/palette-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"palette-config.js","names":[],"sources":["../../src/tokens/palette-config.ts"],"sourcesContent":["import { useSyncExternalStore } from 'react';\n\n/**\n * Runtime configuration for the Glaze-generated color palette.\n *\n * The palette recipe itself lives in `./palette.ts`; this module owns only the\n * *seeds* it is built from, plus a version counter the token caches watch. It\n * deliberately imports nothing else — not the token modules, not `glaze` — so\n * there is no import cycle and no ordering hazard.\n *\n * Reading is free; writing rebuilds the palette on the next token read. See\n * `Getting Started/Theming` in Storybook for the full contract.\n */\n\n// ============================================================================\n// Default seeds\n// ============================================================================\n\n/** Brand hue. Drives the `default`, `primary`, `purple` and `special` themes. */\nexport const DEFAULT_HUE = 280.3;\nexport const DEFAULT_SUCCESS_HUE = 156.9;\nexport const DEFAULT_DANGER_HUE = 23.1;\nexport const DEFAULT_WARNING_HUE = 84.3;\nexport const DEFAULT_NOTE_HUE = 302.3;\n\n/** Seed saturation. Per-color `saturation` in the recipe is a 0–1 factor of it. */\nexport const DEFAULT_SATURATION = 80;\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/** Hue / saturation seed override for one colored theme. */\nexport interface PaletteThemeSeed {\n  /** Hue in degrees (0–360). */\n  hue?: number;\n  /** Saturation (0–100). Defaults to the palette-level `saturation`. */\n  saturation?: number;\n}\n\n/**\n * The `code-*` syntax family takes a saturation and nothing else.\n *\n * Its hues are absolute literals by design, so syntax colors never rotate with the\n * brand — strings would collide with numbers the moment the brand went green. And\n * unlike every other theme, its saturation does **not** inherit the palette-level\n * one: the code palette is calibrated once and stays there, so re-seeding the app\n * cannot quietly wash out a code block.\n */\nexport interface PaletteCodeSeed {\n  /** Saturation (0–100). Defaults to {@link DEFAULT_SATURATION}, not to `saturation`. */\n  saturation?: number;\n}\n\n/** Names of the themes whose seeds can be overridden individually. */\nexport type PaletteThemeName =\n  | 'success'\n  | 'danger'\n  | 'warning'\n  | 'note'\n  | 'code';\n\n/**\n * Palette tuning. Every field is optional; omitted fields keep their default,\n * and per-theme fields left unset inherit the palette-level value.\n */\nexport interface PaletteConfig {\n  /**\n   * Accent hue in degrees (0–360) — the brand.\n   *\n   * Drives the `accent-*` family on every theme, `primary` / `purple` / `special`,\n   * and the brand-tinted odds and ends (`focus`, the loading faces, the disabled\n   * chip). Also the default for {@link PaletteConfig.baseHue}.\n   */\n  hue?: number;\n  /**\n   * Hue of the **base** zone in degrees (0–360): the neutral chrome — `surface`\n   * and its ladder, the `surface-text*` ramp, `border`, `placeholder`. Defaults to\n   * `hue`, so the chrome carries a faint tint of the brand unless you say otherwise.\n   *\n   * Splitting it lets the chrome sit on a different hue from the accent — a warm\n   * grey UI with a cool blue brand, say. Only the `default` theme is affected: a\n   * colored theme's tinted `surface` deliberately follows *its own* hue, because a\n   * danger banner should read as red.\n   */\n  baseHue?: number;\n  /**\n   * Seed saturation (0–100), and the fallback for every theme that does not set\n   * its own.\n   *\n   * One scale for the whole theme, by design. Every color's own `saturation` is a\n   * 0–1 factor of this seed — `surface` at 0.12, `border` at 0.175, the text ramp\n   * at 0.2, the accent family at ~1.0 — so moving it rescales the palette while\n   * keeping those proportions. Unlike hue, which is configured separately for the\n   * brand and for each status theme, saturation is deliberately not split: the\n   * ratio between a subtle surface tint and a saturated accent is part of the\n   * design.\n   */\n  saturation?: number;\n  /**\n   * Global. Widens the usable chroma range by relaxing the sRGB-safe limit,\n   * producing a softer, more even palette across hues. Glaze treats `pastel` as\n   * instance-level, so it is threaded into every theme.\n   */\n  pastel?: boolean;\n  /**\n   * Global. `'auto'` (the default) keeps the two-tier model: normal colors plus\n   * a separate high-contrast tier driven by `<html data-contrast=\"high\">` /\n   * `prefers-contrast: more`.\n   *\n   * A number (0–100) replaces that switch with a slider — and, because a manual\n   * level already carries the contrast preference, **drops the high-contrast\n   * tier entirely**. `0` reproduces the normal output and `100` the\n   * high-contrast output, bit for bit.\n   */\n  contrastLevel?: number | 'auto';\n  /** Per-theme seed overrides. */\n  themes?: {\n    success?: PaletteThemeSeed;\n    danger?: PaletteThemeSeed;\n    warning?: PaletteThemeSeed;\n    note?: PaletteThemeSeed;\n    code?: PaletteCodeSeed;\n  };\n}\n\n/** {@link PaletteConfig} with every field resolved to a concrete value. */\nexport interface ResolvedPaletteConfig {\n  hue: number;\n  baseHue: number;\n  saturation: number;\n  pastel: boolean;\n  contrastLevel: number | 'auto';\n  themes: {\n    success: { hue: number; saturation: number };\n    danger: { hue: number; saturation: number };\n    warning: { hue: number; saturation: number };\n    note: { hue: number; saturation: number };\n    code: { saturation: number };\n  };\n}\n\n// ============================================================================\n// Resolution\n// ============================================================================\n\nconst DEFAULT_THEME_HUES = {\n  success: DEFAULT_SUCCESS_HUE,\n  danger: DEFAULT_DANGER_HUE,\n  warning: DEFAULT_WARNING_HUE,\n  note: DEFAULT_NOTE_HUE,\n} as const;\n\nfunction resolveConfig(input: PaletteConfig): ResolvedPaletteConfig {\n  const saturation = input.saturation ?? DEFAULT_SATURATION;\n  const themes = input.themes ?? {};\n\n  const hue = input.hue ?? DEFAULT_HUE;\n\n  return {\n    hue,\n    baseHue: input.baseHue ?? hue,\n    saturation,\n    pastel: input.pastel ?? false,\n    contrastLevel: input.contrastLevel ?? 'auto',\n    themes: {\n      success: {\n        hue: themes.success?.hue ?? DEFAULT_THEME_HUES.success,\n        saturation: themes.success?.saturation ?? saturation,\n      },\n      danger: {\n        hue: themes.danger?.hue ?? DEFAULT_THEME_HUES.danger,\n        saturation: themes.danger?.saturation ?? saturation,\n      },\n      warning: {\n        hue: themes.warning?.hue ?? DEFAULT_THEME_HUES.warning,\n        saturation: themes.warning?.saturation ?? saturation,\n      },\n      note: {\n        hue: themes.note?.hue ?? DEFAULT_THEME_HUES.note,\n        saturation: themes.note?.saturation ?? saturation,\n      },\n      // Deliberately NOT `?? saturation`: the code palette is calibrated once and\n      // does not follow the palette-level seed. See `PaletteCodeSeed`.\n      code: { saturation: themes.code?.saturation ?? DEFAULT_SATURATION },\n    },\n  };\n}\n\n/**\n * The palette as it ships, with no tuning applied. Frozen — it is the baseline\n * every resolution falls back to, so a stray write to it would move the defaults\n * for the whole process.\n */\nexport const DEFAULT_PALETTE_CONFIG: ResolvedPaletteConfig = freezeConfig(\n  resolveConfig({}),\n);\n\n// ============================================================================\n// Store\n// ============================================================================\n\n/**\n * The last config *as written*, sparse — not the resolved one. Keeping the sparse\n * form is what makes inheritance live: a `saturation` with no `themes.danger.\n * saturation` beside it means danger genuinely follows the palette, rather than\n * having been frozen at whatever the palette read when it was set.\n */\nlet input: PaletteConfig = {};\nlet resolved: ResolvedPaletteConfig = DEFAULT_PALETTE_CONFIG;\nlet version = 0;\n\nconst listeners = new Set<() => void>();\n\nfunction mergeSeed<T extends PaletteThemeSeed | PaletteCodeSeed>(\n  base: T | undefined,\n  patch: T | undefined,\n): T | undefined {\n  if (!base) return patch;\n  // A patch that omits the theme entirely says nothing about it, so the base\n  // survives. Clearing one of its fields is `{ theme: { hue: undefined } }`.\n  if (!patch) return base;\n\n  return { ...base, ...patch };\n}\n\n/**\n * Layer a patch over a base config. Used by {@link resolvePaletteConfig} for\n * previews — *not* by {@link setPaletteConfig}, which replaces.\n */\nfunction mergeInput(base: PaletteConfig, patch: PaletteConfig): PaletteConfig {\n  const next: PaletteConfig = { ...base, ...patch };\n\n  if (base.themes || patch.themes) {\n    next.themes = {\n      success: mergeSeed(base.themes?.success, patch.themes?.success),\n      danger: mergeSeed(base.themes?.danger, patch.themes?.danger),\n      warning: mergeSeed(base.themes?.warning, patch.themes?.warning),\n      note: mergeSeed(base.themes?.note, patch.themes?.note),\n      code: mergeSeed(base.themes?.code, patch.themes?.code),\n    };\n  }\n\n  return next;\n}\n\nfunction isSameConfig(a: ResolvedPaletteConfig, b: ResolvedPaletteConfig) {\n  return (\n    a.hue === b.hue &&\n    a.baseHue === b.baseHue &&\n    a.saturation === b.saturation &&\n    a.pastel === b.pastel &&\n    a.contrastLevel === b.contrastLevel &&\n    a.themes.code.saturation === b.themes.code.saturation &&\n    (['success', 'danger', 'warning', 'note'] as const).every(\n      (name) =>\n        a.themes[name].hue === b.themes[name].hue &&\n        a.themes[name].saturation === b.themes[name].saturation,\n    )\n  );\n}\n\n/**\n * Which fields are *explicitly set*, as an order-independent signature.\n *\n * Two configs can resolve to identical values yet differ in which of those values\n * are pinned rather than inherited — pinning `primary.saturation` to the number it\n * already inherited is the obvious case. That difference is invisible to\n * {@link isSameConfig} but visible through {@link getPaletteConfigInput}, so it has\n * to count as a change or a settings UI reading it would never re-render.\n */\nfunction pinSignature(config: PaletteConfig): string {\n  const set = (value: unknown) => (value === undefined ? '0' : '1');\n\n  return [\n    set(config.hue),\n    set(config.baseHue),\n    set(config.saturation),\n    set(config.pastel),\n    set(config.contrastLevel),\n    set(config.themes?.code?.saturation),\n    ...(['success', 'danger', 'warning', 'note'] as const).flatMap((name) => [\n      set(config.themes?.[name]?.hue),\n      set(config.themes?.[name]?.saturation),\n    ]),\n  ].join('');\n}\n\n/**\n * Snapshot a config so the store owns it outright.\n *\n * Two hazards this closes. The caller's object stays theirs, so mutating it after\n * the call cannot desync `input` from `resolved`. And what we hand back from\n * {@link getPaletteConfig} / {@link getPaletteConfigInput} is frozen, so a caller\n * who writes to it gets a clear failure rather than silently corrupting the store\n * — the version would not bump, and every token cache would go on serving values\n * that no longer match the config.\n */\nfunction freezeConfig<T extends PaletteConfig | ResolvedPaletteConfig>(\n  config: T,\n): T {\n  const themes = config.themes;\n\n  if (themes) {\n    for (const seed of Object.values(themes)) {\n      if (seed) Object.freeze(seed);\n    }\n    Object.freeze(themes);\n  }\n\n  return Object.freeze(config);\n}\n\n/** {@link freezeConfig} on a copy, for a config we did not create ourselves. */\nfunction snapshotConfig(config: PaletteConfig): PaletteConfig {\n  const themes = config.themes;\n\n  return freezeConfig({\n    ...config,\n    ...(themes\n      ? {\n          themes: {\n            ...(themes.success ? { success: { ...themes.success } } : null),\n            ...(themes.danger ? { danger: { ...themes.danger } } : null),\n            ...(themes.warning ? { warning: { ...themes.warning } } : null),\n            ...(themes.note ? { note: { ...themes.note } } : null),\n            ...(themes.code ? { code: { ...themes.code } } : null),\n          },\n        }\n      : null),\n  });\n}\n\nfunction commit(nextInput: PaletteConfig) {\n  const nextResolved = resolveConfig(nextInput);\n\n  // Bail before bumping the version when nothing observable moved, so re-applying\n  // the same config — an inline `<Root palette={{ … }}>` literal on every\n  // render, a StrictMode double render — costs nothing.\n  if (\n    isSameConfig(resolved, nextResolved) &&\n    pinSignature(input) === pinSignature(nextInput)\n  ) {\n    return;\n  }\n\n  input = snapshotConfig(nextInput);\n  resolved = freezeConfig(nextResolved);\n  version++;\n\n  listeners.forEach((listener) => listener());\n}\n\n/**\n * Set the palette config.\n *\n * **Replaces**, like `useState` — the config you pass *is* the config, resolved\n * against the shipped defaults. Nothing accumulates, so a field you leave out is a\n * field you do not have: dropping a customization means dropping it from the\n * object, and re-applying the same object twice is the same as applying it once.\n *\n * ```ts\n * setPaletteConfig({ hue: 200, baseHue: 60 });\n * setPaletteConfig({ hue: 200 }); // baseHue is gone — back to inheriting `hue`\n * ```\n *\n * To adjust one field of the config already in place — a slider in a settings UI —\n * pass an updater. It receives the config as written, sparse, so spreading it\n * preserves which fields are pinned and which still inherit:\n *\n * ```ts\n * setPaletteConfig((config) => ({ ...config, hue: 200 }));\n * ```\n *\n * The palette is rebuilt lazily on the next token read, and any mounted `<Root>`\n * re-injects the token block — no component re-render is involved, because every\n * color in the kit resolves through a CSS custom property.\n */\nexport function setPaletteConfig(\n  config: PaletteConfig | ((previous: PaletteConfig) => PaletteConfig),\n): void {\n  commit(typeof config === 'function' ? config(input) : config);\n}\n\n/**\n * Drop all tuning and restore the palette the kit ships with. Identical to\n * `setPaletteConfig({})`; it exists to be readable at a call site.\n */\nexport function resetPaletteConfig(): void {\n  commit({});\n}\n\n/**\n * Force every token to re-resolve without changing the palette config.\n *\n * Only needed if you drive Glaze directly — `glaze.configure({ darkTone })` and\n * the like. Glaze invalidates its own caches, but the kit's token maps are\n * memoized against *this* module's version, so they need telling. Calling it\n * before the first paint is unnecessary; nothing has been resolved yet.\n */\nexport function invalidatePaletteTokens(): void {\n  version++;\n  listeners.forEach((listener) => listener());\n}\n\n/** The current config, with every field resolved to a concrete value. */\nexport function getPaletteConfig(): ResolvedPaletteConfig {\n  return resolved;\n}\n\n/**\n * The config **as set**, sparse — omitted fields are the ones still inheriting.\n *\n * {@link getPaletteConfig} resolves everything to concrete values, which loses the\n * distinction between \"explicitly 80\" and \"80 because it follows the brand\". A\n * settings UI needs that distinction to show an inherited value as inherited, and\n * to offer a way back:\n *\n * ```ts\n * const pinned = getPaletteConfigInput().baseHue !== undefined;\n *\n * // Re-link it to the brand by dropping the field.\n * setPaletteConfig(({ baseHue, ...config }) => config);\n * ```\n *\n * It is also the value handed to a {@link setPaletteConfig} updater.\n */\nexport function getPaletteConfigInput(): PaletteConfig {\n  return input;\n}\n\n/**\n * Resolve a patch **over** the current config, without applying it.\n *\n * This one layers, unlike {@link setPaletteConfig}: a preview wants \"the theme in\n * use, but in dark\", so the fields it does not mention have to come from the live\n * config rather than from the defaults. The store is not touched and no listener\n * fires.\n */\nexport function resolvePaletteConfig(\n  config?: PaletteConfig,\n): ResolvedPaletteConfig {\n  if (!config) return resolved;\n\n  return resolveConfig(mergeInput(input, config));\n}\n\n/**\n * Increments whenever the resolved config changes. The token caches in\n * `./palette.ts`, `./colors.ts` and `./index.ts` compare against it instead of\n * memoizing forever — the same idiom Glaze uses for its own config version.\n */\nexport function getPaletteVersion(): number {\n  return version;\n}\n\n/** Subscribe to palette config changes. Returns an unsubscribe function. */\nexport function subscribePaletteConfig(listener: () => void): () => void {\n  listeners.add(listener);\n\n  return () => {\n    listeners.delete(listener);\n  };\n}\n\n// ============================================================================\n// React bindings\n// ============================================================================\n\n/**\n * Re-render on palette config changes. Returns the version, not the config, so\n * the snapshot is a primitive and React never warns about an uncached snapshot.\n */\nexport function usePaletteVersion(): number {\n  return useSyncExternalStore(\n    subscribePaletteConfig,\n    getPaletteVersion,\n    getPaletteVersion,\n  );\n}\n\n/**\n * Read and tune the palette from React, `useState`-style — including the part\n * where the setter *replaces*. A control that changes one field wants the updater\n * form, or it will drop every other field:\n *\n * ```tsx\n * const [palette, setPalette] = usePaletteConfig();\n *\n * <HueSlider\n *   value={palette.hue}\n *   onChange={(hue) => setPalette((config) => ({ ...config, hue }))}\n * />\n * ```\n *\n * The first element is the *resolved* config, so `palette.hue` is always a number.\n * The updater's argument is the sparse one — see {@link getPaletteConfigInput}.\n *\n * The config is global process state, so every consumer of this hook — and every\n * mounted `<Root>` — sees the same palette.\n */\nexport function usePaletteConfig(): readonly [\n  ResolvedPaletteConfig,\n  typeof setPaletteConfig,\n] {\n  usePaletteVersion();\n\n  return [getPaletteConfig(), setPaletteConfig];\n}\n"],"mappings":"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"}

package/dist/tokens/palette.d.ts

@@ -1,15 +1,55 @@
 
-import { Styles } from "@tenphi/tasty";
-import "@tenphi/glaze";
+import { PaletteConfig } from "./palette-config.js";
+import { Styles, Tokens } from "@tenphi/tasty";
+import { GlazePalette, GlazeTheme } from "@tenphi/glaze";
 
 //#region src/tokens/palette.d.ts
+/** Which resolved scheme variant {@link renderPaletteTokens} should return. */
+interface RenderPaletteOptions extends PaletteConfig {
+  /** Color scheme to resolve. Default: `'light'`. */
+  scheme?: 'light' | 'dark';
+  /** Resolve the high-contrast variant of that scheme. Default: `false`. */
+  highContrast?: boolean;
+}
+/**
+ * Resolve Glaze palette tokens against the current palette config.
+ *
+ * Memoized against the config version (see `./palette-config.ts`), so repeated
+ * reads are free and `setPaletteConfig()` invalidates them. Resolution is
+ * deferred rather than done at module import, so host apps can call
+ * `setPaletteConfig(...)` / `glaze.configure(...)` after importing
+ * `@cube-dev/ui-kit` and still affect the first paint.
+ *
+ * Keys use `#name` syntax; values are state maps:
+ *   '#surface': { '': 'oklch(...)', '@dark': 'oklch(...)', '@hc': 'oklch(...)' }
+ */
 declare function getPaletteTokens(): Styles;
+/** The live `GlazePalette`. Rebuilt whenever the palette config changes. */
+declare function getPalette(): GlazePalette;
+/**
+ * The live theme behind the `code-*` tokens. Separate from {@link getPalette}
+ * because it carries its own saturation seed — see {@link CODE_COLORS}.
+ */
+declare function getCodeTheme(): GlazeTheme;
+/**
+ * Resolve one scheme variant of a palette to flat, literal color values.
+ *
+ * Unlike {@link getPaletteTokens}, which emits state maps (`@dark` / `@hc`) for
+ * the whole document, this collapses the palette to the single variant you ask
+ * for. That is what makes a **region** preview possible: applied through a tasty
+ * `tokens` prop, the values override the inherited ones for that subtree only, so
+ * a dark or high-contrast theme can be shown inside a light page.
+ *
+ * Prefer `renderColorTokens()` from `./colors` unless you specifically want the
+ * palette without the legacy aliases.
+ */
+declare function renderPaletteTokens(options?: RenderPaletteOptions): Tokens;
 /**
  * Lazy proxy of {@link getPaletteTokens}. Prefer `getPaletteTokens()` in new
- * code. First property / enumeration access resolves against the live glaze
- * config (same memo as the getter).
+ * code. Property / enumeration access always reflects the current palette
+ * config.
  */
 declare const PALETTE_TOKENS: Styles;
 //#endregion
-export { PALETTE_TOKENS, getPaletteTokens };
+export { PALETTE_TOKENS, RenderPaletteOptions, getCodeTheme, getPalette, getPaletteTokens, renderPaletteTokens };
 //# sourceMappingURL=palette.d.ts.map