@unpunnyfuns/swatchbook-blocks 0.54.0 → 0.56.0

package/dist/index.d.mts

@@ -1,6 +1,7 @@
 import * as _$react from "react";
 import { ReactElement, ReactNode } from "react";
-import { Axis, 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,29 +94,27 @@ 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
+ * `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 variance analysis 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 +125,6 @@ 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>>;
   activePermutation: string;
   activeAxes: Readonly<Record<string, string>>;
   cssVarPrefix: string;
@@ -129,6 +138,38 @@ 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.
+   * 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>>>;
+  /**
+   * `Project.jointOverrides` flattened to entries for wire transport.
+   * Same ascending-arity iteration order the Map carries on the
+   * server side. Empty array when no joint divergences exist.
+   */
+  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. */
+  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
@@ -842,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, 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 VirtualPresetShape as VirtualPreset, type VirtualPresetShape, type VirtualTokenShape as VirtualToken, type VirtualTokenShape, type VirtualTokenListingShape, formatColor, useActiveAxes, useActivePermutation, useColorFormat, useOptionalSwatchbookData, useSwatchbookData };
 //# sourceMappingURL=index.d.mts.map