@unpunnyfuns/swatchbook-blocks 1.0.0-alpha.0 → 1.0.0-alpha.2

package/dist/index.d.mts

@@ -62,7 +62,7 @@ interface VirtualTokenShape {
  * the single canonical wire shape; both the addon's plugin (server-side
  * emit) and blocks (consumer-side read) reference the same definition.
  */
-type VirtualTokenListingShape = SlimListedToken;
+type VirtualTokenListing = SlimListedToken;
 type VirtualPresetShape = Preset;
 /**
  * Wire shape of the token graph — aliased from core's authoritative
@@ -88,7 +88,13 @@ interface ProjectSnapshot {
    */
   indicators?: Readonly<Record<string, boolean>>;
   diagnostics: readonly VirtualDiagnosticShape[];
-  css: string;
+  /**
+   * 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
@@ -96,7 +102,7 @@ interface ProjectSnapshot {
    * projects. Treat as enrichment — fall back gracefully when a path is
    * absent.
    */
-  listing?: Readonly<Record<string, VirtualTokenListingShape>>;
+  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
@@ -117,12 +123,6 @@ interface ProjectSnapshot {
    */
   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
@@ -341,9 +341,11 @@ declare function Diagnostics({
   caption
 }?: DiagnosticsProps): ReactElement;
 //#endregion
-//#region src/dimension-scale/DimensionBar.d.ts
+//#region src/dimension-scale/DimensionSample.d.ts
+/** The visual treatment for a dimension sample: a length bar, a radius square, or a sized square. */
 type DimensionVisual = 'length' | 'radius' | 'size';
-interface DimensionBarProps {
+/** Props for the connected {@link DimensionSample} block. */
+interface DimensionSampleProps {
   /** Full dot-path of the dimension token to preview. */
   path: string;
   /**
@@ -354,10 +356,11 @@ interface DimensionBarProps {
    */
   visual?: DimensionVisual;
 }
-declare function DimensionBar({
+/** Connected block: resolves `path` against the active project and renders its dimension sample. */
+declare function DimensionSample({
   path,
   visual
-}: DimensionBarProps): ReactElement;
+}: DimensionSampleProps): ReactElement;
 //#endregion
 //#region src/DimensionScale.d.ts
 interface DimensionScaleProps {
@@ -497,6 +500,13 @@ declare function MotionSample({
 }: MotionSampleProps): ReactElement;
 //#endregion
 //#region src/MotionPreview.d.ts
+/**
+ * Unlike the other filter/caption/sortBy/sortDir blocks in this family,
+ * `MotionPreview` has no `sortBy`/`sortDir` — rows are always ordered by
+ * kind (`transition` / `duration` / `cubicBezier`) then path. There's no
+ * single numeric axis across the three kinds that a sort would meaningfully
+ * order by.
+ */
 interface MotionPreviewProps {
   /**
    * Token-path filter. Defaults to transition + duration + cubicBezier
@@ -580,6 +590,12 @@ declare function useChannelGlobals(): ChannelGlobals;
 //#endregion
 //#region src/internal/channel.d.ts
 /**
+ * Host adapter API — a distinct tier from the components/hooks/
+ * `SwatchbookProvider` surface that MDX/story authors use. This is how a
+ * host (Storybook's addon, or an alternative embedding) injects live data
+ * into blocks without blocks depending on that host. Most consumers never
+ * touch this; it exists for whoever builds the next integration.
+ *
  * Minimal event-source contract blocks need from their host. Storybook's
  * preview Channel satisfies it structurally; a plain emitter or a test double
  * does too. Blocks never import `storybook/preview-api` — the addon, which
@@ -591,13 +607,19 @@ interface BlockChannel {
   on<T>(event: string, listener: (payload: T) => void): void;
 }
 /**
- * Inject the host channel. Called once by the addon preview at init. Runs any
- * subscribers that registered before the channel existed, then clears the
- * queue. Idempotent for consumers: each subscriber guards its own attach, so a
- * re-register (HMR) does not double-wire.
+ * Host adapter API. The single most load-bearing function in the host
+ * contract — the addon calls it once at preview init.
+ *
+ * Inject the host channel. Runs any subscribers that queued before the
+ * channel existed, then clears the queue. The host contract does NOT dedupe:
+ * on HMR a subscriber's module re-runs {@link onChannel}, which re-attaches
+ * immediately once the channel is set, so each subscriber MUST guard its own
+ * attach to stay single-wired.
  */
 declare function registerChannel(next: BlockChannel): void;
 /**
+ * Host adapter API — see {@link registerChannel}.
+ *
  * Attach a subscriber to the host channel now if one is registered, else queue
  * it to run the moment {@link registerChannel} fires. Blocks call this at
  * module load; the queue absorbs the gap until the addon injects the channel.
@@ -631,6 +653,12 @@ declare function useSwatchbookData(): ProjectSnapshot;
 //#endregion
 //#region src/internal/channel-tokens.d.ts
 /**
+ * Host adapter API — same integration tier as {@link BlockChannel} /
+ * {@link registerChannel} / {@link onChannel}, distinct from the
+ * components/hooks/`SwatchbookProvider` surface MDX/story authors use.
+ * Most consumers never touch this; it exists for whoever builds the next
+ * host integration.
+ *
  * Live token snapshot backed by the addon's preview dev-time HMR event.
  *
  * The initial snapshot is *injected* by the addon preview via
@@ -646,6 +674,7 @@ declare function useSwatchbookData(): ProjectSnapshot;
  * `useSyncExternalStore`, so hooks re-render in place on each token save.
  */
 declare const TOKENS_UPDATED_EVENT = "swatchbook/tokens-updated";
+/** Host adapter API — see {@link registerTokenSource}. */
 interface TokenSnapshot {
   readonly axes: readonly VirtualAxisShape[];
   readonly presets: readonly {
@@ -658,13 +687,15 @@ interface TokenSnapshot {
   readonly cssVarPrefix: string;
   /** Project-wide baseline for the row-indicator strip from `config.indicators`. */
   readonly indicators: Readonly<Record<string, boolean>>;
-  readonly listing: Readonly<Record<string, VirtualTokenListingShape>>;
+  readonly listing: Readonly<Record<string, VirtualTokenListing>>;
   readonly tokenGraph: VirtualTokenGraph;
   readonly defaultTuple: Record<string, string>;
   /** Monotonic counter, bumped on each update. Useful as a React key. */
   readonly version: number;
 }
 /**
+ * Host adapter API — same integration tier as {@link registerChannel}.
+ *
  * 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
@@ -672,6 +703,12 @@ interface TokenSnapshot {
  * snapshot, so a partial source is safe.
  */
 declare function registerTokenSource(source: Partial<TokenSnapshot>): void;
+/**
+ * Host adapter API — same integration tier as {@link registerChannel}. Most
+ * consumers read project data through `useSwatchbookData()` /
+ * `SwatchbookProvider` instead; this is the internal subscription
+ * `useProject()`'s fallback path uses to read the live channel-fed snapshot.
+ */
 declare function useTokenSnapshot(): TokenSnapshot;
 //#endregion
 //#region src/ShadowPreview.d.ts
@@ -822,7 +859,13 @@ declare function TokenUsageSnippet({
 //#endregion
 //#region src/TokenNavigator.d.ts
 interface TokenNavigatorProps {
-  /** If provided, mount at this dot-path subtree and hide everything outside it. */
+  /**
+   * If provided, mount at this dot-path subtree and hide everything outside
+   * it. Unlike every other listing block's `filter` (a glob over paths,
+   * inclusion-only), `root` is a single literal path that also affects
+   * where the tree mounts and how breadcrumbs render — it re-roots the
+   * navigator, not just narrows its rows.
+   */
   root?: string;
   /**
    * Restrict the tree to tokens with the given DTCG `$type`(s). Pass a single
@@ -830,6 +873,10 @@ interface TokenNavigatorProps {
    * small-multiples view (`type={['duration', 'cubicBezier', 'transition']}`).
    * Composes with `root` — both constraints must hold. Group nodes that end
    * up with no surviving leaves collapse out.
+   *
+   * Accepts `string | readonly string[]` — wider than `TokenTableProps.type`
+   * (`string`-only) because a small-multiples tree view benefits from
+   * multi-type scoping in a way a flat table doesn't.
    */
   type?: string | readonly string[];
   /**
@@ -966,5 +1013,5 @@ declare function TypographyScale({
   sortDir
 }: TypographyScaleProps): ReactElement;
 //#endregion
-export { AliasChain, type AliasChainProps, AliasedBy, type AliasedByProps, AxesContext, AxisVariance, type AxisVarianceProps, type BlockChannel, 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, onChannel, registerChannel, registerTokenSource, useActiveAxes, useActiveTheme, useChannelGlobals, useColorFormat, useOptionalSwatchbookData, useSwatchbookData, useTokenSnapshot };
+export { AliasChain, type AliasChainProps, AliasedBy, type AliasedByProps, AxesContext, AxisVariance, type AxisVarianceProps, type BlockChannel, 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, DimensionSample, type DimensionSampleProps, DimensionScale, type DimensionScaleProps, type DimensionVisual, FontFamilyPreview, type FontFamilyPreviewProps, FontWeightScale, type FontWeightScaleProps, type FormatColorResult, GradientPalette, type GradientPaletteProps, type IndicatorName, type IndicatorsProp, MotionPreview, type MotionPreviewProps, MotionSample, type MotionSampleProps, type MotionSpeed, type NormalizedColor, OpacityScale, type OpacityScaleProps, type ProjectSnapshot, ShadowPreview, type ShadowPreviewProps, ShadowSample, type ShadowSampleProps, type SortBy, type SortDir, StrokeStylePreview, type StrokeStylePreviewProps, 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 VirtualDiagnosticShape as VirtualDiagnostic, type VirtualPresetShape as VirtualPreset, type VirtualTokenShape as VirtualToken, type VirtualTokenGraph, type VirtualTokenListing, formatColor, onChannel, registerChannel, registerTokenSource, useActiveAxes, useActiveTheme, useChannelGlobals, useColorFormat, useOptionalSwatchbookData, useSwatchbookData, useTokenSnapshot };
 //# sourceMappingURL=index.d.mts.map