@unpunnyfuns/swatchbook-blocks 0.60.9 → 0.62.1

package/README.md

@@ -2,9 +2,9 @@
 
 React MDX doc blocks for [swatchbook](https://github.com/unpunnyfuns/swatchbook).
 
-Render your DTCG tokens in `.mdx` stories — swatch grids, type-specific previews, per-token inspectors. The blocks react to the toolbar's axis flips without any wiring in your story code.
+Render your DTCG tokens in `.mdx` stories: swatch grids, type-specific previews, per-token inspectors. The blocks react to the toolbar's axis flips without any wiring in your story code.
 
-Most consumers pick this up transitively via [`@unpunnyfuns/swatchbook-addon`](../addon); `import { TokenTable } from '@unpunnyfuns/swatchbook-addon'` works out of the box. Install this package directly when you want blocks *without* the Storybook addon — unit tests, a standalone React app wrapping tokens in a custom surface.
+Most consumers pick this up transitively via [`@unpunnyfuns/swatchbook-addon`](../addon); `import { TokenTable } from '@unpunnyfuns/swatchbook-addon'` works out of the box. Install this package directly when you want blocks *without* the Storybook addon, such as unit tests or a standalone React app wrapping tokens in a custom surface.
 
 ## Install
 
@@ -39,10 +39,10 @@ Block catalogue, props, and composition patterns live in the [blocks reference](
 
 ## Boundaries
 
-- ✅ Compose multiple blocks per page — each mounts independently.
+- ✅ Compose multiple blocks per page; each mounts independently.
 - ✅ Render outside Storybook with a hand-built or loaded `ProjectSnapshot`.
-- ❌ Don't import from `virtual:swatchbook/tokens` — it's the addon's internal wiring, not a public API. Use `SwatchbookProvider`.
-- ❌ Don't use `useGlobals` / `useArgs` from `storybook/preview-api` inside custom blocks — those hooks throw in docs context.
+- ❌ Don't import from `virtual:swatchbook/tokens`; it's the addon's internal wiring, not a public API. Use `SwatchbookProvider`.
+- ❌ Don't use `useGlobals` / `useArgs` from `storybook/preview-api` inside custom blocks; those hooks throw in docs context.
 
 ## Credits
 
@@ -50,4 +50,4 @@ Token parsing and resolver evaluation come from [Terrazzo](https://terrazzo.app/
 
 ## Documentation
 
-[unpunnyfuns.github.io/swatchbook](https://unpunnyfuns.github.io/swatchbook/) — concepts, guides, and full API reference.
+[unpunnyfuns.github.io/swatchbook](https://unpunnyfuns.github.io/swatchbook/): concepts, guides, and full API reference.

package/dist/index.d.mts

@@ -1,54 +1,11 @@
+import { COLOR_FORMATS, ColorFormat } from "@unpunnyfuns/swatchbook-core/color-formats";
+import { FormatColorResult, NormalizedColor, formatColor } from "@unpunnyfuns/swatchbook-core/format-color";
 import * as _$react from "react";
 import { ReactElement, ReactNode } from "react";
 import { TokenGraph } from "@unpunnyfuns/swatchbook-core/graph";
 import { Axis, Diagnostic, Preset } from "@unpunnyfuns/swatchbook-core";
 import { SlimListedToken } from "@unpunnyfuns/swatchbook-core/snapshot-for-wire";
 
-//#region src/format-color.d.ts
-/**
- * Color display formats understood by {@link formatColor}.
- *
- * - `hex` — sRGB hex (`#rrggbb` or `#rrggbbaa`). Out-of-gamut or wide-gamut
- *   colors fall back to `rgb()` and surface `outOfGamut: true` so callers
- *   can render a ⚠ glyph.
- * - `rgb` / `hsl` — modern CSS Color 4 space-separated syntax, converted
- *   from the source colorspace. Out-of-gamut values are still stringified
- *   (the browser will clip when actually rendering) and flagged.
- * - `oklch` — perceptual wide-gamut form. Never marks out-of-gamut because
- *   every color expressible in sRGB/P3 fits in oklch.
- * - `raw` — compact JSON of the normalized Terrazzo shape. For DTCG
- *   authors who want to see what the parser actually stored.
- */
-type ColorFormat = 'hex' | 'rgb' | 'hsl' | 'oklch' | 'raw';
-declare const COLOR_FORMATS: readonly ColorFormat[];
-/**
- * Terrazzo's `ColorValueNormalized`, copied inline to avoid a hard dep on
- * `@terrazzo/token-tools` from blocks. Matches the shape documented at
- * https://terrazzo.app/docs/cli/reference/token-tools/ColorValueNormalized.
- *
- * Some token payloads we see in the wild use the legacy DTCG-ish `channels`
- * field in place of `components`; we accept either.
- */
-interface NormalizedColor {
-  colorSpace: string;
-  components?: readonly (number | null)[];
-  channels?: readonly (number | null)[];
-  alpha?: number;
-  hex?: string;
-}
-interface FormatColorResult {
-  /** Display string — e.g. `rgb(59 132 246)`, `#3b82f6`. */
-  value: string;
-  /** True when the requested format can't losslessly represent the color. */
-  outOfGamut: boolean;
-}
-/**
- * Convert Terrazzo's normalized color payload into a display string in the
- * requested format. Pure function — never throws; returns `{ value: '—' }`
- * for unrecognized input so calling blocks don't need try/catch.
- */
-declare function formatColor(value: unknown, format: ColorFormat, fallback?: string): FormatColorResult;
-//#endregion
 //#region src/contexts.d.ts
 /**
  * Typed shape of the addon's `virtual:swatchbook/tokens` module.
@@ -114,9 +71,6 @@ type VirtualTokenGraph = TokenGraph;
  */
 interface ProjectSnapshot {
   axes: readonly VirtualAxisShape[];
-  /** Axis names suppressed via `config.disabledAxes` — pinned to their defaults, hidden from the toolbar. */
-  disabledAxes: readonly string[];
-  presets: readonly VirtualPresetShape[];
   activeTheme: string;
   activeAxes: Readonly<Record<string, string>>;
   cssVarPrefix: string;
@@ -169,7 +123,7 @@ declare function useActiveTheme(): string;
  * Active axis tuple for the current story/docs render — `Record<axisName,
  * contextName>`. Derived from the same input as {@link ThemeContext}; split
  * out so consumers needing per-axis info (toolbar, panel, tuple-aware
- * blocks) don't have to reparse the composed permutation ID.
+ * blocks) don't have to reparse the composed theme name.
  */
 declare const AxesContext: _$react.Context<Readonly<Record<string, string>>>;
 declare function useActiveAxes(): Readonly<Record<string, string>>;
@@ -314,7 +268,7 @@ interface ColorTableProps {
    *
    * Single-member groups render as plain rows (no pill selector). Empty
    * map (default) disables grouping entirely; each token renders as its
-   * own row, identical to the pre-grouping behavior.
+   * own row.
    */
   variants?: Record<string, string>;
 }
@@ -348,7 +302,7 @@ declare function Diagnostics({
 }?: DiagnosticsProps): ReactElement;
 //#endregion
 //#region src/dimension-scale/DimensionBar.d.ts
-type DimensionKind = 'length' | 'radius' | 'size';
+type DimensionVisual = 'length' | 'radius' | 'size';
 interface DimensionBarProps {
   /** Full dot-path of the dimension token to preview. */
   path: string;
@@ -358,11 +312,11 @@ interface DimensionBarProps {
    * - `'radius'`: 56×56 square with the token applied as `border-radius`.
    * - `'size'`: a square sized to the token's dimension.
    */
-  kind?: DimensionKind;
+  visual?: DimensionVisual;
 }
 declare function DimensionBar({
   path,
-  kind
+  visual
 }: DimensionBarProps): ReactElement;
 //#endregion
 //#region src/DimensionScale.d.ts
@@ -378,7 +332,7 @@ interface DimensionScaleProps {
    * - `'radius'`: 56×56 square with the token applied as `border-radius`.
    * - `'size'`: a square sized to the token's dimension.
    */
-  kind?: DimensionKind;
+  visual?: DimensionVisual;
   /** Override the caption. */
   caption?: string;
   /**
@@ -394,14 +348,14 @@ interface DimensionScaleProps {
 }
 declare function DimensionScale({
   filter,
-  kind,
+  visual,
   caption,
   sortBy,
   sortDir
 }: DimensionScaleProps): ReactElement;
 //#endregion
-//#region src/FontFamilySample.d.ts
-interface FontFamilySampleProps {
+//#region src/FontFamilyPreview.d.ts
+interface FontFamilyPreviewProps {
   /**
    * Token-path filter. Defaults to every `fontFamily` token. Use e.g.
    * `"font.family.*"` to scope to the ref layer.
@@ -420,13 +374,13 @@ interface FontFamilySampleProps {
   /** `'asc'` (default) or `'desc'`. */
   sortDir?: SortDir;
 }
-declare function FontFamilySample({
+declare function FontFamilyPreview({
   filter,
   sample,
   caption,
   sortBy,
   sortDir
-}: FontFamilySampleProps): ReactElement;
+}: FontFamilyPreviewProps): ReactElement;
 //#endregion
 //#region src/FontWeightScale.d.ts
 interface FontWeightScaleProps {
@@ -569,6 +523,25 @@ declare function OpacityScale({
   sortDir
 }: OpacityScaleProps): ReactElement;
 //#endregion
+//#region src/internal/channel-globals.d.ts
+/**
+ * Shared subscription to Storybook's globals channel, lifted out of React
+ * component state so the values survive docs-mode remounts.
+ *
+ * On MDX docs pages, Storybook force-rerenders the docs container on every
+ * `updateGlobals` (see `preview/runtime.js` → `onUpdateGlobals`), which
+ * unmounts and remounts any embedded blocks. A `useState(null)` initializer
+ * inside the block would reset to null on each remount — the symptom is a
+ * one-frame flicker to the correct value, then revert to the defaults.
+ * Module-level state persists; React reads it through `useSyncExternalStore`
+ * and stays concurrent-safe.
+ */
+interface ChannelGlobals {
+  axes: Record<string, string> | null;
+  format: ColorFormat | null;
+}
+declare function useChannelGlobals(): ChannelGlobals;
+//#endregion
 //#region src/provider.d.ts
 interface SwatchbookProviderProps {
   value: ProjectSnapshot;
@@ -594,6 +567,49 @@ declare function SwatchbookProvider({
  */
 declare function useSwatchbookData(): ProjectSnapshot;
 //#endregion
+//#region src/internal/channel-tokens.d.ts
+/**
+ * Live token snapshot backed by the addon's preview dev-time HMR event.
+ *
+ * The initial snapshot is *injected* by the addon preview via
+ * {@link registerTokenSource} rather than imported from the addon's
+ * `virtual:swatchbook/tokens` build artifact — so blocks carries no
+ * dependency on that module and imports cleanly standalone (outside
+ * Storybook, in unit tests, in the docs site). Until something registers
+ * a source, blocks render from empty defaults.
+ *
+ * For dev-time updates 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 re-render in place on each token save.
+ */
+declare const TOKENS_UPDATED_EVENT = "swatchbook/tokens-updated";
+interface TokenSnapshot {
+  readonly axes: readonly VirtualAxisShape[];
+  readonly presets: readonly {
+    name: string;
+    axes: Partial<Record<string, string>>;
+    description?: string;
+  }[];
+  readonly diagnostics: readonly VirtualDiagnosticShape[];
+  readonly css: string;
+  readonly cssVarPrefix: string;
+  readonly listing: Readonly<Record<string, VirtualTokenListingShape>>;
+  readonly tokenGraph: VirtualTokenGraph;
+  readonly defaultTuple: Record<string, string>;
+  /** Monotonic counter, bumped on each update. Useful as a React key. */
+  readonly version: number;
+}
+/**
+ * Seed the initial token snapshot. The addon preview calls this once at
+ * init with the build-time `virtual:swatchbook/tokens` data. Keeping the
+ * virtual-module read on the addon side (the package that owns it) lets
+ * blocks import cleanly without it. No-op fields fall back to the current
+ * snapshot, so a partial source is safe.
+ */
+declare function registerTokenSource(source: Partial<TokenSnapshot>): void;
+declare function useTokenSnapshot(): TokenSnapshot;
+//#endregion
 //#region src/ShadowPreview.d.ts
 interface ShadowPreviewProps {
   /**
@@ -628,8 +644,8 @@ declare function ShadowSample({
   path
 }: ShadowSampleProps): ReactElement;
 //#endregion
-//#region src/StrokeStyleSample.d.ts
-interface StrokeStyleSampleProps {
+//#region src/StrokeStylePreview.d.ts
+interface StrokeStylePreviewProps {
   /**
    * Token-path filter. Defaults to every `strokeStyle` token. Use e.g.
    * `"stroke.style.*"` to scope to the ref layer.
@@ -646,12 +662,12 @@ interface StrokeStyleSampleProps {
   /** `'asc'` (default) or `'desc'`. */
   sortDir?: SortDir;
 }
-declare function StrokeStyleSample({
+declare function StrokeStylePreview({
   filter,
   caption,
   sortBy,
   sortDir
-}: StrokeStyleSampleProps): ReactElement;
+}: StrokeStylePreviewProps): ReactElement;
 //#endregion
 //#region src/TokenDetail.d.ts
 interface TokenDetailProps {
@@ -859,5 +875,5 @@ declare function TypographyScale({
   sortDir
 }: TypographyScaleProps): ReactElement;
 //#endregion
-export { AliasChain, type AliasChainProps, AliasedBy, type AliasedByProps, AxesContext, AxisVariance, type AxisVarianceProps, BorderPreview, type BorderPreviewProps, BorderSample, type BorderSampleProps, COLOR_FORMATS, type ColorFormat, ColorFormatContext, ColorPalette, type ColorPaletteProps, ColorTable, type ColorTableProps, CompositeBreakdown, type CompositeBreakdownProps, CompositePreview, type CompositePreviewProps, ConsumerOutput, type ConsumerOutputProps, Diagnostics, type DiagnosticsProps, DimensionBar, type DimensionBarProps, type DimensionKind, DimensionScale, type DimensionScaleProps, FontFamilySample, type FontFamilySampleProps, FontWeightScale, type FontWeightScaleProps, type FormatColorResult, GradientPalette, type GradientPaletteProps, MotionPreview, type MotionPreviewProps, MotionSample, type MotionSampleProps, type MotionSpeed, type NormalizedColor, OpacityScale, type OpacityScaleProps, type ProjectSnapshot, ShadowPreview, type ShadowPreviewProps, ShadowSample, type ShadowSampleProps, StrokeStyleSample, type StrokeStyleSampleProps, SwatchbookContext, SwatchbookProvider, type SwatchbookProviderProps, ThemeContext, TokenDetail, type TokenDetailProps, TokenHeader, type TokenHeaderProps, TokenNavigator, type TokenNavigatorProps, TokenTable, type TokenTableProps, TokenUsageSnippet, type TokenUsageSnippetProps, TypographyScale, type TypographyScaleProps, type VirtualAxisShape as VirtualAxis, type VirtualAxisShape, type VirtualDiagnosticShape as VirtualDiagnostic, type VirtualDiagnosticShape, type VirtualPresetShape as VirtualPreset, type VirtualPresetShape, type VirtualTokenShape as VirtualToken, type VirtualTokenShape, type VirtualTokenGraph, type VirtualTokenListingShape, formatColor, useActiveAxes, useActiveTheme, useColorFormat, useOptionalSwatchbookData, useSwatchbookData };
+export { AliasChain, type AliasChainProps, AliasedBy, type AliasedByProps, AxesContext, AxisVariance, type AxisVarianceProps, BorderPreview, type BorderPreviewProps, BorderSample, type BorderSampleProps, COLOR_FORMATS, type ChannelGlobals, type ColorFormat, ColorFormatContext, ColorPalette, type ColorPaletteProps, ColorTable, type ColorTableProps, CompositeBreakdown, type CompositeBreakdownProps, CompositePreview, type CompositePreviewProps, ConsumerOutput, type ConsumerOutputProps, Diagnostics, type DiagnosticsProps, DimensionBar, type DimensionBarProps, DimensionScale, type DimensionScaleProps, type DimensionVisual, FontFamilyPreview, type FontFamilyPreviewProps, FontWeightScale, type FontWeightScaleProps, type FormatColorResult, GradientPalette, type GradientPaletteProps, MotionPreview, type MotionPreviewProps, MotionSample, type MotionSampleProps, type MotionSpeed, type NormalizedColor, OpacityScale, type OpacityScaleProps, type ProjectSnapshot, ShadowPreview, type ShadowPreviewProps, ShadowSample, type ShadowSampleProps, StrokeStylePreview, type StrokeStylePreviewProps, SwatchbookContext, SwatchbookProvider, type SwatchbookProviderProps, TOKENS_UPDATED_EVENT, ThemeContext, TokenDetail, type TokenDetailProps, TokenHeader, type TokenHeaderProps, TokenNavigator, type TokenNavigatorProps, type TokenSnapshot, TokenTable, type TokenTableProps, TokenUsageSnippet, type TokenUsageSnippetProps, TypographyScale, type TypographyScaleProps, type VirtualAxisShape as VirtualAxis, type VirtualAxisShape, type VirtualDiagnosticShape as VirtualDiagnostic, type VirtualDiagnosticShape, type VirtualPresetShape as VirtualPreset, type VirtualPresetShape, type VirtualTokenShape as VirtualToken, type VirtualTokenShape, type VirtualTokenGraph, type VirtualTokenListingShape, formatColor, registerTokenSource, useActiveAxes, useActiveTheme, useChannelGlobals, useColorFormat, useOptionalSwatchbookData, useSwatchbookData, useTokenSnapshot };
 //# sourceMappingURL=index.d.mts.map