@unpunnyfuns/swatchbook-blocks 0.54.0 → 0.55.0

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import * as _$react from "react";
 import { ReactElement, ReactNode } from "react";
-import { Axis, Diagnostic, Permutation, Preset } from "@unpunnyfuns/swatchbook-core";
+import { Axis, AxisVarianceResult, Diagnostic, Permutation, Preset } from "@unpunnyfuns/swatchbook-core";
 
 //#region src/format-color.d.ts
 /**
@@ -104,6 +104,21 @@ interface VirtualTokenListingShape {
   };
 }
 type VirtualPresetShape = Preset;
+/**
+ * Wire shape of one `Project.jointOverrides` entry — same as core's
+ * `JointOverride` but with the block's `VirtualTokenShape` for the
+ * token values that ship over the wire.
+ */
+interface VirtualJointOverrideShape {
+  axes: Record<string, string>;
+  tokens: Record<string, VirtualTokenShape>;
+}
+/**
+ * Map from path → cached `AxisVarianceResult`. Snapshot carries this
+ * so the `AxisVariance` block can O(1) look up which axes affect a
+ * token instead of re-running `analyzeAxisVariance` on every render.
+ */
+type VirtualVarianceByPathShape = Record<string, AxisVarianceResult>;
 /**
  * Full project data read by blocks. Populated by the addon's preview
  * decorator (from the virtual module) or constructed by hand in
@@ -114,8 +129,17 @@ interface ProjectSnapshot {
   /** Axis names suppressed via `config.disabledAxes` — pinned to their defaults, hidden from the toolbar. */
   disabledAxes: readonly string[];
   presets: readonly VirtualPresetShape[];
-  permutations: readonly VirtualPermutationShape[];
-  permutationsResolved: Record<string, Record<string, VirtualTokenShape>>;
+  /**
+   * @deprecated Wire-shipped permutations were removed in PR 6a.
+   * Hand-built snapshots (tests, MDX consumers) may still populate
+   * this for backward compatibility with the legacy fallback path
+   * in `useProject`. Production preview snapshots omit it.
+   */
+  permutations?: readonly VirtualPermutationShape[];
+  /**
+   * @deprecated See `permutations`. Wire format dropped in PR 6a.
+   */
+  permutationsResolved?: Record<string, Record<string, VirtualTokenShape>>;
   activePermutation: string;
   activeAxes: Readonly<Record<string, string>>;
   cssVarPrefix: string;
@@ -129,6 +153,41 @@ interface ProjectSnapshot {
    * absent.
    */
   listing?: Readonly<Record<string, VirtualTokenListingShape>>;
+  /**
+   * Per-axis cell maps — `cells[axis][context]` is the resolved token
+   * data for `{ ...defaults, [axis]: context }`. Bounded by
+   * `Σ(axes × contexts)` regardless of cartesian product size.
+   * Optional during the chain rollout — empty fallback when the
+   * snapshot pre-dates the wire format change.
+   */
+  cells?: Record<string, Record<string, Record<string, VirtualTokenShape>>>;
+  /**
+   * `Project.jointOverrides` flattened to entries for wire transport.
+   * Same ascending-arity iteration order the Map carries on the
+   * server side.
+   */
+  jointOverrides?: readonly (readonly [string, VirtualJointOverrideShape])[];
+  /**
+   * Cached per-path variance results. Blocks read this for O(1) axis
+   * variance lookup instead of recomputing on each render.
+   */
+  varianceByPath?: VirtualVarianceByPathShape;
+  /**
+   * The default tuple — `{ axis: axis.default }` for every axis.
+   * Replaces the legacy "look at `permutations[0].input`" pattern.
+   */
+  defaultTuple?: Record<string, string>;
+  /**
+   * Pre-built `resolveAt(tuple)` accessor. The addon's preview
+   * decorator instantiates this once per iframe lifetime — the
+   * underlying virtual-module exports (cells, jointOverrides, axes,
+   * defaultTuple) are stable, so a single resolver instance with
+   * internal per-tuple memoization is correct and avoids the
+   * per-render rebuild dance the blocks side used to do. Hand-built
+   * snapshots (tests, MDX) can omit this; blocks fall back to
+   * building locally from `cells` / `permutationsResolved`.
+   */
+  resolveAt?: (tuple: Record<string, string>) => Record<string, VirtualTokenShape>;
 }
 /**
  * Context carrying the full {@link ProjectSnapshot}. `null` sentinel lets

package/dist/index.mjs

@@ -2,12 +2,12 @@ import './style.css';
 import Color from "colorjs.io";
 import { Fragment, createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { buildResolveAt } from "@unpunnyfuns/swatchbook-core/resolve-at";
 import { makeCSSVar } from "@terrazzo/token-tools/css";
 import { addons } from "storybook/preview-api";
-import { axes, css, cssVarPrefix, defaultPermutation, diagnostics, listing, permutations, permutationsResolved, presets } from "virtual:swatchbook/tokens";
+import { axes, cells, css, cssVarPrefix, defaultTuple, diagnostics, jointOverrides, listing, presets, varianceByPath } from "virtual:swatchbook/tokens";
 import { fuzzyFilter } from "@unpunnyfuns/swatchbook-core/fuzzy";
 import cx from "clsx";
-import { analyzeAxisVariance } from "@unpunnyfuns/swatchbook-core/variance";
 //#region src/format-color.ts
 const COLOR_FORMATS = [
 	"hex",
@@ -343,13 +343,14 @@ const TOKENS_UPDATED_EVENT = "swatchbook/tokens-updated";
 let snapshot = {
 	axes,
 	presets,
-	permutations,
-	defaultPermutation,
-	permutationsResolved,
 	diagnostics,
 	css,
 	cssVarPrefix,
 	listing: listing ?? {},
+	cells: cells ?? {},
+	jointOverrides: jointOverrides ?? [],
+	varianceByPath: varianceByPath ?? {},
+	defaultTuple: defaultTuple ?? {},
 	version: 0
 };
 const listeners = /* @__PURE__ */ new Set();
@@ -361,13 +362,14 @@ function ensureSubscribed() {
 		snapshot = {
 			axes: payload.axes ?? snapshot.axes,
 			presets: payload.presets ?? snapshot.presets,
-			permutations: payload.permutations ?? snapshot.permutations,
-			defaultPermutation: payload.defaultPermutation ?? snapshot.defaultPermutation,
-			permutationsResolved: payload.permutationsResolved ?? snapshot.permutationsResolved,
 			diagnostics: payload.diagnostics ?? snapshot.diagnostics,
 			css: payload.css ?? snapshot.css,
 			cssVarPrefix: payload.cssVarPrefix ?? snapshot.cssVarPrefix,
 			listing: payload.listing ?? snapshot.listing,
+			cells: payload.cells ?? snapshot.cells,
+			jointOverrides: payload.jointOverrides ?? snapshot.jointOverrides,
+			varianceByPath: payload.varianceByPath ?? snapshot.varianceByPath,
+			defaultTuple: payload.defaultTuple ?? snapshot.defaultTuple,
 			version: snapshot.version + 1
 		};
 		for (const cb of listeners) cb();
@@ -400,11 +402,31 @@ function ensureStylesheet(css) {
 	}
 	if (style.textContent !== css) style.textContent = css;
 }
-function defaultTuple(axes) {
+function defaultTuple$1(axes) {
 	const out = {};
 	for (const axis of axes) out[axis.name] = axis.default;
 	return out;
 }
+/**
+* Stable string key for a tuple — axes sorted by name + `:` separator.
+* Matches the key form `buildResolveAt` uses in core so both surfaces
+* agree on what counts as "the same tuple."
+*/
+function canonicalTupleKey(tuple) {
+	return Object.keys(tuple).toSorted().map((k) => `${k}:${tuple[k]}`).join("|");
+}
+/**
+* Build a `Map<canonicalKey, permutationName>` once per permutations
+* list so per-tuple lookups go through O(1) `Map.get` instead of an
+* `Array.prototype.find` scan per call. Bounded by the permutations
+* count regardless of how many lookups consumers do.
+*/
+function buildPermutationNameByTuple(permutations) {
+	const out = /* @__PURE__ */ new Map();
+	for (const perm of permutations) out.set(canonicalTupleKey(perm.input), perm.name);
+	return out;
+}
+const noPermutationName = () => void 0;
 function tuplesEqual(a, b) {
 	const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
 	for (const k of keys) if (a[k] !== b[k]) return false;
@@ -413,17 +435,38 @@ function tuplesEqual(a, b) {
 function nameForTuple(themesList, tuple) {
 	return themesList.find((t) => tuplesEqual(t.input, tuple))?.name;
 }
-function snapshotToData(snapshot) {
-	return {
-		activePermutation: snapshot.activePermutation,
-		activeAxes: { ...snapshot.activeAxes },
-		axes: snapshot.axes,
-		permutations: snapshot.permutations,
-		permutationsResolved: snapshot.permutationsResolved,
-		resolved: snapshot.permutationsResolved[snapshot.activePermutation] ?? {},
-		diagnostics: snapshot.diagnostics,
-		cssVarPrefix: snapshot.cssVarPrefix,
-		listing: snapshot.listing ?? {}
+/**
+* Reconstruct a `resolveAt` accessor from snapshot data. The wire
+* format ships `cells` as plain JSON and `jointOverrides` as an
+* array of `[key, entry]` pairs (Map doesn't survive JSON.stringify);
+* this hydrates them and wraps `buildResolveAt` from core. Stable
+* identity across calls with the same snapshot — `useMemo` keyed on
+* the snapshot fields produces a referentially stable function.
+*/
+function makeResolveAt(snapshot) {
+	const cells = snapshot.cells ?? {};
+	const jointOverrides = new Map(snapshot.jointOverrides ?? []);
+	const defaults = snapshot.defaultTuple ?? defaultTuple$1(snapshot.axes);
+	const resolver = buildResolveAt(snapshot.axes, cells, jointOverrides, defaults);
+	return (tuple) => resolver(tuple);
+}
+/**
+* Build the `resolveAt` accessor for a snapshot. Prefers the
+* snapshot's own `resolveAt` (the addon's preview decorator
+* pre-builds one at module load — see `previewResolveAt` in
+* `packages/addon/src/preview.tsx`), falling back to constructing
+* one from `cells` + `jointOverrides` when present (covers
+* hand-built test snapshots and the no-provider path) and finally to
+* the legacy per-permutation lookup for snapshots that only carry
+* `permutationsResolved` + `permutations` (MDX consumers that
+* pre-date the wire format change).
+*/
+function snapshotResolveAt(snapshot) {
+	if (snapshot.resolveAt) return snapshot.resolveAt;
+	if (Object.keys(snapshot.cells ?? {}).length > 0) return makeResolveAt(snapshot);
+	return (tuple) => {
+		const perms = snapshot.permutations ?? [];
+		return (snapshot.permutationsResolved ?? {})[nameForTuple(perms, tuple) ?? snapshot.activePermutation] ?? {};
 	};
 }
 /**
@@ -440,8 +483,39 @@ function snapshotToData(snapshot) {
 */
 function useProject() {
 	const snapshot = useOptionalSwatchbookData();
+	const axes = snapshot?.axes;
+	const cells = snapshot?.cells;
+	const jointOverrides = snapshot?.jointOverrides;
+	const dataDefaultTuple = snapshot?.defaultTuple;
+	const activePermutation = snapshot?.activePermutation;
+	const resolveAt = useMemo(() => {
+		if (!snapshot) return null;
+		return snapshotResolveAt(snapshot);
+	}, [
+		axes,
+		cells,
+		jointOverrides,
+		dataDefaultTuple,
+		activePermutation
+	]);
+	const permutationNameByTuple = useMemo(() => buildPermutationNameByTuple(snapshot?.permutations ?? []), [snapshot?.permutations]);
 	const fallback = useVirtualModuleFallback(snapshot === null);
-	return snapshot !== null ? snapshotToData(snapshot) : fallback;
+	if (snapshot !== null && resolveAt !== null) return snapshotToData(snapshot, resolveAt, permutationNameByTuple);
+	return fallback;
+}
+function snapshotToData(snapshot, resolveAt, permutationNameByTuple) {
+	return {
+		activePermutation: snapshot.activePermutation,
+		activeAxes: snapshot.activeAxes,
+		axes: snapshot.axes,
+		resolved: resolveAt(snapshot.activeAxes),
+		diagnostics: snapshot.diagnostics,
+		cssVarPrefix: snapshot.cssVarPrefix,
+		listing: snapshot.listing ?? {},
+		varianceByPath: snapshot.varianceByPath ?? {},
+		resolveAt,
+		permutationNameForTuple: (tuple) => permutationNameByTuple.get(canonicalTupleKey(tuple))
+	};
 }
 function useVirtualModuleFallback(enabled) {
 	const contextPermutation = useActivePermutation();
@@ -459,19 +533,32 @@ function useVirtualModuleFallback(enabled) {
 		if (!enabled) return;
 		ensureStylesheet(tokens.css);
 	}, [enabled, tokens.css]);
-	const activeAxes = Object.keys(contextAxes).length > 0 ? { ...contextAxes } : channelGlobals.axes ?? defaultTuple(tokens.axes);
-	const derivedName = nameForTuple(tokens.permutations, activeAxes);
-	const activePermutation = contextPermutation || derivedName || tokens.defaultPermutation || tokens.permutations[0]?.name || "";
+	const activeAxes = Object.keys(contextAxes).length > 0 ? { ...contextAxes } : channelGlobals.axes ?? defaultTuple$1(tokens.axes);
+	const activePermutation = contextPermutation || tokens.axes.map((a) => activeAxes[a.name] ?? a.default).join(" · ") || "";
+	const resolveAt = useMemo(() => makeResolveAt({
+		axes: tokens.axes,
+		cells: tokens.cells,
+		jointOverrides: tokens.jointOverrides,
+		defaultTuple: tokens.defaultTuple
+	}), [
+		tokens.axes,
+		tokens.cells,
+		tokens.jointOverrides,
+		tokens.defaultTuple
+	]);
+	const resolved = resolveAt(activeAxes);
+	const permutationNameForTuple = noPermutationName;
 	return {
 		activePermutation,
 		activeAxes,
 		axes: tokens.axes,
-		permutations: tokens.permutations,
-		permutationsResolved: tokens.permutationsResolved,
-		resolved: tokens.permutationsResolved[activePermutation] ?? {},
+		resolved,
 		diagnostics: tokens.diagnostics,
 		cssVarPrefix: tokens.cssVarPrefix,
-		listing: tokens.listing
+		listing: tokens.listing,
+		varianceByPath: tokens.varianceByPath,
+		resolveAt,
+		permutationNameForTuple
 	};
 }
 /**
@@ -2656,7 +2743,7 @@ function StrokeStyleSample({ filter, caption, sortBy = "path", sortDir = "asc" }
 //#region src/token-detail/internal.ts
 function useTokenDetailData(path) {
 	const project = useProject();
-	const { activePermutation, activeAxes, axes, permutations, permutationsResolved, resolved, cssVarPrefix } = project;
+	const { activePermutation, activeAxes, axes, resolved, cssVarPrefix, varianceByPath, resolveAt, permutationNameForTuple } = project;
 	const typedResolved = resolved;
 	return {
 		token: typedResolved[path],
@@ -2664,10 +2751,11 @@ function useTokenDetailData(path) {
 		activePermutation,
 		activeAxes,
 		axes,
-		permutations,
-		permutationsResolved,
 		resolved: typedResolved,
-		cssVarPrefix
+		cssVarPrefix,
+		varianceByPath,
+		resolveAt,
+		permutationNameForTuple
 	};
 }
 //#endregion
@@ -2792,27 +2880,25 @@ function treeHasTruncation(nodes) {
 //#endregion
 //#region src/token-detail/AxisVariance.tsx
 function AxisVariance({ path }) {
-	const { token, cssVar, axes, permutations, permutationsResolved, activeAxes, cssVarPrefix } = useTokenDetailData(path);
+	const { token, cssVar, axes, activeAxes, cssVarPrefix, varianceByPath, resolveAt, permutationNameForTuple } = useTokenDetailData(path);
 	const colorFormat = useColorFormat();
 	const tokenType = token?.$type;
 	const isColor = tokenType === "color";
 	const formatFn = (t) => valueFor(t, tokenType, colorFormat);
 	const variance = useMemo(() => {
-		const result = analyzeAxisVariance(path, axes, permutations, permutationsResolved);
+		const result = varianceByPath[path];
+		if (!result) return {
+			kind: "constant",
+			varyingAxes: []
+		};
 		return {
 			kind: result.kind === "constant" ? "constant" : result.kind === "single" ? "one-axis" : "multi-axis",
 			varyingAxes: result.varyingAxes
 		};
-	}, [
-		path,
-		axes,
-		permutations,
-		permutationsResolved
-	]);
-	if (permutations.length === 0) return /* @__PURE__ */ jsx(Fragment$1, {});
+	}, [path, varianceByPath]);
+	if (axes.length === 0) return /* @__PURE__ */ jsx(Fragment$1, {});
 	if (variance.kind === "constant") {
-		const anyPermutation = permutations[0];
-		const value = anyPermutation ? formatFn(permutationsResolved[anyPermutation.name]?.[path]) : "—";
+		const value = formatFn(resolveAt(activeAxes)[path]);
 		return /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx("div", {
 			className: "sb-token-detail__section-header",
 			children: "Values across axes"
@@ -2831,16 +2917,12 @@ function AxisVariance({ path }) {
 							"aria-hidden": true
 						}),
 						value,
-						/* @__PURE__ */ jsxs("span", {
+						/* @__PURE__ */ jsx("span", {
 							style: {
 								opacity: .6,
 								marginLeft: 8
 							},
-							children: [
-								"same across all ",
-								permutations.length,
-								" tuples"
-							]
+							children: "same across every axis"
 						})
 					]
 				})
@@ -2857,14 +2939,10 @@ function AxisVariance({ path }) {
 				...activeAxes,
 				[axisName]: ctx
 			};
-			const name = permutations.find((t) => {
-				const input = t.input;
-				return Object.keys(input).every((k) => input[k] === target[k]);
-			})?.name ?? "";
 			return {
 				ctx,
-				themeName: name,
-				value: name ? formatFn(permutationsResolved[name]?.[path]) : "—"
+				themeName: permutationNameForTuple(target) ?? "",
+				value: formatFn(resolveAt(target)[path])
 			};
 		});
 		return /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsxs("div", {
@@ -2930,12 +3008,13 @@ function AxisVariance({ path }) {
 					className: "sb-token-detail__theme-cell",
 					children: row
 				}), colAxis.contexts.map((col) => {
-					const name = tupleName(permutations, {
+					const target = {
 						...activeAxes,
 						[rowAxis.name]: row,
 						[colAxis.name]: col
-					});
-					const value = name ? formatFn(permutationsResolved[name]?.[path]) : "—";
+					};
+					const name = permutationNameForTuple(target);
+					const value = formatFn(resolveAt(target)[path]);
 					return /* @__PURE__ */ jsxs("td", {
 						className: "sb-token-detail__theme-cell",
 						"data-row": row,
@@ -2965,12 +3044,6 @@ function valueFor(token, $type, format) {
 	if (!token) return "—";
 	return formatTokenValue(token.$value, $type, format);
 }
-function tupleName(permutations, tuple) {
-	return permutations.find((t) => {
-		const input = t.input;
-		return Object.keys(input).every((k) => input[k] === tuple[k]);
-	})?.name;
-}
 //#endregion
 //#region src/token-detail/CompositeBreakdown.tsx
 function CompositeBreakdown({ path }) {