@unpunnyfuns/swatchbook-blocks 0.67.0 → 0.69.0

package/README.md

@@ -4,7 +4,7 @@ React MDX doc blocks for [swatchbook](https://github.com/unpunnyfuns/swatchbook)
 
 Render your DTCG tokens in `.mdx` stories: swatch grids, type-specific previews, per-token inspectors. The blocks react to the toolbar's axis flips without any wiring in your story code.
 
-Most consumers pick this up transitively via [`@unpunnyfuns/swatchbook-addon`](../addon); `import { TokenTable } from '@unpunnyfuns/swatchbook-addon'` works out of the box. Install this package directly when you want blocks *without* the Storybook addon, such as unit tests or a standalone React app wrapping tokens in a custom surface.
+Most consumers pick this up transitively via [`@unpunnyfuns/swatchbook-addon`](../addon); `import { TokenTable } from '@unpunnyfuns/swatchbook-addon'` works out of the box. Install this package directly when you want blocks _without_ the Storybook addon, such as unit tests or a standalone React app wrapping tokens in a custom surface.
 
 ## Install
 
@@ -32,7 +32,7 @@ import snapshot from './tokens-snapshot.json';
 
 <SwatchbookProvider value={snapshot}>
   <TokenTable filter="color.**" />
-</SwatchbookProvider>
+</SwatchbookProvider>;
 ```
 
 Block catalogue, props, and composition patterns live in the [blocks reference](https://unpunnyfuns.github.io/swatchbook/reference/blocks) and the [authoring guide](https://unpunnyfuns.github.io/swatchbook/guides/authoring-doc-stories).

package/dist/index.d.mts

@@ -304,6 +304,12 @@ interface ColorTableProps {
   /** Configure the per-row indicator strip. See `IndicatorsProp`. Gamut stays in the Value cell, so it is not part of this strip. */
   indicators?: IndicatorsProp;
 }
+/**
+ * A grouped, searchable table of `$type: color` tokens. Suffix-matched
+ * variants (see `variants` prop) collapse into a single row with a pill
+ * selector; clicking a row expands it in place to show the description,
+ * alias chain, and (for grouped rows) every variant's hex/HSL/OKLCH values.
+ */
 declare function ColorTable({
   filter,
   caption,
@@ -543,10 +549,6 @@ interface OpacityScaleProps {
  * checkerboard backdrop, so the transparency is visually readable. The
  * number by itself (`0.4`) doesn't convey what the token looks like
  * applied to a surface; the sample does.
- *
- * Only tokens whose `$value` is a finite number between 0 and 1
- * inclusive are rendered — non-opacity `number` siblings (`line-height`,
- * `z-index`) fall out naturally.
  */
 declare function OpacityScale({
   filter,
@@ -576,6 +578,32 @@ interface ChannelGlobals {
 }
 declare function useChannelGlobals(): ChannelGlobals;
 //#endregion
+//#region src/internal/channel.d.ts
+/**
+ * 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
+ * owns the Storybook relationship, injects the channel at preview init via
+ * {@link registerChannel}, mirroring how `registerTokenSource` injects the
+ * initial token snapshot.
+ */
+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.
+ */
+declare function registerChannel(next: BlockChannel): void;
+/**
+ * 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.
+ */
+declare function onChannel(attach: (channel: BlockChannel) => void): void;
+//#endregion
 //#region src/provider.d.ts
 interface SwatchbookProviderProps {
   value: ProjectSnapshot;
@@ -835,6 +863,11 @@ interface TokenNavigatorProps {
   /** Configure the per-row indicator strip. See `IndicatorsProp`. */
   indicators?: IndicatorsProp;
 }
+/**
+ * A collapsible, searchable tree of tokens with roving-tabindex keyboard
+ * navigation. Click a leaf to inspect it in a slide-over (unless `onSelect`
+ * is provided, which hands the follow-up to the consumer).
+ */
 declare function TokenNavigator({
   root,
   type,
@@ -888,6 +921,11 @@ interface TokenTableProps {
   /** Configure the per-row indicator strip. See `IndicatorsProp`. */
   indicators?: IndicatorsProp;
 }
+/**
+ * A sortable, searchable table of tokens. Click a row to inspect it in a
+ * slide-over (unless `onSelect` is provided, which hands the follow-up to the
+ * consumer).
+ */
 declare function TokenTable({
   filter,
   type,
@@ -928,5 +966,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 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, 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, 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 };
 //# sourceMappingURL=index.d.mts.map