@unpunnyfuns/swatchbook-blocks 0.2.2 → 0.3.0

package/dist/index.d.mts

@@ -46,6 +46,111 @@ interface FormatColorResult {
  */
 declare function formatColor(value: unknown, format: ColorFormat, fallback?: string): FormatColorResult;
 //#endregion
+//#region src/contexts.d.ts
+/**
+ * Typed shape of the addon's `virtual:swatchbook/tokens` module, duplicated
+ * as value-importable interfaces so consumers outside the addon's Vite
+ * plugin (unit tests, custom React apps) can construct a snapshot by hand.
+ *
+ * The ambient `declare module 'virtual:swatchbook/tokens'` declarations in
+ * `packages/addon/src/virtual.d.ts` describe the same payload; the two
+ * stay in sync by eye.
+ */
+interface VirtualAxisShape {
+  name: string;
+  contexts: readonly string[];
+  default: string;
+  description?: string;
+  source: 'resolver' | 'layered' | 'synthetic';
+}
+interface VirtualThemeShape {
+  name: string;
+  input: Record<string, string>;
+  sources: string[];
+}
+interface VirtualDiagnosticShape {
+  severity: 'error' | 'warn' | 'info';
+  group: string;
+  message: string;
+  filename?: string;
+  line?: number;
+  column?: number;
+}
+interface VirtualTokenShape {
+  $type?: string;
+  $value?: unknown;
+  $description?: string;
+  aliasOf?: string;
+  aliasChain?: readonly string[];
+  aliasedBy?: readonly string[];
+}
+interface VirtualPresetShape {
+  name: string;
+  axes: Partial<Record<string, string>>;
+  description?: string;
+}
+/**
+ * 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[];
+  /** Axis names suppressed via `config.disabledAxes` — pinned to their defaults, hidden from the toolbar. */
+  disabledAxes: readonly string[];
+  presets: readonly VirtualPresetShape[];
+  themes: readonly VirtualThemeShape[];
+  themesResolved: Record<string, Record<string, VirtualTokenShape>>;
+  activeTheme: string;
+  activeAxes: Readonly<Record<string, string>>;
+  cssVarPrefix: string;
+  diagnostics: readonly VirtualDiagnosticShape[];
+  css: string;
+}
+/**
+ * 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 permutation ID.
+ */
+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.
+ *
+ * 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>;
+declare function useColorFormat(): ColorFormat;
+//#endregion
+//#region src/internal/sort-tokens.d.ts
+type SortBy = 'path' | 'value' | 'none';
+type SortDir = 'asc' | 'desc';
+//#endregion
 //#region src/BorderPreview.d.ts
 interface BorderPreviewProps {
   /**
@@ -55,10 +160,20 @@ interface BorderPreviewProps {
   filter?: string;
   /** Override the caption. */
   caption?: string;
+  /**
+   * Sort order. `'path'` (default) sorts lexicographically on the
+   * dot-path; `'value'` falls through to path (borders don't have a
+   * single-axis ordering); `'none'` preserves project order.
+   */
+  sortBy?: SortBy;
+  /** `'asc'` (default) or `'desc'`. */
+  sortDir?: SortDir;
 }
 declare function BorderPreview({
   filter,
-  caption
+  caption,
+  sortBy,
+  sortDir
 }: BorderPreviewProps): ReactElement;
 //#endregion
 //#region src/border-preview/BorderSample.d.ts
@@ -92,13 +207,44 @@ interface ColorPaletteProps {
   groupBy?: number;
   /** Override the section caption. */
   caption?: string;
+  /**
+   * Sort order within each group.
+   * - `'path'` (default) — lexicographic on the dot-path.
+   * - `'value'` — perceptual ordering: oklch L → C → H (ramps read
+   *   light→dark, then warm→cool within each lightness band).
+   * - `'none'` — preserve project iteration order.
+   */
+  sortBy?: SortBy;
+  /** `'asc'` (default) or `'desc'`. */
+  sortDir?: SortDir;
 }
 declare function ColorPalette({
   filter,
   groupBy,
-  caption
+  caption,
+  sortBy,
+  sortDir
 }: ColorPaletteProps): ReactElement;
 //#endregion
+//#region src/Diagnostics.d.ts
+interface DiagnosticsProps {
+  /** Override the section caption. Defaults to a severity summary. */
+  caption?: string;
+}
+/**
+ * Render the project's load diagnostics — parser errors, resolver warnings,
+ * disabled-axes validation issues, etc. — as a collapsible list. Auto-opens
+ * when the project carries errors or warnings; stays collapsed for clean
+ * loads and info-only loads.
+ *
+ * Replaces the diagnostics section from the addon's (now-retired) Design
+ * Tokens panel. Consumers compose it alongside TokenNavigator / TokenTable
+ * on their own MDX pages.
+ */
+declare function Diagnostics({
+  caption
+}?: DiagnosticsProps): ReactElement;
+//#endregion
 //#region src/dimension-scale/DimensionBar.d.ts
 type DimensionKind = 'length' | 'radius' | 'size';
 interface DimensionBarProps {
@@ -133,11 +279,23 @@ interface DimensionScaleProps {
   kind?: DimensionKind;
   /** Override the caption. */
   caption?: string;
+  /**
+   * Sort order.
+   * - `'value'` (default) — numeric by rendered pixel size (`px` / `rem` / `em`).
+   *   Non-convertible units (ex/ch/%) land after the convertible ones.
+   * - `'path'` — lexicographic on the dot-path.
+   * - `'none'` — preserve project iteration order.
+   */
+  sortBy?: SortBy;
+  /** `'asc'` (default) or `'desc'`. */
+  sortDir?: SortDir;
 }
 declare function DimensionScale({
   filter,
   kind,
-  caption
+  caption,
+  sortBy,
+  sortDir
 }: DimensionScaleProps): ReactElement;
 //#endregion
 //#region src/FontFamilySample.d.ts
@@ -151,11 +309,21 @@ interface FontFamilySampleProps {
   sample?: string;
   /** Override the caption. */
   caption?: string;
+  /**
+   * Sort order. `'path'` (default) sorts lexicographically on the
+   * dot-path; `'value'` ordering falls through to path for this block's
+   * type (composite / non-numeric); `'none'` preserves project order.
+   */
+  sortBy?: SortBy;
+  /** `'asc'` (default) or `'desc'`. */
+  sortDir?: SortDir;
 }
 declare function FontFamilySample({
   filter,
   sample,
-  caption
+  caption,
+  sortBy,
+  sortDir
 }: FontFamilySampleProps): ReactElement;
 //#endregion
 //#region src/FontWeightScale.d.ts
@@ -169,11 +337,22 @@ interface FontWeightScaleProps {
   sample?: string;
   /** Override the caption. */
   caption?: string;
+  /**
+   * Sort order.
+   * - `'value'` (default) — ascending numeric by weight (100 → 900).
+   * - `'path'` — lexicographic on the dot-path.
+   * - `'none'` — preserve project iteration order.
+   */
+  sortBy?: SortBy;
+  /** `'asc'` (default) or `'desc'`. */
+  sortDir?: SortDir;
 }
 declare function FontWeightScale({
   filter,
   sample,
-  caption
+  caption,
+  sortBy,
+  sortDir
 }: FontWeightScaleProps): ReactElement;
 //#endregion
 //#region src/GradientPalette.d.ts
@@ -185,10 +364,20 @@ interface GradientPaletteProps {
   filter?: string;
   /** Override the caption. */
   caption?: string;
+  /**
+   * Sort order. `'path'` (default) sorts lexicographically on the
+   * dot-path; `'value'` falls through to path (gradients don't have
+   * a single-axis ordering); `'none'` preserves project order.
+   */
+  sortBy?: SortBy;
+  /** `'asc'` (default) or `'desc'`. */
+  sortDir?: SortDir;
 }
 declare function GradientPalette({
   filter,
-  caption
+  caption,
+  sortBy,
+  sortDir
 }: GradientPaletteProps): ReactElement;
 //#endregion
 //#region src/motion-preview/MotionSample.d.ts
@@ -226,107 +415,6 @@ declare function MotionPreview({
   caption
 }: MotionPreviewProps): ReactElement;
 //#endregion
-//#region src/contexts.d.ts
-/**
- * Typed shape of the addon's `virtual:swatchbook/tokens` module, duplicated
- * as value-importable interfaces so consumers outside the addon's Vite
- * plugin (unit tests, custom React apps) can construct a snapshot by hand.
- *
- * The ambient `declare module 'virtual:swatchbook/tokens'` declarations in
- * `packages/addon/src/virtual.d.ts` describe the same payload; the two
- * stay in sync by eye.
- */
-interface VirtualAxisShape {
-  name: string;
-  contexts: readonly string[];
-  default: string;
-  description?: string;
-  source: 'resolver' | 'layered' | 'synthetic';
-}
-interface VirtualThemeShape {
-  name: string;
-  input: Record<string, string>;
-  sources: string[];
-}
-interface VirtualDiagnosticShape {
-  severity: 'error' | 'warn' | 'info';
-  group: string;
-  message: string;
-  filename?: string;
-  line?: number;
-  column?: number;
-}
-interface VirtualTokenShape {
-  $type?: string;
-  $value?: unknown;
-  $description?: string;
-  aliasOf?: string;
-  aliasChain?: readonly string[];
-  aliasedBy?: readonly string[];
-}
-interface VirtualPresetShape {
-  name: string;
-  axes: Partial<Record<string, string>>;
-  description?: string;
-}
-/**
- * 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[];
-  /** Axis names suppressed via `config.disabledAxes` — pinned to their defaults, hidden from the toolbar. */
-  disabledAxes: readonly string[];
-  presets: readonly VirtualPresetShape[];
-  themes: readonly VirtualThemeShape[];
-  themesResolved: Record<string, Record<string, VirtualTokenShape>>;
-  activeTheme: string;
-  activeAxes: Readonly<Record<string, string>>;
-  cssVarPrefix: string;
-  diagnostics: readonly VirtualDiagnosticShape[];
-  css: string;
-}
-/**
- * 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 permutation ID.
- */
-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.
- *
- * 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>;
-declare function useColorFormat(): ColorFormat;
-//#endregion
 //#region src/provider.d.ts
 interface SwatchbookProviderProps {
   value: ProjectSnapshot;
@@ -361,10 +449,20 @@ interface ShadowPreviewProps {
   filter?: string;
   /** Override the caption. */
   caption?: string;
+  /**
+   * Sort order. `'path'` (default) sorts lexicographically on the
+   * dot-path; `'value'` falls through to path (shadows don't have a
+   * single-axis ordering); `'none'` preserves project order.
+   */
+  sortBy?: SortBy;
+  /** `'asc'` (default) or `'desc'`. */
+  sortDir?: SortDir;
 }
 declare function ShadowPreview({
   filter,
-  caption
+  caption,
+  sortBy,
+  sortDir
 }: ShadowPreviewProps): ReactElement;
 //#endregion
 //#region src/shadow-preview/ShadowSample.d.ts
@@ -385,10 +483,20 @@ interface StrokeStyleSampleProps {
   filter?: string;
   /** Override the caption. */
   caption?: string;
+  /**
+   * Sort order. `'path'` (default) sorts lexicographically on the
+   * dot-path; `'value'` ordering falls through to path for this block's
+   * type (composite / non-numeric); `'none'` preserves project order.
+   */
+  sortBy?: SortBy;
+  /** `'asc'` (default) or `'desc'`. */
+  sortDir?: SortDir;
 }
 declare function StrokeStyleSample({
   filter,
-  caption
+  caption,
+  sortBy,
+  sortDir
 }: StrokeStyleSampleProps): ReactElement;
 //#endregion
 //#region src/TokenDetail.d.ts
@@ -510,16 +618,34 @@ interface TokenTableProps {
   filter?: string;
   /** Restrict to one DTCG `$type`. */
   type?: string;
-  /** Show the CSS variable reference column. Defaults to `true`. */
-  showVar?: boolean;
   /** Override the table caption. */
   caption?: string;
+  /**
+   * Sort order.
+   * - `'path'` (default) — lexicographic on the dot-path.
+   * - `'value'` — per-`$type`: numeric for `dimension` / `duration` /
+   *   `fontWeight`; perceptual (oklch L → C → H) for `color`; lexicographic
+   *   for `fontFamily` / `strokeStyle`. Composite types fall through to
+   *   path order.
+   * - `'none'` — preserve project iteration order.
+   */
+  sortBy?: SortBy;
+  /** `'asc'` (default) or `'desc'`. */
+  sortDir?: SortDir;
+  /**
+   * Called with the clicked row's dot-path. When set, the built-in
+   * `<TokenDetail>` slide-over is suppressed — the consumer owns the
+   * follow-up UI (inline panel, drill-down route, …).
+   */
+  onSelect?(path: string): void;
 }
 declare function TokenTable({
   filter,
   type,
-  showVar,
-  caption
+  caption,
+  sortBy,
+  sortDir,
+  onSelect
 }: TokenTableProps): ReactElement;
 //#endregion
 //#region src/TypographyScale.d.ts
@@ -533,12 +659,22 @@ interface TypographyScaleProps {
   sample?: string;
   /** Override the caption. */
   caption?: string;
+  /**
+   * Sort order. `'path'` (default) sorts lexicographically on the
+   * dot-path; `'value'` ordering falls through to path for this block's
+   * type (composite / non-numeric); `'none'` preserves project order.
+   */
+  sortBy?: SortBy;
+  /** `'asc'` (default) or `'desc'`. */
+  sortDir?: SortDir;
 }
 declare function TypographyScale({
   filter,
   sample,
-  caption
+  caption,
+  sortBy,
+  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, CompositeBreakdown, type CompositeBreakdownProps, CompositePreview, type CompositePreviewProps, ConsumerOutput, type ConsumerOutputProps, 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, type ProjectSnapshot, ShadowPreview, type ShadowPreviewProps, ShadowSample, type ShadowSampleProps, StrokeStyleSample, type StrokeStyleSampleProps, SwatchbookContext, SwatchbookProvider, type SwatchbookProviderProps, ThemeContext, 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 VirtualThemeShape as VirtualTheme, type VirtualThemeShape, type VirtualTokenShape as VirtualToken, type VirtualTokenShape, formatColor, useActiveAxes, useActiveTheme, 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, 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, type ProjectSnapshot, ShadowPreview, type ShadowPreviewProps, ShadowSample, type ShadowSampleProps, StrokeStyleSample, type StrokeStyleSampleProps, SwatchbookContext, SwatchbookProvider, type SwatchbookProviderProps, ThemeContext, 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 VirtualThemeShape as VirtualTheme, type VirtualThemeShape, type VirtualTokenShape as VirtualToken, type VirtualTokenShape, formatColor, useActiveAxes, useActiveTheme, useColorFormat, useOptionalSwatchbookData, useSwatchbookData };
 //# sourceMappingURL=index.d.mts.map