@unpunnyfuns/swatchbook-blocks 1.1.0 → 1.2.0

package/README.md

@@ -39,10 +39,7 @@ Block catalogue, props, and composition patterns live in the [blocks reference](
 
 ## Boundaries
 
-- ✅ 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.
+Blocks read from `SwatchbookProvider`, not the addon's internal `virtual:swatchbook/tokens` module; don't import that directly. And `useGlobals` / `useArgs` from `storybook/preview-api` throw in a docs context, so don't call them inside custom blocks.
 
 ## Credits
 

package/dist/index.d.mts

@@ -111,6 +111,15 @@ interface ProjectSnapshot {
   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
@@ -144,10 +153,17 @@ declare function useActiveTheme(): string;
 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. Populated
- * by the addon's preview decorator from the `swatchbookColorFormat` global
- * (per-story `globals` or toolbar dropdown) and consumed by blocks that
- * render color-token values. Emitted CSS is unaffected.
+ * 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 snapshot's
+ * `defaultColorFormat` (from `Config.defaultColorFormat`). "Active
+ * snapshot" is whichever source is actually feeding the render:
+ * `SwatchbookProvider` when a story decorator mounted one, otherwise the
+ * channel-fed `TokenSnapshot` 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
@@ -155,6 +171,12 @@ declare function useActiveAxes(): Readonly<Record<string, string>>;
  * isn't available).
  */
 declare const ColorFormatContext: _$react.Context<ColorFormat | null>;
+/**
+ * Resolves the color-display format from the context/snapshot/default
+ * chain: `ColorFormatContext` → active snapshot'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/internal/sort-tokens.d.ts
@@ -178,12 +200,19 @@ interface BorderPreviewProps {
   sortBy?: SortBy;
   /** `'asc'` (default) or `'desc'`. */
   sortDir?: SortDir;
+  /**
+   * Highest-precedence color format for this preview's values, overriding
+   * an outer `ColorFormatContext` and the project's `defaultColorFormat`.
+   * Omit to inherit the existing precedence chain (see `useColorFormat`).
+   */
+  colorFormat?: ColorFormat;
 }
 declare function BorderPreview({
   filter,
   caption,
   sortBy,
-  sortDir
+  sortDir,
+  colorFormat
 }: BorderPreviewProps): ReactElement;
 //#endregion
 //#region src/border-preview/BorderSample.d.ts
@@ -227,13 +256,20 @@ interface ColorPaletteProps {
   sortBy?: SortBy;
   /** `'asc'` (default) or `'desc'`. */
   sortDir?: SortDir;
+  /**
+   * Highest-precedence color format for this palette's values, overriding
+   * an outer `ColorFormatContext` and the project's `defaultColorFormat`.
+   * Omit to inherit the existing precedence chain (see `useColorFormat`).
+   */
+  colorFormat?: ColorFormat;
 }
 declare function ColorPalette({
   filter,
   groupBy,
   caption,
   sortBy,
-  sortDir
+  sortDir,
+  colorFormat
 }: ColorPaletteProps): ReactElement;
 //#endregion
 //#region src/indicators/resolve.d.ts
@@ -303,6 +339,12 @@ interface ColorTableProps {
   id?: string;
   /** Configure the per-row indicator strip. See `IndicatorsProp`. Gamut stays in the Value cell, so it is not part of this strip. */
   indicators?: IndicatorsProp;
+  /**
+   * Highest-precedence color format for this table's values, overriding
+   * an outer `ColorFormatContext` and the project's `defaultColorFormat`.
+   * Omit to inherit the existing precedence chain (see `useColorFormat`).
+   */
+  colorFormat?: ColorFormat;
 }
 /**
  * A grouped, searchable table of `$type: color` tokens. Suffix-matched
@@ -319,7 +361,8 @@ declare function ColorTable({
   onSelect,
   variants,
   id,
-  indicators
+  indicators,
+  colorFormat
 }: ColorTableProps): ReactElement;
 //#endregion
 //#region src/Diagnostics.d.ts
@@ -471,12 +514,19 @@ interface GradientPaletteProps {
   sortBy?: SortBy;
   /** `'asc'` (default) or `'desc'`. */
   sortDir?: SortDir;
+  /**
+   * Highest-precedence color format for this palette's values, overriding
+   * an outer `ColorFormatContext` and the project's `defaultColorFormat`.
+   * Omit to inherit the existing precedence chain (see `useColorFormat`).
+   */
+  colorFormat?: ColorFormat;
 }
 declare function GradientPalette({
   filter,
   caption,
   sortBy,
-  sortDir
+  sortDir,
+  colorFormat
 }: GradientPaletteProps): ReactElement;
 //#endregion
 //#region src/motion-preview/MotionSample.d.ts
@@ -690,6 +740,14 @@ interface TokenSnapshot {
   readonly listing: Readonly<Record<string, VirtualTokenListing>>;
   readonly tokenGraph: VirtualTokenGraph;
   readonly defaultTuple: Record<string, string>;
+  /**
+   * Starting color format for blocks that display color values:
+   * `config.defaultColorFormat` from core, forwarded from the addon's
+   * `registerTokenSource` call. `useColorFormat()` falls back to this on
+   * the provider-less (MDX/autodocs) path when no `ColorFormatContext`/
+   * channel-globals override is active.
+   */
+  readonly defaultColorFormat: ColorFormat;
   /** Monotonic counter, bumped on each update. Useful as a React key. */
   readonly version: number;
 }
@@ -728,12 +786,19 @@ interface ShadowPreviewProps {
   sortBy?: SortBy;
   /** `'asc'` (default) or `'desc'`. */
   sortDir?: SortDir;
+  /**
+   * Highest-precedence color format for this preview's values, overriding
+   * an outer `ColorFormatContext` and the project's `defaultColorFormat`.
+   * Omit to inherit the existing precedence chain (see `useColorFormat`).
+   */
+  colorFormat?: ColorFormat;
 }
 declare function ShadowPreview({
   filter,
   caption,
   sortBy,
-  sortDir
+  sortDir,
+  colorFormat
 }: ShadowPreviewProps): ReactElement;
 //#endregion
 //#region src/shadow-preview/ShadowSample.d.ts
@@ -776,10 +841,18 @@ interface TokenDetailProps {
   path: string;
   /** Override the heading. Defaults to the path. */
   heading?: string;
+  /**
+   * Highest-precedence color format for this block's values, overriding
+   * an outer `ColorFormatContext` and the project's `defaultColorFormat`.
+   * Omit to inherit the existing precedence chain (see `useColorFormat`).
+   * Also governs the composed `CompositeBreakdown` / `AxisVariance` sub-parts.
+   */
+  colorFormat?: ColorFormat;
 }
 declare function TokenDetail({
   path,
-  heading
+  heading,
+  colorFormat
 }: TokenDetailProps): ReactElement;
 //#endregion
 //#region src/token-detail/AliasChain.d.ts
@@ -804,18 +877,32 @@ declare function AliasedBy({
 interface AxisVarianceProps {
   /** Full dot-path of the token. */
   path: string;
+  /**
+   * Highest-precedence color format for this block's values, overriding
+   * an outer `ColorFormatContext` and the project's `defaultColorFormat`.
+   * Omit to inherit the existing precedence chain (see `useColorFormat`).
+   */
+  colorFormat?: ColorFormat;
 }
 declare function AxisVariance({
-  path
+  path,
+  colorFormat
 }: AxisVarianceProps): ReactElement;
 //#endregion
 //#region src/token-detail/CompositeBreakdown.d.ts
 interface CompositeBreakdownProps {
   /** Full dot-path of the token. */
   path: string;
+  /**
+   * Highest-precedence color format for this block's values, overriding
+   * an outer `ColorFormatContext` and the project's `defaultColorFormat`.
+   * Omit to inherit the existing precedence chain (see `useColorFormat`).
+   */
+  colorFormat?: ColorFormat;
 }
 declare function CompositeBreakdown({
-  path
+  path,
+  colorFormat
 }: CompositeBreakdownProps): ReactElement | null;
 //#endregion
 //#region src/token-detail/CompositePreview.d.ts
@@ -909,6 +996,13 @@ interface TokenNavigatorProps {
   id?: string;
   /** Configure the per-row indicator strip. See `IndicatorsProp`. */
   indicators?: IndicatorsProp;
+  /**
+   * Highest-precedence color format for this tree's values, overriding
+   * an outer `ColorFormatContext` and the project's `defaultColorFormat`.
+   * Omit to inherit the existing precedence chain (see `useColorFormat`).
+   * Also governs the composed row-detail `TokenDetail` slide-over.
+   */
+  colorFormat?: ColorFormat;
 }
 /**
  * A collapsible, searchable tree of tokens with roving-tabindex keyboard
@@ -922,7 +1016,8 @@ declare function TokenNavigator({
   searchable,
   onSelect,
   id,
-  indicators
+  indicators,
+  colorFormat
 }: TokenNavigatorProps): ReactElement;
 //#endregion
 //#region src/TokenTable.d.ts
@@ -967,6 +1062,13 @@ interface TokenTableProps {
   id?: string;
   /** Configure the per-row indicator strip. See `IndicatorsProp`. */
   indicators?: IndicatorsProp;
+  /**
+   * Highest-precedence color format for this table's values, overriding
+   * an outer `ColorFormatContext` and the project's `defaultColorFormat`.
+   * Omit to inherit the existing precedence chain (see `useColorFormat`).
+   * Also governs the composed row-detail `TokenDetail` slide-over.
+   */
+  colorFormat?: ColorFormat;
 }
 /**
  * A sortable, searchable table of tokens. Click a row to inspect it in a
@@ -982,7 +1084,8 @@ declare function TokenTable({
   searchable,
   onSelect,
   id,
-  indicators
+  indicators,
+  colorFormat
 }: TokenTableProps): ReactElement;
 //#endregion
 //#region src/TypographyScale.d.ts