@unpunnyfuns/swatchbook-blocks 0.7.0 → 0.9.0

package/README.md

@@ -6,11 +6,13 @@ Published as `@unpunnyfuns/swatchbook-blocks`. Storybook MDX doc blocks for DTCG
 
 ## Install
 
+Most consumers pick this up transitively via `@unpunnyfuns/swatchbook-addon` — the addon re-exports the full blocks API, so `import { TokenTable } from '@unpunnyfuns/swatchbook-addon'` works and you don't need a second install line. Reach for this package directly when you want blocks *without* the Storybook addon (unit tests, a standalone React app wrapping tokens in a custom surface):
+
 ```sh
 npm install @unpunnyfuns/swatchbook-blocks
 ```
 
-Blocks read the token graph from a `SwatchbookProvider`. Inside Storybook, register `@unpunnyfuns/swatchbook-addon` alongside these blocks — its preview decorator mounts the provider automatically. Outside Storybook, wrap your tree in `SwatchbookProvider` and pass a `ProjectSnapshot` directly (see [Outside Storybook](#outside-storybook) below).
+Blocks read the token graph from a `SwatchbookProvider`. Inside Storybook, the addon's preview decorator mounts the provider automatically. Outside Storybook, wrap your tree in `SwatchbookProvider` and pass a `ProjectSnapshot` directly (see [Outside Storybook](#outside-storybook) below).
 
 ## Blocks
 
@@ -46,7 +48,7 @@ Shared: every block accepts a `caption` override and renders against the addon's
 The addon's preview decorator wraps every story in a `SwatchbookProvider` for you, so MDX and story authors drop blocks in directly:
 
 ```mdx
-import { TokenTable, ColorPalette, TokenDetail } from '@unpunnyfuns/swatchbook-blocks';
+import { TokenTable, ColorPalette, TokenDetail } from '@unpunnyfuns/swatchbook-addon';
 
 # Color tokens
 

package/dist/index.mjs

@@ -3,7 +3,7 @@ import Color from "colorjs.io";
 import { createContext, useCallback, useContext, useEffect, useMemo, useState, useSyncExternalStore } from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { addons } from "storybook/preview-api";
-import { axes, css, cssVarPrefix, defaultTheme, diagnostics, themes, themesResolved } from "virtual:swatchbook/tokens";
+import { axes, css, cssVarPrefix, defaultTheme, diagnostics, presets, themes, themesResolved } from "virtual:swatchbook/tokens";
 import cx from "clsx";
 //#region src/format-color.ts
 const COLOR_FORMATS = [
@@ -202,24 +202,24 @@ function EmptyState({ children }) {
 const AXES_GLOBAL_KEY = "swatchbookAxes";
 const THEME_GLOBAL_KEY = "swatchbookTheme";
 const COLOR_FORMAT_GLOBAL_KEY = "swatchbookColorFormat";
-let snapshot = {
+let snapshot$1 = {
 	axes: null,
 	theme: null,
 	format: null
 };
-const listeners = /* @__PURE__ */ new Set();
-let subscribed = false;
+const listeners$1 = /* @__PURE__ */ new Set();
+let subscribed$1 = false;
 function isColorFormat(value) {
 	return typeof value === "string" && COLOR_FORMATS.includes(value);
 }
-function ensureSubscribed() {
-	if (subscribed || typeof window === "undefined") return;
-	subscribed = true;
+function ensureSubscribed$1() {
+	if (subscribed$1 || typeof window === "undefined") return;
+	subscribed$1 = true;
 	const channel = addons.getChannel();
 	const onGlobals = (payload) => {
 		const globals = payload.globals;
 		if (!globals) return;
-		let next = snapshot;
+		let next = snapshot$1;
 		const nextAxes = globals[AXES_GLOBAL_KEY];
 		if (nextAxes && typeof nextAxes === "object") next = {
 			...next,
@@ -235,9 +235,9 @@ function ensureSubscribed() {
 			...next,
 			format: nextFormat
 		};
-		if (next !== snapshot) {
-			snapshot = next;
-			for (const cb of listeners) cb();
+		if (next !== snapshot$1) {
+			snapshot$1 = next;
+			for (const cb of listeners$1) cb();
 		}
 	};
 	/**
@@ -257,22 +257,22 @@ function ensureSubscribed() {
 * lands in our snapshot before any block renders. Running `useSyncExternalStore`'s
 * `subscribe` lazily on first hook call would miss the event in most cases.
 */
-ensureSubscribed();
-function subscribe(cb) {
-	ensureSubscribed();
-	listeners.add(cb);
+ensureSubscribed$1();
+function subscribe$1(cb) {
+	ensureSubscribed$1();
+	listeners$1.add(cb);
 	return () => {
-		listeners.delete(cb);
+		listeners$1.delete(cb);
 	};
 }
-function getSnapshot() {
-	return snapshot;
+function getSnapshot$1() {
+	return snapshot$1;
 }
 function getServerSnapshot() {
-	return snapshot;
+	return snapshot$1;
 }
 function useChannelGlobals() {
-	return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+	return useSyncExternalStore(subscribe$1, getSnapshot$1, getServerSnapshot);
 }
 //#endregion
 //#region src/contexts.ts
@@ -326,6 +326,70 @@ function useColorFormat() {
 	return contextValue ?? channelGlobals.format ?? "hex";
 }
 //#endregion
+//#region src/internal/channel-tokens.ts
+/**
+* Live token snapshot backed by the addon's preview dev-time HMR event.
+*
+* Blocks read the virtual module at module load; without a way to notice
+* changes, edits to the source token files would flow into the addon's
+* in-memory project but nowhere else — the React tree would keep
+* rendering the old values until a full preview reload. This module
+* subscribes to `TOKENS_UPDATED_EVENT` on Storybook's channel (which the
+* addon preview re-broadcasts from its own HMR listener) and exposes
+* the latest snapshot via `useSyncExternalStore`, so hooks that read
+* through this module re-render in place on each token save.
+*
+* Outside the preview iframe (the docs-site path, unit tests) the
+* channel never receives anything, and consumers keep seeing the
+* initial values baked into the virtual module at build time.
+*/
+const TOKENS_UPDATED_EVENT = "swatchbook/tokens-updated";
+let snapshot = {
+	axes,
+	presets,
+	themes,
+	defaultTheme,
+	themesResolved,
+	diagnostics,
+	css,
+	cssVarPrefix,
+	version: 0
+};
+const listeners = /* @__PURE__ */ new Set();
+let subscribed = false;
+function ensureSubscribed() {
+	if (subscribed || typeof window === "undefined") return;
+	subscribed = true;
+	addons.getChannel().on(TOKENS_UPDATED_EVENT, (payload) => {
+		snapshot = {
+			axes: payload.axes ?? snapshot.axes,
+			presets: payload.presets ?? snapshot.presets,
+			themes: payload.themes ?? snapshot.themes,
+			defaultTheme: payload.defaultTheme ?? snapshot.defaultTheme,
+			themesResolved: payload.themesResolved ?? snapshot.themesResolved,
+			diagnostics: payload.diagnostics ?? snapshot.diagnostics,
+			css: payload.css ?? snapshot.css,
+			cssVarPrefix: payload.cssVarPrefix ?? snapshot.cssVarPrefix,
+			version: snapshot.version + 1
+		};
+		for (const cb of listeners) cb();
+	});
+}
+ensureSubscribed();
+function subscribe(cb) {
+	ensureSubscribed();
+	listeners.add(cb);
+	return () => {
+		listeners.delete(cb);
+	};
+}
+function getSnapshot() {
+	return snapshot;
+}
+function useTokenSnapshot() {
+	return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+//#endregion
 //#region src/internal/use-project.ts
 const STYLE_ELEMENT_ID = "swatchbook-tokens";
 function ensureStylesheet(css) {
@@ -387,24 +451,32 @@ function useVirtualModuleFallback(enabled) {
 	const contextTheme = useActiveTheme();
 	const contextAxes = useActiveAxes();
 	const channelGlobals = useChannelGlobals();
+	/**
+	* Subscribe to the live token snapshot rather than reading the virtual
+	* module's module-level exports directly. Initial values come from
+	* `virtual:swatchbook/tokens` at load time; subsequent dev-time edits
+	* flow through the addon's HMR channel and update this snapshot in
+	* place so blocks re-render without a full preview reload.
+	*/
+	const tokens = useTokenSnapshot();
 	useEffect(() => {
 		if (!enabled) return;
-		ensureStylesheet(css);
-	}, [enabled]);
-	const activeAxes = Object.keys(contextAxes).length > 0 ? { ...contextAxes } : channelGlobals.axes ?? defaultTuple(axes);
-	const derivedName = nameForTuple(themes, activeAxes);
+		ensureStylesheet(tokens.css);
+	}, [enabled, tokens.css]);
+	const activeAxes = Object.keys(contextAxes).length > 0 ? { ...contextAxes } : channelGlobals.axes ?? defaultTuple(tokens.axes);
+	const derivedName = nameForTuple(tokens.themes, activeAxes);
 	const channelTheme = channelGlobals.theme;
-	const fallbackTupleName = channelTheme && tupleForName(themes, channelTheme) ? channelTheme : null;
-	const activeTheme = contextTheme || derivedName || fallbackTupleName || channelTheme || defaultTheme || themes[0]?.name || "";
+	const fallbackTupleName = channelTheme && tupleForName(tokens.themes, channelTheme) ? channelTheme : null;
+	const activeTheme = contextTheme || derivedName || fallbackTupleName || channelTheme || tokens.defaultTheme || tokens.themes[0]?.name || "";
 	return {
 		activeTheme,
 		activeAxes,
-		axes,
-		themes,
-		themesResolved,
-		resolved: themesResolved[activeTheme] ?? {},
-		diagnostics,
-		cssVarPrefix
+		axes: tokens.axes,
+		themes: tokens.themes,
+		themesResolved: tokens.themesResolved,
+		resolved: tokens.themesResolved[activeTheme] ?? {},
+		diagnostics: tokens.diagnostics,
+		cssVarPrefix: tokens.cssVarPrefix
 	};
 }
 function makeCssVar(path, prefix) {