@unpunnyfuns/swatchbook-blocks 1.2.0 → 2.0.0

package/dist/registry-Dm25Go94.d.mts

@@ -0,0 +1,244 @@
+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 } 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";
+import { RealisedToken, TokenType } from "@unpunnyfuns/swatchbook-core/token-value-types";
+
+//#region src/contexts.d.ts
+/**
+ * Typed shape of the addon's `virtual:swatchbook/tokens` module.
+ *
+ * The axis / permutation / diagnostic / preset entries are deliberate
+ * type-aliases of core's authoritative shapes — the virtual module
+ * publishes those shapes verbatim, so single-sourcing the types prevents
+ * silent drift the moment core grows a field the plugin doesn't
+ * serialise.
+ *
+ * Token / listing shapes stay as narrowed interfaces because blocks
+ * only read a subset of Terrazzo's full token / listing structure; the
+ * narrower shape documents what's actually relied on.
+ *
+ * The ambient `declare module 'virtual:swatchbook/tokens'` declarations
+ * in `packages/addon/src/virtual.d.ts` describe the same payload.
+ */
+type VirtualAxisShape = Axis;
+type VirtualDiagnosticShape = Diagnostic;
+interface VirtualTokenShape {
+  $type?: string | undefined;
+  $value?: unknown;
+  $description?: string | undefined;
+  /**
+   * DTCG `$deprecated` — `true` or a message string. Mirrors core's
+   * `SwatchbookToken.$deprecated`; reaches blocks via the resolved token
+   * map reconstructed from the wire `tokenGraph`.
+   */
+  $deprecated?: string | boolean | 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
+ * snapshot carries. Blocks read `names.css` for the authoritative CSS
+ * variable name and `previewValue` for the display-ready CSS string.
+ * `source.loc` enables "jump to authoring source" affordances.
+ *
+ * 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.
+ */
+type VirtualTokenListing = SlimListedToken;
+type VirtualPresetShape = Preset;
+/**
+ * Wire shape of the token graph — aliased from core's authoritative
+ * `TokenGraph` so both the virtual module declaration and the React
+ * context stay aligned with the same definition.
+ */
+type VirtualTokenGraph = TokenGraph;
+/**
+ * Full project data read by blocks. Populated by the addon's preview
+ * decorator (from the virtual module) or constructed by hand in
+ * non-Storybook consumers.
+ */
+interface ProjectSnapshot {
+  axes: readonly VirtualAxisShape[];
+  activeTheme: string;
+  activeAxes: Readonly<Record<string, string>>;
+  cssVarPrefix: string;
+  /**
+   * Project-wide baseline for the row-indicator strip from
+   * `config.indicators`. Sits between the hard-coded indicator defaults
+   * and a block's `indicators` prop. Optional — hand-built snapshots
+   * (tests, MDX) omit it and blocks fall back to the bare defaults.
+   */
+  indicators?: Readonly<Record<string, boolean>>;
+  diagnostics: readonly VirtualDiagnosticShape[];
+  /**
+   * Raw stylesheet text for the active theme. Optional — nothing on the
+   * `SwatchbookProvider` read path consumes it (`useProject()` never reads
+   * `snapshot.css`); the addon populates it incidentally when constructing
+   * its snapshot but injects CSS through its own independent mechanism.
+   */
+  css?: string;
+  /**
+   * Path-indexed Token Listing data produced by
+   * `@terrazzo/plugin-token-listing`. Blocks prefer reading authoritative
+   * CSS var names and preview values from here; empty for non-resolver
+   * projects. Treat as enrichment — fall back gracefully when a path is
+   * absent.
+   */
+  listing?: Readonly<Record<string, VirtualTokenListing>>;
+  /**
+   * Pre-built token graph for the project. JSON-serializable; nodes
+   * carry per-axis writes plus alias edges. The blocks hook backs
+   * `resolveAt` and variance from this graph.
+   */
+  tokenGraph?: VirtualTokenGraph;
+  /** The default tuple — `{ axis: axis.default }` for every axis. */
+  defaultTuple: Record<string, string>;
+  /**
+   * Starting color format for blocks that display color values:
+   * `config.defaultColorFormat` from core, passed through the wire
+   * snapshot. `useColorFormat()` falls back to this when neither a
+   * block's own `colorFormat` prop nor a `ColorFormatContext` override is
+   * active. Optional: hand-built snapshots (tests, MDX) that omit it fall
+   * through to the bare `'hex'` default.
+   */
+  defaultColorFormat?: ColorFormat;
+  /**
+   * Pre-built `resolveAt(tuple)` accessor. The addon's preview decorator
+   * instantiates this once per iframe lifetime. When present, use-project
+   * prefers it over building its own from `tokenGraph`, so it MUST preserve
+   * alias provenance — back it with `resolveAllWithProvenanceAt`, not the raw
+   * leaf `resolveAllAt`, or axis-varying aliases silently lose their chain /
+   * reverse refs / description at non-default tuples. Hand-built snapshots
+   * (tests, MDX) can omit this; blocks then fall back to a provenance-aware
+   * graph-backed resolver built from `tokenGraph`.
+   */
+  resolveAt?: (tuple: Record<string, string>) => Record<string, VirtualTokenShape>;
+}
+/**
+ * Context carrying the full {@link ProjectSnapshot}. `null` sentinel lets
+ * `useSwatchbookData()` tell "provider present" from "fall back to the
+ * virtual module".
+ */
+declare const SwatchbookContext: _$react.Context<ProjectSnapshot | null>;
+declare function useOptionalSwatchbookData(): ProjectSnapshot | null;
+/**
+ * Active swatchbook theme for the current story/docs render. Populated by
+ * the addon's preview decorator and consumed by `useToken` + any future
+ * consumer hooks.
+ *
+ * This runs through plain React context rather than Storybook's
+ * `useGlobals` so the same hook works in autodocs / MDX renders where the
+ * preview-hooks context isn't available.
+ */
+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 ThemeContext}; split
+ * out so consumers needing per-axis info (toolbar, panel, tuple-aware
+ * 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>>;
+/**
+ * Active color-display format for the current story/docs render, consumed
+ * by blocks that render color-token values. Emitted CSS is unaffected.
+ *
+ * Sits in the middle of the precedence chain a block resolves via
+ * `colorFormat ?? useColorFormat()`: a block's own `colorFormat` prop wins
+ * over this context, which wins over the active source's
+ * `defaultColorFormat` (from `Config.defaultColorFormat`). "Active
+ * source" is whichever one is actually feeding the render:
+ * `SwatchbookProvider`'s snapshot when a story decorator mounted one,
+ * otherwise the ambient `ProjectSource` (`#/host.ts`) that MDX-embedded
+ * blocks (no `<Story/>`, no provider) read through `useProject()`'s
+ * fallback path.
+ *
+ * Runs through plain React context rather than Storybook's `useGlobals` so
+ * per-story seeded globals flow through on first render and the same hook
+ * is safe to call from MDX doc blocks (where the preview-hooks context
+ * isn't available).
+ */
+declare const ColorFormatContext: _$react.Context<ColorFormat | null>;
+/**
+ * Resolves the color-display format from the context/snapshot/source
+ * chain: `ColorFormatContext` → provider snapshot's `defaultColorFormat`
+ * → ambient source's `defaultColorFormat` → `'hex'`. Composing blocks
+ * read `colorFormat ?? useColorFormat()` to give their own `colorFormat`
+ * prop top precedence over this chain.
+ */
+declare function useColorFormat(): ColorFormat;
+//#endregion
+//#region src/presenters/types.d.ts
+/**
+ * Uniform props every presenter receives, built-in or third-party. A composer
+ * renders `registry[token.$type]` with this shape and never special-cases a
+ * type. The presenter owns the `$value`→CSS mapping; that is what an override
+ * customizes.
+ */
+interface PresenterProps<T extends TokenType = TokenType> {
+  /** Token dot-path. Label/provenance; the presenter shows the leaf. */
+  path: string;
+  /** Fully-realised token: concrete `$value`, no alias/graph resolution. */
+  token: RealisedToken<T>;
+  /** R3: present → use for the visual; absent → render from `$value`. */
+  cssVar?: string | undefined;
+  /** Relevant to color/gradient; other presenters ignore it (uniform props). */
+  colorFormat: ColorFormat;
+  /**
+   * Optional block-level display hints (RJSF `ui:options`-style). A query
+   * block passes its own config (e.g. `{ visual }`, `{ speed }`, `{ sample }`)
+   * here; built-in presenters read the keys they understand, custom presenters
+   * ignore them. Not part of the token; purely presentation.
+   */
+  options?: Record<string, unknown> | undefined;
+}
+/** A presenter component for tokens of `$type` T. */
+type PresenterComponent<T extends TokenType = TokenType> = (props: PresenterProps<T>) => ReactElement;
+/** `$type` → presenter. Partial: a composer falls back to defaults for gaps. */
+type PresenterRegistry = Partial<Record<TokenType, PresenterComponent>>;
+//#endregion
+//#region src/presenters/registry.d.ts
+/**
+ * Built-in presenters, keyed by DTCG `$type`. Phase C registers each entry as
+ * its presenter lands. A consumer's `presenters` override merges over this.
+ */
+declare const DEFAULT_PRESENTERS: PresenterRegistry;
+/** Overrides win per `$type`; unlisted types keep the built-in. */
+declare function mergePresenters(overrides?: PresenterRegistry): PresenterRegistry;
+/** The active merged registry for the subtree. */
+declare const PresenterContext: _$react.Context<Partial<Record<TokenType, PresenterComponent<TokenType>>>>;
+/**
+ * Set the ambient presenter registry consulted by blocks that render with
+ * no `SwatchbookProvider` or `PresenterContext.Provider` above them (MDX
+ * doc blocks, autodocs). A host registers this once at preview-init; it is
+ * NOT reactive, so register before first render. Passing no argument (or
+ * `undefined`) resets to the built-ins. An explicit provider/context
+ * override still wins for its subtree; this only fills the provider-less
+ * gap.
+ */
+declare function registerPresenters(overrides?: PresenterRegistry): void;
+/** The presenter for `type`, or `undefined` if none is registered. */
+declare function usePresenter(type: TokenType): PresenterComponent | undefined;
+//#endregion
+export { useOptionalSwatchbookData as C, NormalizedColor as D, FormatColorResult as E, formatColor as O, useColorFormat as S, ColorFormat as T, VirtualTokenGraph as _, usePresenter as a, useActiveAxes as b, PresenterRegistry as c, ProjectSnapshot as d, SwatchbookContext as f, VirtualPresetShape as g, VirtualDiagnosticShape as h, registerPresenters as i, AxesContext as l, VirtualAxisShape as m, PresenterContext as n, PresenterComponent as o, ThemeContext as p, mergePresenters as r, PresenterProps as s, DEFAULT_PRESENTERS as t, ColorFormatContext as u, VirtualTokenListing as v, COLOR_FORMATS as w, useActiveTheme as x, VirtualTokenShape as y };
+//# sourceMappingURL=registry-Dm25Go94.d.mts.map