@cube-dev/ui-kit 0.165.0 → 0.167.0

package/dist/tokens/base.js.map

@@ -1 +1 @@
-{"version":3,"file":"base.js","names":[],"sources":["../../src/tokens/base.ts"],"sourcesContent":["import type { Styles } from '@tenphi/tasty';\n\n/**\n * Base design system tokens.\n * These define the fundamental units and values used throughout the system.\n *\n * Keys use $ prefix for CSS custom properties.\n */\nexport const BASE_TOKENS: Styles = {\n  // Typography base\n  /** @deprecated Use preset tokens instead */\n  '$font-size': '14px',\n  /** @deprecated Use preset tokens instead */\n  '$line-height': '20px',\n\n  // Input typography\n  '$input-font-size': '14px',\n  '$input-line-height': '20px',\n  '$input-letter-spacing': '0.02em',\n\n  // Opacity & dimensions\n  /** Opacity for disabled elements */\n  '$disabled-opacity': '.4',\n  /** Base gap unit for spacing (used with `.5x`, `1x`, `2x` etc.) */\n  $gap: '8px',\n  /** Stroke width for icons */\n  '$stroke-width': 1.5,\n  /** Focus outline width */\n  '$outline-width': 'calc(1rem / 16 * 3)',\n  /** Border width for bordered elements */\n  '$border-width': '1px',\n\n  // Border radius\n  /** Base border radius (used with `1r`, `2r` etc.) */\n  $radius: '6px',\n  /** Larger radius using tasty calc: 1r + 0.5x */\n  '$large-radius': '(1r + .5x)',\n  /** Card border radius */\n  '$card-radius': '(1r + .5x)',\n  /** Sharp corner for leaf shapes */\n  '$sharp-radius': '0px',\n\n  // Misc dimensions\n  /** Minimum dialog width (responsive) */\n  '$min-dialog-size': 'min(288px, calc(100vw - (2 * var(--gap))))',\n\n  // Transitions\n  /** Default transition duration */\n  $transition: '80ms',\n  /** Transition for disclosure animations */\n  '$disclosure-transition': '120ms',\n  /** Transition for tab animations */\n  '$tab-transition': '120ms',\n  /** Transition for fade animations */\n  '$fade-transition': '200ms',\n\n  // Scrollbar tokens\n  '$scrollbar-width': '1.5x',\n  '$scrollbar-outline-width': '1ow',\n  '$scrollbar-radius': '1.5r',\n  '#scrollbar-thumb': '#text.5',\n  '#scrollbar-outline': '#clear',\n  '#scrollbar-bg': '#surface-2',\n  '#scrollbar-corner': '#clear',\n};\n"],"mappings":";;;;;;;;AAQA,MAAa,cAAsB;CAGjC,cAAc;CAEd,gBAAgB;CAGhB,oBAAoB;CACpB,sBAAsB;CACtB,yBAAyB;CAIzB,qBAAqB;CAErB,MAAM;CAEN,iBAAiB;CAEjB,kBAAkB;CAElB,iBAAiB;CAIjB,SAAS;CAET,iBAAiB;CAEjB,gBAAgB;CAEhB,iBAAiB;CAIjB,oBAAoB;CAIpB,aAAa;CAEb,0BAA0B;CAE1B,mBAAmB;CAEnB,oBAAoB;CAGpB,oBAAoB;CACpB,4BAA4B;CAC5B,qBAAqB;CACrB,oBAAoB;CACpB,sBAAsB;CACtB,iBAAiB;CACjB,qBAAqB;CACtB"}
+{"version":3,"file":"base.js","names":[],"sources":["../../src/tokens/base.ts"],"sourcesContent":["import type { Styles } from '@tenphi/tasty';\n\n/**\n * Base design system tokens.\n * These define the fundamental units and values used throughout the system.\n *\n * Keys use $ prefix for CSS custom properties.\n */\nexport const BASE_TOKENS: Styles = {\n  // Typography base\n  /** @deprecated Use preset tokens instead */\n  '$font-size': '14px',\n  /** @deprecated Use preset tokens instead */\n  '$line-height': '20px',\n\n  // Input typography\n  '$input-font-size': '14px',\n  '$input-line-height': '20px',\n  '$input-letter-spacing': '0.02em',\n\n  // Opacity & dimensions\n  /** Opacity for disabled elements */\n  '$disabled-opacity': '.4',\n  /** Base gap unit for spacing (used with `.5x`, `1x`, `2x` etc.) */\n  $gap: '8px',\n  /** Stroke width for icons */\n  '$stroke-width': 1.5,\n  /** Focus outline width */\n  '$outline-width': 'calc(1rem / 16 * 3)',\n  /** Border width for bordered elements */\n  '$border-width': '1px',\n\n  // Border radius\n  /** Base border radius (used with `1r`, `2r` etc.) */\n  $radius: '6px',\n  /** Larger radius using tasty calc: 1r + 0.5x */\n  '$large-radius': '(1r + .5x)',\n  /** Card border radius */\n  '$card-radius': '(1r + .5x)',\n  /** Sharp corner for leaf shapes */\n  '$sharp-radius': '0px',\n\n  // Misc dimensions\n  /** Minimum dialog width (responsive) */\n  '$min-dialog-size': 'min(288px, calc(100vw - (2 * var(--gap))))',\n\n  // Transitions\n  /** Default transition duration */\n  $transition: '80ms',\n  /** Transition for disclosure animations */\n  '$disclosure-transition': '120ms',\n  /** Transition for tab animations */\n  '$tab-transition': '120ms',\n  /** Transition for fade animations */\n  '$fade-transition': '200ms',\n\n  /**\n   * Marks an element as carrying the token block. Not a design value — nothing\n   * styles against it.\n   *\n   * `resolveTokenValue()` reads it to answer the one question a computed value\n   * cannot: \"are the kit's tokens in effect here?\" Tasty registers `@property`\n   * defaults with real initial values — `--gap` is `4px` off the block, not\n   * `0px` — so a token read from outside `<Root>` comes back plausible and\n   * wrong, and no amount of inspecting the value would reveal it. This is\n   * declared alongside the tokens, so it is present exactly where they are.\n   */\n  '$tokens-applied': '1',\n\n  // Scrollbar tokens\n  '$scrollbar-width': '1.5x',\n  '$scrollbar-outline-width': '1ow',\n  '$scrollbar-radius': '1.5r',\n  '#scrollbar-thumb': '#text.5',\n  '#scrollbar-outline': '#clear',\n  '#scrollbar-bg': '#surface-2',\n  '#scrollbar-corner': '#clear',\n};\n"],"mappings":";;;;;;;;AAQA,MAAa,cAAsB;CAGjC,cAAc;CAEd,gBAAgB;CAGhB,oBAAoB;CACpB,sBAAsB;CACtB,yBAAyB;CAIzB,qBAAqB;CAErB,MAAM;CAEN,iBAAiB;CAEjB,kBAAkB;CAElB,iBAAiB;CAIjB,SAAS;CAET,iBAAiB;CAEjB,gBAAgB;CAEhB,iBAAiB;CAIjB,oBAAoB;CAIpB,aAAa;CAEb,0BAA0B;CAE1B,mBAAmB;CAEnB,oBAAoB;CAapB,mBAAmB;CAGnB,oBAAoB;CACpB,4BAA4B;CAC5B,qBAAqB;CACrB,oBAAoB;CACpB,sBAAsB;CACtB,iBAAiB;CACjB,qBAAqB;CACtB"}

package/dist/tokens/color-seed.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.165.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.167.0 | Cube Dev Team */
 import { glaze } from "@tenphi/glaze";
 
 //#region src/tokens/color-seed.ts

package/dist/tokens/color-theme.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.165.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.167.0 | Cube Dev Team */
 import { colorSeed } from "./color-seed.js";
 import { DEFAULT_HUE, DEFAULT_SATURATION, getPaletteConfig, getPaletteVersion, usePaletteVersion } from "./palette-config.js";
 import { tintRecipe } from "./palette.js";

package/dist/tokens/colors.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.165.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.167.0 | Cube Dev Team */
 import { getPaletteVersion } from "./palette-config.js";
 import { BASE_TOKENS } from "./base.js";
 import { lazyStyles } from "./lazy-styles.js";

package/dist/tokens/index.d.ts

@@ -1,6 +1,8 @@
 
 import { DEFAULT_PALETTE_CONFIG, MAX_BASE_SATURATION, PaletteCodeSeed, PaletteConfig, PaletteNumericSeed, PaletteSeed, PaletteThemeName, ResolvedPaletteConfig, ResolvedThemeSeed, SurfaceMode, getPaletteConfig, getPaletteConfigInput, invalidatePaletteTokens, resetPaletteConfig, resolvePaletteConfig, setPaletteConfig, subscribePaletteConfig, usePaletteConfig, usePaletteVersion } from "./palette-config.js";
 import { SIZES, SIZE_NAME_TO_KEY, SIZE_TOKENS, SizeKey, SizeName } from "./sizes.js";
+import { TOKENS, getTokens } from "./all-tokens.js";
+import { ResolveTokenOptions, ResolvedPreset, resolvePresetValues, resolveTokenValue, resolveTokenValues, usePresetValues, useTokenValue, useTokenValues } from "./resolve.js";
 import { PALETTE_TOKENS, RenderPaletteOptions, getCodeTheme, getPalette, getPaletteTokens, renderPaletteTokens } from "./palette.js";
 import { COLOR_TOKENS, getColorTokens, renderColorTokens } from "./colors.js";
 import { ColorSeed, colorSeed } from "./color-seed.js";
@@ -9,13 +11,4 @@ import { SPACE_TOKENS } from "./spacing.js";
 import { SHADOW_TOKENS } from "./shadows.js";
 import { LAYOUT_TOKENS } from "./layout.js";
 import { BASE_TOKENS } from "./base.js";
-import { TYPOGRAPHY_PRESETS } from "./typography.js";
-import { Styles } from "@tenphi/tasty";
-
-//#region src/tokens/index.d.ts
-declare function getTokens(): Styles;
-/** Lazy proxy of {@link getTokens}. Prefer `getTokens()` in new code. */
-declare const TOKENS: Styles;
-//#endregion
-export { TOKENS, getTokens };
-//# sourceMappingURL=index.d.ts.map
+import { TYPOGRAPHY_PRESETS } from "./typography.js";

package/dist/tokens/layout.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.165.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.167.0 | Cube Dev Team */
 //#region src/tokens/layout.ts
 /**
 * Layout-related tokens for common UI dimensions.

package/dist/tokens/lazy-styles.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.165.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.167.0 | Cube Dev Team */
 //#region src/tokens/lazy-styles.ts
 /**
 * Proxy that defers to `factory()` on every property / enumeration access.

package/dist/tokens/palette-config.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.165.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.167.0 | Cube Dev Team */
 import { colorSeed } from "./color-seed.js";
 import { useSyncExternalStore } from "react";
 

package/dist/tokens/palette.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.165.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.167.0 | Cube Dev Team */
 import { SURFACE_SATURATION_SHARE, getPaletteConfig, getPaletteVersion, resolvePaletteConfig } from "./palette-config.js";
 import { lazyStyles } from "./lazy-styles.js";
 import { apcaContrast, glaze, okhslToLinearSrgb, variantToOkhsl } from "@tenphi/glaze";

package/dist/tokens/resolve.d.ts

@@ -0,0 +1,113 @@
+
+//#region src/tokens/resolve.d.ts
+interface ResolveTokenOptions {
+  /**
+   * Element to read the tokens off. Defaults to the document `<body>`, which is
+   * where `<Root>` declares them.
+   *
+   * Pass an element when the value has to reflect a *local* override — a subtree
+   * carrying its own `tokens` prop (`renderColorTokens()`), or one under a
+   * `data-schema` / `data-contrast` attribute that differs from the document's.
+   * The element's own document and view are used, so a node inside a same-origin
+   * iframe resolves against that iframe.
+   */
+  element?: Element | null;
+  /**
+   * Returned in place of `null` when a token is unset, unresolvable, or reads
+   * back as an `@property` placeholder — including on the server, where there is
+   * no DOM to read.
+   */
+  fallback?: string;
+}
+/**
+ * Fields mirror {@link TypographyPreset}. A field the preset does not define is
+ * `null`, except `fontFamily`, which falls back to the document's `--font-sans`
+ * so the common case (`t1`–`t4`, `h1`–`h6`, which inherit the sans stack rather
+ * than naming it) still hands back a usable stack.
+ */
+type ResolvedPreset = {
+  fontFamily: string | null;
+  fontSize: string | null;
+  fontStyle: string | null;
+  fontWeight: string | null;
+  lineHeight: string | null;
+  letterSpacing: string | null;
+  textTransform: string | null;
+  boldFontWeight: string | null;
+  iconSize: string | null;
+};
+/**
+ * Read the resolved value of one design token — a color, a length, a font
+ * descriptor — as a literal string.
+ *
+ * ```ts
+ * resolveTokenValue('#purple'); // 'oklch(0.52 0.24 285)'
+ * resolveTokenValue('$space-md'); // '8px'
+ * resolveTokenValue('$t3-font-size'); // '14px'
+ * ```
+ *
+ * Returns `options.fallback ?? null` when the token is not declared on the
+ * element it was read from — see {@link ResolveTokenOptions}.
+ */
+declare function resolveTokenValue(token: string, options?: ResolveTokenOptions): string | null;
+/**
+ * {@link resolveTokenValue} for several tokens at once, through a single
+ * `getComputedStyle` call. Prefer this when building a theme object — a Stripe
+ * `Appearance`, a CodeMirror theme — which needs a dozen values at a time.
+ *
+ * ```ts
+ * const { '#surface': background, '#surface-text': color } = resolveTokenValues([
+ *   '#surface',
+ *   '#surface-text',
+ * ]);
+ * ```
+ */
+declare function resolveTokenValues<T extends string>(tokens: readonly T[], options?: ResolveTokenOptions): Record<T, string | null>;
+/**
+ * Resolve a typography preset — `'t3'`, `'h2'`, `'s3'` — to the literal font
+ * descriptors behind it, for a surface that takes a font as values rather than
+ * as a `preset` style.
+ *
+ * ```ts
+ * const { fontFamily, fontSize, lineHeight } = resolvePresetValues('t3');
+ * ```
+ *
+ * A preset legitimately leaves most of these unset — only headings carry an
+ * `iconSize`, only the `s*` family names a `fontFamily` — so unlike
+ * {@link resolveTokenValues} a miss here is expected and never warns.
+ */
+declare function resolvePresetValues(preset: string, options?: ResolveTokenOptions): ResolvedPreset;
+/**
+ * {@link resolveTokenValue} as a hook: re-renders when the palette is re-seeded
+ * or the scheme / contrast tier flips.
+ *
+ * ```tsx
+ * const accent = useTokenValue('#purple');
+ *
+ * return <Chart series={{ color: accent ?? '#000' }} />;
+ * ```
+ */
+declare function useTokenValue(token: string, options?: ResolveTokenOptions): string | null;
+/**
+ * {@link resolveTokenValues} as a hook. The returned object keeps its identity
+ * while the values are unchanged, so it is safe as a dependency of the theme
+ * object built from it — and the token list may be an inline literal.
+ *
+ * ```tsx
+ * const colors = useTokenValues(['#surface', '#surface-text', '#border']);
+ *
+ * const appearance = useMemo(() => toStripeAppearance(colors), [colors]);
+ * ```
+ */
+declare function useTokenValues<T extends string>(tokens: readonly T[], options?: ResolveTokenOptions): Record<T, string | null>;
+/**
+ * {@link resolvePresetValues} as a hook.
+ *
+ * ```tsx
+ * const { fontFamily, fontSize } = usePresetValues('s3');
+ * ```
+ */
+declare function usePresetValues(preset: string, options?: ResolveTokenOptions): ResolvedPreset;
+//#endregion
+export { ResolveTokenOptions, ResolvedPreset, resolvePresetValues, resolveTokenValue, resolveTokenValues, usePresetValues, useTokenValue, useTokenValues };
+//# sourceMappingURL=resolve.d.ts.map

package/dist/tokens/resolve.js

@@ -0,0 +1,403 @@
+/** @license MIT | @cube-dev/ui-kit v0.167.0 | Cube Dev Team */
+import { useLayoutEffect as useLayoutEffect$1 } from "../utils/react/useLayoutEffect.js";
+import { warn } from "../utils/warnings.js";
+import { getPaletteVersion, usePaletteVersion } from "./palette-config.js";
+import { getTokens } from "./all-tokens.js";
+import { useState, useSyncExternalStore } from "react";
+
+//#region src/tokens/resolve.ts
+/**
+* Resolving a design token to a literal value, for consumers that render into a
+* surface our stylesheets do not reach — a third-party iframe (Stripe Elements),
+* a CodeMirror / Monaco theme object, a Vega spec. Those take colors, lengths and
+* font descriptors as values; `var(--purple-color)` means nothing to them.
+*
+* Doing it by hand fails silently, because a token read from the wrong element
+* does not come back empty. Tasty registers `@property` rules — its own defaults
+* plus one for every custom property whose type it can infer — and an undeclared
+* token reads back as that rule's `initial-value`. Some of those are obvious
+* duds (`rgba(0, 0, 0, 0)` for a `<color>`, `0px` for a `<length>`), but many are
+* ordinary-looking values: off the token block `--gap` reads `4px` rather than
+* the kit's `8px`, `--transition` reads `80ms`, `--radius` reads `6px`. So
+* inspecting the value cannot tell a real token from a miss, in either
+* direction — `#clear` really is `transparent` and `$h2-letter-spacing` really
+* is `0px`.
+*
+* The question that CAN be answered is "are the kit's tokens in effect on this
+* element?", and `$tokens-applied` (see `src/tokens/base.ts`) answers it: it is
+* declared alongside the tokens, so it is present exactly where they are. Off
+* that surface every read is reported as unresolved; on it, the computed value
+* is the truth.
+*/
+/**
+* Declared by the token block and nothing else — see `src/tokens/base.ts`.
+*
+* Matched by VALUE rather than by presence, because presence is not the signal
+* it looks like: tasty infers a type for the marker as readily as for any other
+* token, registers `@property --tokens-applied` with `initial-value: 0`, and so
+* hands back `0` off the block instead of an empty string. Comparing against the
+* declared value is right either way, and cannot drift from `base.ts`.
+*/
+const SURFACE_MARKER = "$tokens-applied";
+function isTokenSurface(computed) {
+	const declared = getTokens()[SURFACE_MARKER];
+	const name = tokenToProperty(SURFACE_MARKER);
+	if (typeof declared !== "string" || !name) return false;
+	return normalizeValue(computed.getPropertyValue(name)) === normalizeValue(declared);
+}
+/**
+* Values that mean "this property was never declared" once we already know the
+* token block IS in effect. Only used to catch a token the kit does not declare
+* at all — a typo, or a name from another design system — since for those there
+* is no marker to lean on.
+*/
+const PLACEHOLDER_VALUES = new Set([
+	"transparent",
+	"rgba(0,0,0,0)",
+	"0",
+	"0px",
+	"0deg",
+	"0s"
+]);
+/** Custom property names are CSS identifiers: a letter or `_`, then word chars or `-`. */
+const PROPERTY_NAME_RE = /^[a-zA-Z_][\w-]*$/;
+const PRESET_FIELD_SUFFIXES = {
+	fontFamily: "font-family",
+	fontSize: "font-size",
+	fontStyle: "font-style",
+	fontWeight: "font-weight",
+	lineHeight: "line-height",
+	letterSpacing: "letter-spacing",
+	textTransform: "text-transform",
+	boldFontWeight: "bold-font-weight",
+	iconSize: "icon-size"
+};
+const PRESET_FIELDS = Object.keys(PRESET_FIELD_SUFFIXES);
+/**
+* Map a token to its CSS custom property name, using the same convention tasty's
+* style DSL does: `#name` is a color (`--name-color`), `$name` is everything else
+* (`--name`). A raw `--name` or a bare `name` is taken as written.
+*
+* Returns `null` for anything that would not be a valid custom property.
+*/
+function tokenToProperty(token) {
+	const trimmed = token.trim();
+	let name;
+	if (trimmed.startsWith("--")) name = trimmed.slice(2);
+	else if (trimmed.startsWith("#")) name = `${trimmed.slice(1)}-color`;
+	else if (trimmed.startsWith("$")) name = trimmed.slice(1);
+	else name = trimmed;
+	return PROPERTY_NAME_RE.test(name) ? `--${name}` : null;
+}
+/** Whitespace and case are not meaningful in the values we compare against. */
+function normalizeValue(value) {
+	return value.replace(/\s+/g, "").toLowerCase();
+}
+/**
+* Every custom property the kit declares, by name. Membership only — the value
+* is deliberately not consulted, because a token's declared value tells you
+* nothing about whether it is in effect where you read it.
+*
+* Memoized against the palette version, like {@link getTokens} itself.
+*/
+let knownNamesCache = null;
+function getKnownTokenNames() {
+	const version = getPaletteVersion();
+	if (!knownNamesCache || knownNamesCache.version !== version) {
+		const names = /* @__PURE__ */ new Set();
+		for (const key of Object.keys(getTokens())) {
+			const name = tokenToProperty(key);
+			if (name) names.add(name);
+		}
+		knownNamesCache = {
+			version,
+			names
+		};
+	}
+	return knownNamesCache.names;
+}
+/** These fire per token, per page — once each, not once per render. */
+const warnedTokens = /* @__PURE__ */ new Set();
+function warnOnce(key, message) {
+	if (warnedTokens.has(key)) return;
+	warnedTokens.add(key);
+	warn(message);
+}
+/** The document `<body>` is where `<Root>` declares the token block. */
+function resolveTarget(element) {
+	if (element) return element;
+	if (typeof document === "undefined") return null;
+	return document.body ?? document.documentElement ?? null;
+}
+function readValue(computed, token, fallback, silent, onTokenSurface) {
+	const name = tokenToProperty(token);
+	if (!name) {
+		warnOnce(`name:${token}`, `"${token}" is not a valid design token name.`);
+		return fallback;
+	}
+	if (!onTokenSurface) {
+		if (!silent) warnOnce(`surface:${name}`, `Token "${token}" (${name}) was read from an element the design tokens are not in effect on, so any value there is tasty's @property default rather than the kit's. <Root> declares the token block on <body>, so <html>, a detached node, and a tree that has not mounted <Root> yet are all outside it. Pass \`element\` to read from a specific subtree, or \`fallback\` for a value to use instead.`);
+		return fallback;
+	}
+	const value = computed.getPropertyValue(name).trim();
+	if (!value) return fallback;
+	if (PLACEHOLDER_VALUES.has(normalizeValue(value)) && !getKnownTokenNames().has(name)) {
+		if (!silent) warnOnce(`unknown:${name}`, `Token "${token}" (${name}) is not declared by the kit, and read back as an unset custom property. Check the name, or pass \`fallback\`.`);
+		return fallback;
+	}
+	return value;
+}
+/**
+* Read the resolved value of one design token — a color, a length, a font
+* descriptor — as a literal string.
+*
+* ```ts
+* resolveTokenValue('#purple'); // 'oklch(0.52 0.24 285)'
+* resolveTokenValue('$space-md'); // '8px'
+* resolveTokenValue('$t3-font-size'); // '14px'
+* ```
+*
+* Returns `options.fallback ?? null` when the token is not declared on the
+* element it was read from — see {@link ResolveTokenOptions}.
+*/
+function resolveTokenValue(token, options = {}) {
+	return resolveTokenValues([token], options)[token];
+}
+/**
+* {@link resolveTokenValue} for several tokens at once, through a single
+* `getComputedStyle` call. Prefer this when building a theme object — a Stripe
+* `Appearance`, a CodeMirror theme — which needs a dozen values at a time.
+*
+* ```ts
+* const { '#surface': background, '#surface-text': color } = resolveTokenValues([
+*   '#surface',
+*   '#surface-text',
+* ]);
+* ```
+*/
+function resolveTokenValues(tokens, options = {}) {
+	return readTokens(tokens, options, false);
+}
+/** Shared by the public reader and the preset reader, which suppresses warnings. */
+function readTokens(tokens, options, silent) {
+	const { element, fallback = null } = options;
+	const result = {};
+	const target = resolveTarget(element);
+	const view = target?.ownerDocument?.defaultView;
+	if (!target || !view) {
+		for (const token of tokens) result[token] = fallback;
+		return result;
+	}
+	const computed = view.getComputedStyle(target);
+	const onTokenSurface = isTokenSurface(computed);
+	for (const token of tokens) result[token] = readValue(computed, token, fallback, silent, onTokenSurface);
+	return result;
+}
+/**
+* Resolve a typography preset — `'t3'`, `'h2'`, `'s3'` — to the literal font
+* descriptors behind it, for a surface that takes a font as values rather than
+* as a `preset` style.
+*
+* ```ts
+* const { fontFamily, fontSize, lineHeight } = resolvePresetValues('t3');
+* ```
+*
+* A preset legitimately leaves most of these unset — only headings carry an
+* `iconSize`, only the `s*` family names a `fontFamily` — so unlike
+* {@link resolveTokenValues} a miss here is expected and never warns.
+*/
+function resolvePresetValues(preset, options = {}) {
+	const { fallback = null } = options;
+	const names = PRESET_FIELDS.map((field) => `$${preset}-${PRESET_FIELD_SUFFIXES[field]}`);
+	const values = readTokens([...names, "--font-sans"], { element: options.element }, true);
+	const resolved = {};
+	PRESET_FIELDS.forEach((field, index) => {
+		resolved[field] = values[names[index]] ?? fallback;
+	});
+	resolved.fontFamily = values[names[PRESET_FIELDS.indexOf("fontFamily")]] ?? values["--font-sans"] ?? fallback;
+	return resolved;
+}
+/**
+* A token's resolved value changes for two reasons: the palette was re-seeded
+* (`setPaletteConfig()`, covered by `usePaletteVersion`), or the scheme /
+* contrast tier flipped. This store covers the second.
+*
+* Both axes are the ones `@dark` and `@hc` resolve against (see
+* `src/components/Root.tsx`): the `data-schema` / `data-contrast` attributes on
+* `<html>`, and the `prefers-color-scheme` / `prefers-contrast` media queries
+* they fall back to. An attribute flip is invisible to `matchMedia` and a system
+* flip is invisible to a `MutationObserver`, so both are watched.
+*/
+const APPEARANCE_QUERIES = ["(prefers-color-scheme: dark)", "(prefers-contrast: more)"];
+const APPEARANCE_ATTRIBUTES = ["data-schema", "data-contrast"];
+let appearanceVersion = 0;
+let stopWatchingAppearance = null;
+const appearanceListeners = /* @__PURE__ */ new Set();
+function onAppearanceChange() {
+	appearanceVersion++;
+	appearanceListeners.forEach((listener) => listener());
+}
+function watchAppearance() {
+	const teardowns = [];
+	if (typeof window.matchMedia === "function") for (const query of APPEARANCE_QUERIES) {
+		const list = window.matchMedia(query);
+		if (typeof list?.addEventListener !== "function") continue;
+		list.addEventListener("change", onAppearanceChange);
+		teardowns.push(() => list.removeEventListener("change", onAppearanceChange));
+	}
+	if (typeof MutationObserver === "function" && document.documentElement) {
+		const observer = new MutationObserver(onAppearanceChange);
+		observer.observe(document.documentElement, {
+			attributes: true,
+			attributeFilter: APPEARANCE_ATTRIBUTES
+		});
+		teardowns.push(() => observer.disconnect());
+	}
+	return () => teardowns.forEach((teardown) => teardown());
+}
+function subscribeAppearance(listener) {
+	appearanceListeners.add(listener);
+	if (appearanceListeners.size === 1 && typeof window !== "undefined") stopWatchingAppearance = watchAppearance();
+	return () => {
+		appearanceListeners.delete(listener);
+		if (!appearanceListeners.size) {
+			stopWatchingAppearance?.();
+			stopWatchingAppearance = null;
+		}
+	};
+}
+function getAppearanceVersion() {
+	return appearanceVersion;
+}
+/**
+* A version React only ever hands out while rendering on the server or
+* hydrating: `useSyncExternalStore` reads `getServerSnapshot` in exactly those
+* two cases and `getSnapshot` in every other. That makes it a reliable "this
+* render has to match the server's markup" flag — see {@link useResolvedTokens}.
+*
+* A plain client render (`createRoot`) never sees it, so a CSR app still
+* resolves on its first render rather than paying an extra pass.
+*/
+const HYDRATING = -1;
+function getServerAppearanceVersion() {
+	return HYDRATING;
+}
+/**
+* Re-render on a scheme / contrast change. Returns the version rather than the
+* state so the snapshot is a primitive — the same reason `usePaletteVersion`
+* does, see `src/tokens/palette-config.ts`.
+*/
+function useAppearanceVersion() {
+	return useSyncExternalStore(subscribeAppearance, getAppearanceVersion, getServerAppearanceVersion);
+}
+/**
+* The value is read out of the DOM, so it re-resolves whenever the palette is
+* re-seeded or the scheme / contrast tier flips, and it is `fallback ?? null`
+* during SSR. The layout effect is what covers the first commit: a consumer
+* rendered in the same pass as `<Root>` reads before the token block lands.
+*/
+function useResolvedTokens(tokens, key, options) {
+	const { element, fallback } = options;
+	const paletteVersion = usePaletteVersion();
+	const appearance = useAppearanceVersion();
+	const [values, setValues] = useState(() => appearance === HYDRATING ? unresolved(tokens, fallback) : resolveTokenValues(tokens, options));
+	useLayoutEffect$1(() => {
+		setValues((previous) => {
+			const next = resolveTokenValues(tokens, {
+				element,
+				fallback
+			});
+			return isSameRecord(previous, next) ? previous : next;
+		});
+	}, [
+		key,
+		element,
+		fallback,
+		paletteVersion,
+		appearance
+	]);
+	return values;
+}
+/**
+* What the server rendered: no DOM, so every token is the fallback. The first
+* client render has to agree with it or hydration reports a mismatch for any
+* consumer that renders the value; the layout effect above replaces it with the
+* resolved values before the browser paints.
+*/
+function unresolved(tokens, fallback) {
+	const result = {};
+	for (const token of tokens) result[token] = fallback ?? null;
+	return result;
+}
+/** Keeps the previous object when nothing moved, so it stays usable as a dep. */
+function isSameRecord(a, b) {
+	const keys = Object.keys(b);
+	if (Object.keys(a).length !== keys.length) return false;
+	return keys.every((key) => a[key] === b[key]);
+}
+/**
+* {@link resolveTokenValue} as a hook: re-renders when the palette is re-seeded
+* or the scheme / contrast tier flips.
+*
+* ```tsx
+* const accent = useTokenValue('#purple');
+*
+* return <Chart series={{ color: accent ?? '#000' }} />;
+* ```
+*/
+function useTokenValue(token, options = {}) {
+	return useResolvedTokens([token], token, options)[token];
+}
+/**
+* {@link resolveTokenValues} as a hook. The returned object keeps its identity
+* while the values are unchanged, so it is safe as a dependency of the theme
+* object built from it — and the token list may be an inline literal.
+*
+* ```tsx
+* const colors = useTokenValues(['#surface', '#surface-text', '#border']);
+*
+* const appearance = useMemo(() => toStripeAppearance(colors), [colors]);
+* ```
+*/
+function useTokenValues(tokens, options = {}) {
+	return useResolvedTokens(tokens, tokens.join(" "), options);
+}
+/**
+* {@link resolvePresetValues} as a hook.
+*
+* ```tsx
+* const { fontFamily, fontSize } = usePresetValues('s3');
+* ```
+*/
+function usePresetValues(preset, options = {}) {
+	const { element, fallback } = options;
+	const paletteVersion = usePaletteVersion();
+	const appearance = useAppearanceVersion();
+	const [values, setValues] = useState(() => appearance === HYDRATING ? unresolvedPreset(fallback) : resolvePresetValues(preset, options));
+	useLayoutEffect$1(() => {
+		setValues((previous) => {
+			const next = resolvePresetValues(preset, {
+				element,
+				fallback
+			});
+			return isSameRecord(previous, next) ? previous : next;
+		});
+	}, [
+		preset,
+		element,
+		fallback,
+		paletteVersion,
+		appearance
+	]);
+	return values;
+}
+/** {@link unresolved} for the fixed shape {@link resolvePresetValues} returns. */
+function unresolvedPreset(fallback) {
+	const resolved = {};
+	for (const field of PRESET_FIELDS) resolved[field] = fallback ?? null;
+	return resolved;
+}
+
+//#endregion
+export { resolvePresetValues, resolveTokenValue, resolveTokenValues, usePresetValues, useTokenValue, useTokenValues };
+//# sourceMappingURL=resolve.js.map