@unpunnyfuns/swatchbook-blocks 0.55.0 → 0.57.0

package/README.md

@@ -19,8 +19,8 @@ Inside Storybook the addon mounts a `SwatchbookProvider` for you:
 ```mdx
 import { ColorPalette, TokenTable, TokenDetail } from '@unpunnyfuns/swatchbook-addon';
 
-<ColorPalette filter="color.*" />
-<TokenTable filter="color.*" type="color" />
+<ColorPalette filter="color.**" />
+<TokenTable filter="color.**" type="color" />
 <TokenDetail path="color.accent.bg" />
 ```
 

package/dist/index.d.mts

@@ -1,6 +1,7 @@
 import * as _$react from "react";
 import { ReactElement, ReactNode } from "react";
-import { Axis, AxisVarianceResult, Diagnostic, Permutation, Preset } from "@unpunnyfuns/swatchbook-core";
+import { Axis, AxisVarianceResult, Diagnostic, Preset } from "@unpunnyfuns/swatchbook-core";
+import { SlimListedToken } from "@unpunnyfuns/swatchbook-core/snapshot-for-wire";
 
 //#region src/format-color.d.ts
 /**
@@ -65,15 +66,27 @@ declare function formatColor(value: unknown, format: ColorFormat, fallback?: str
  * in `packages/addon/src/virtual.d.ts` describe the same payload.
  */
 type VirtualAxisShape = Axis;
-type VirtualPermutationShape = Permutation;
 type VirtualDiagnosticShape = Diagnostic;
 interface VirtualTokenShape {
-  $type?: string;
+  $type?: string | undefined;
   $value?: unknown;
-  $description?: string;
-  aliasOf?: string;
-  aliasChain?: readonly string[];
-  aliasedBy?: readonly string[];
+  $description?: string | undefined;
+  aliasOf?: string | undefined;
+  aliasChain?: readonly string[] | undefined;
+  aliasedBy?: readonly string[] | undefined;
+  /**
+   * Per-sub-field alias map for composite tokens whose value blends
+   * primitives with aliased fragments — Terrazzo populates this when
+   * one or more component fields of a composite ($type: 'border',
+   * 'shadow', 'typography', 'gradient', 'transition') resolve through
+   * an alias. The `CompositeBreakdown` block reads it to render the
+   * source path beside each component value. Typed as `unknown` because
+   * the shape varies per composite type (color carries a
+   * `{components: (string | undefined)[]}` sub-shape; typography/border
+   * carry a flat `Record<string, string | undefined>`); the block
+   * narrows it at the consumer.
+   */
+  partialAliasOf?: unknown;
 }
 /**
  * Subset of `@terrazzo/plugin-token-listing`'s `ListedToken` that the
@@ -81,28 +94,11 @@ interface VirtualTokenShape {
  * variable name and `previewValue` for the display-ready CSS string.
  * `source.loc` enables "jump to authoring source" affordances.
  *
- * Only the fields blocks consume are typed here; the plugin's full shape
- * lives in `@unpunnyfuns/swatchbook-core`.
+ * Aliases `SlimListedToken` from core's `/snapshot-for-wire` subpath —
+ * the single canonical wire shape; both the addon's plugin (server-side
+ * emit) and blocks (consumer-side read) reference the same definition.
  */
-interface VirtualTokenListingShape {
-  names: Record<string, string>;
-  previewValue?: string | number;
-  source?: {
-    resource: string;
-    loc?: {
-      start: {
-        line: number;
-        column: number;
-        offset: number;
-      };
-      end: {
-        line: number;
-        column: number;
-        offset: number;
-      };
-    };
-  };
-}
+type VirtualTokenListingShape = SlimListedToken;
 type VirtualPresetShape = Preset;
 /**
  * Wire shape of one `Project.jointOverrides` entry — same as core's
@@ -116,7 +112,7 @@ interface VirtualJointOverrideShape {
 /**
  * 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.
+ * token instead of re-running variance analysis on every render.
  */
 type VirtualVarianceByPathShape = Record<string, AxisVarianceResult>;
 /**
@@ -129,18 +125,7 @@ interface ProjectSnapshot {
   /** Axis names suppressed via `config.disabledAxes` — pinned to their defaults, hidden from the toolbar. */
   disabledAxes: readonly string[];
   presets: readonly VirtualPresetShape[];
-  /**
-   * @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;
+  activeTheme: string;
   activeAxes: Readonly<Record<string, string>>;
   cssVarPrefix: string;
   diagnostics: readonly VirtualDiagnosticShape[];
@@ -157,26 +142,23 @@ interface ProjectSnapshot {
    * 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.
+   * Non-default cells store only the tokens whose value differs from
+   * the default-cell baseline (delta cells).
    */
-  cells?: Record<string, Record<string, Record<string, VirtualTokenShape>>>;
+  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.
+   * server side. Empty array when no joint divergences exist.
    */
-  jointOverrides?: readonly (readonly [string, VirtualJointOverrideShape])[];
+  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>;
+  /** The default tuple — `{ axis: axis.default }` for every axis. */
+  defaultTuple: Record<string, string>;
   /**
    * Pre-built `resolveAt(tuple)` accessor. The addon's preview
    * decorator instantiates this once per iframe lifetime — the
@@ -205,11 +187,11 @@ declare function useOptionalSwatchbookData(): ProjectSnapshot | null;
  * `useGlobals` so the same hook works in autodocs / MDX renders where the
  * preview-hooks context isn't available.
  */
-declare const PermutationContext: _$react.Context<string>;
-declare function useActivePermutation(): string;
+declare const ThemeContext: _$react.Context<string>;
+declare function useActiveTheme(): string;
 /**
  * Active axis tuple for the current story/docs render — `Record<axisName,
- * contextName>`. Derived from the same input as {@link PermutationContext}; split
+ * 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.
  */
@@ -901,5 +883,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, PermutationContext, type ProjectSnapshot, ShadowPreview, type ShadowPreviewProps, ShadowSample, type ShadowSampleProps, StrokeStyleSample, type StrokeStyleSampleProps, SwatchbookContext, SwatchbookProvider, type SwatchbookProviderProps, 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 VirtualPermutationShape as VirtualPermutation, type VirtualPermutationShape, type VirtualPresetShape as VirtualPreset, type VirtualPresetShape, type VirtualTokenShape as VirtualToken, type VirtualTokenShape, type VirtualTokenListingShape, formatColor, useActiveAxes, useActivePermutation, useColorFormat, useOptionalSwatchbookData, useSwatchbookData };
+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 VirtualTokenListingShape, formatColor, useActiveAxes, useActiveTheme, useColorFormat, useOptionalSwatchbookData, useSwatchbookData };
 //# sourceMappingURL=index.d.mts.map