@unpunnyfuns/swatchbook-blocks 0.16.0 → 0.18.0

package/dist/index.d.mts

@@ -84,6 +84,34 @@ interface VirtualTokenShape {
   aliasChain?: readonly string[];
   aliasedBy?: readonly string[];
 }
+/**
+ * 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.
+ *
+ * Only the fields blocks consume are typed here; the plugin's full shape
+ * lives in `@unpunnyfuns/swatchbook-core`.
+ */
+interface VirtualTokenListingShape {
+  names: Record<string, string>;
+  previewValue?: string | number;
+  source?: {
+    resource: string;
+    loc?: {
+      start: {
+        line: number;
+        column: number;
+        offset: number;
+      };
+      end: {
+        line: number;
+        column: number;
+        offset: number;
+      };
+    };
+  };
+}
 interface VirtualPresetShape {
   name: string;
   axes: Partial<Record<string, string>>;
@@ -106,6 +134,14 @@ interface ProjectSnapshot {
   cssVarPrefix: string;
   diagnostics: readonly VirtualDiagnosticShape[];
   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, VirtualTokenListingShape>>;
 }
 /**
  * Context carrying the full {@link ProjectSnapshot}. `null` sentinel lets
@@ -246,33 +282,35 @@ interface ColorTableProps {
   /** `'asc'` (default) or `'desc'`. */
   sortDir?: SortDir;
   /**
-   * Render a fuzzy-search input above the table (case-insensitive,
-   * single-char typo tolerance, out-of-order terms, matches across path +
-   * any format value). Defaults to `true`.
+   * Render a fuzzy-search input above the table. Defaults to `true`.
    */
   searchable?: boolean;
   /**
-   * Called with the clicked row's dot-path. When set, the built-in
-   * `<TokenDetail>` drawer is suppressed — the consumer owns follow-up UI.
+   * Called with the *currently-selected* variant's dot-path on row click.
+   * When set, the built-in expand-in-place behavior is suppressed — the
+   * consumer owns follow-up UI.
    */
   onSelect?(path: string): void;
   /**
    * Map from a display label to a suffix matched against each token's
-   * trailing path segment. A row whose leaf matches one of the suffixes
-   * gets the corresponding label rendered as a pill after the token name.
+   * trailing path segment. Tokens whose leaves match a suffix are grouped
+   * under a shared "base" path (the path with the suffix stripped), and
+   * the group renders as a single row with a pill selector — clicking a
+   * pill swaps the displayed values to that variant. Sibling tokens
+   * without a suffix that share the group's base path are labeled `base`.
    *
-   * Accepts both DTCG-idiomatic and Backmarket-style conventions:
-   * - **Dot segment** (`color.bg.hi.disabled`): the last dot-segment equals
-   *   the suffix exactly (`suffix === 'disabled'`).
-   * - **Hyphen tail** (`color.bg.hi-d`): the last dot-segment ends in
-   *   `-<suffix>` (`suffix === 'd'`).
+   * Matches both DTCG-idiomatic and Backmarket-style conventions:
+   * - **Dot segment** (`color.bg.hi.disabled`): last dot-segment equals
+   *   the suffix (`disabled`). Base path = drop the last segment.
+   * - **Hyphen tail** (`color.bg.hi-d`): last dot-segment ends in
+   *   `-<suffix>` (`d`). Base path = trim the `-<suffix>` from the leaf.
    *
-   * Longest-suffix-wins: `{ hover: 'h', hoverDark: 'h-dark' }` picks
-   * `hoverDark` for a path ending in `-h-dark`. The hyphen-tail form
-   * requires an actual hyphen boundary — suffix `0` does not match
-   * `neutral-900`. Tokens that don't match any suffix render with no pill.
+   * Longest-suffix-wins. Hyphen-tail form requires an actual hyphen
+   * boundary — suffix `0` does not match `neutral-900`.
    *
-   * Empty map (default) → no pills; the block behaves exactly as before.
+   * Single-member groups render as plain rows (no pill selector). Empty
+   * map (default) disables grouping entirely; each token renders as its
+   * own row, identical to the pre-grouping behavior.
    */
   variants?: Record<string, string>;
 }