inkbridge 0.1.0-beta.2 → 0.1.0-beta.21

package/scanner/tailwind-parser.ts

@@ -166,20 +166,51 @@ export function resolveSpacing(value: string): number | undefined {
 // State Modifiers
 // ============================================================================
 
-export const STATE_MODIFIERS = [
+/**
+ * Modifiers that imply the component has its OWN interactive/aria state
+ * (it receives focus, can be disabled directly, etc.). These are the
+ * trigger set for state-component classification — if a root className
+ * uses any of these, the component participates in a state-variant matrix
+ * and the plugin renders it via the state-master path.
+ *
+ * Deliberately excludes `group-*:` and `peer-*:` modifiers — those are
+ * *passive reactions* to a parent's or sibling's state (e.g. Label
+ * dimming when its `<input>` peer is `:disabled`). They don't justify
+ * promoting the component to a state primitive. A Label that only
+ * carries `peer-disabled:opacity-50` should stay `simple`, render its
+ * text children normally, and not get hoisted into a state-master that
+ * wipes its content.
+ */
+export const OWN_STATE_MODIFIERS = [
   'hover:',
   'focus:',
   'focus-visible:',
   'focus-within:',
   'active:',
   'disabled:',
+  'checked:',
   'aria-invalid:',
   'aria-selected:',
   'aria-expanded:',
   'data-[state=open]:',
   'data-[state=checked]:',
   'data-[state=active]:',
+  'data-[checked]:',
   'data-[disabled]:',
+];
+
+/**
+ * All recognized state modifiers — used during state-grouping after a
+ * component has been classified, so passive `group-*` / `peer-*`
+ * variants still get their classes captured even though they don't
+ * trigger classification on their own.
+ */
+export const STATE_MODIFIERS = [
+  ...OWN_STATE_MODIFIERS,
+  'group-data-[checked]:',
+  'group-data-[disabled]:',
+  'peer-data-[checked]:',
+  'peer-data-[disabled]:',
   'group-hover:',
   'group-focus:',
   'peer-focus:',
@@ -377,13 +408,13 @@ export function extractPaletteTokens(classes: string[]): Record<string, string>
   const resolvePaletteColor = (token: string): string | null => {
     if (!token) return null;
     if (token === 'transparent' || token === 'current' || token === 'inherit') return null;
-    const direct = (colors as any)[token];
+    const direct = (colors as Record<string, string | Record<string, string>>)[token];
     if (typeof direct === 'string') return direct;
     const parts = token.split('-');
     if (parts.length < 2) return null;
     const shade = parts[parts.length - 1];
     const name = parts.slice(0, -1).join('-');
-    const group = (colors as any)[name];
+    const group = (colors as Record<string, string | Record<string, string>>)[name];
     if (group && typeof group === 'object' && group[shade]) return group[shade];
     return null;
   };
@@ -506,7 +537,18 @@ export function groupClassesByState(classes: string[]): Record<string, string[]>
       if (!groups[stateName]) {
         groups[stateName] = [];
       }
-      groups[stateName].push(parsed.utility);
+      // Reconstitute the utility with its opacity suffix when one was
+      // parsed off — without this, `focus-visible:ring-ring/50` and
+      // `aria-invalid:ring-destructive/20` get stripped to plain
+      // `ring-ring` / `ring-destructive` (full opacity), losing the
+      // translucent look shadcn uses for soft focus / invalid rings.
+      // Symptom: State Matrix focus/error variants render solid bright
+      // rings instead of the brand-tinted, semi-transparent look the
+      // browser shows.
+      const utilityWithOpacity = parsed.opacity != null
+        ? parsed.utility + '/' + parsed.opacity
+        : parsed.utility;
+      groups[stateName].push(utilityWithOpacity);
     } else if (!parsed.modifier) {
       groups.default.push(cls);
     } else {

package/scanner/text-resize-matrix-regression.ts

@@ -0,0 +1,173 @@
+import assert from 'node:assert/strict';
+
+import { resolveTextResizeWidth, type TextResizeFrameInput } from '../src/layout/text-resize-decision';
+
+// MATRIX REGRESSION — text-resize-to-parent-content-width decision.
+//
+// This is fix-site (c) of the recurring inline-flex pill bug (see
+// `tools/figma-plugin/.ai/troubleshooting.md`). The decision lives in the
+// ui-builder's frame-with-text branch and gates whether the inserted text
+// node is resized to `(parent.maxWidth - parent.padding)` or left HUG-sized.
+//
+// Before this matrix the playbook explicitly named this site as the
+// "youngest fix and most likely to drift through refactors" — no automated
+// coverage. Extracting the decision into a pure helper made it testable
+// without stubbing the buildFigmaNode pipeline.
+//
+// Skip rules (text stays HUG-sized):
+//   - HORIZONTAL + primaryAxisAlignItems=CENTER → numbered-circle case
+//   - HORIZONTAL + primaryAxisSizingMode=AUTO (HUG) → inline-flex pill case
+//   - contextMaxWidth missing / 0 / negative → no resize to compute
+//   - padding consumes the entire maxWidth → no positive width to resize to
+
+function makeFrame(overrides: Partial<TextResizeFrameInput> = {}): TextResizeFrameInput {
+  return {
+    layoutMode: 'NONE',
+    primaryAxisAlignItems: 'MIN',
+    primaryAxisSizingMode: 'AUTO',
+    paddingLeft: 0,
+    paddingRight: 0,
+    ...overrides,
+  };
+}
+
+interface Cell {
+  frame: Partial<TextResizeFrameInput>;
+  contextMaxWidth: number | undefined | null;
+  expect: number | undefined;
+  note: string;
+}
+
+const CELLS: Cell[] = [
+  // ---- resize-allowed cells ----------------------------------------------
+  {
+    frame: { layoutMode: 'NONE' },
+    contextMaxWidth: 600,
+    expect: 600,
+    note: 'NONE parent: resize text to context max width',
+  },
+  {
+    frame: { layoutMode: 'NONE', paddingLeft: 16, paddingRight: 16 },
+    contextMaxWidth: 600,
+    expect: 568,
+    note: 'padding subtracted from target width',
+  },
+  {
+    frame: { layoutMode: 'VERTICAL' },
+    contextMaxWidth: 600,
+    expect: 600,
+    note: 'VERTICAL parent: resize text — the common block-flow case',
+  },
+  {
+    frame: { layoutMode: 'VERTICAL', primaryAxisSizingMode: 'FIXED' },
+    contextMaxWidth: 600,
+    expect: 600,
+    note: 'VERTICAL + FIXED-primary still resizes (sizing mode only affects HORIZONTAL skip)',
+  },
+  {
+    frame: { layoutMode: 'HORIZONTAL', primaryAxisSizingMode: 'FIXED' },
+    contextMaxWidth: 600,
+    expect: 600,
+    note: 'HORIZONTAL + FIXED-primary (not HUG): resize allowed — only HORIZONTAL+HUG is the pill case',
+  },
+  {
+    frame: {
+      layoutMode: 'HORIZONTAL',
+      primaryAxisAlignItems: 'SPACE_BETWEEN',
+      primaryAxisSizingMode: 'FIXED',
+    },
+    contextMaxWidth: 600,
+    expect: 600,
+    note: 'SPACE_BETWEEN is not CENTER; resize allowed',
+  },
+  {
+    frame: { layoutMode: 'GRID' },
+    contextMaxWidth: 600,
+    expect: 600,
+    note: 'GRID parent: not HORIZONTAL, so no HUG/CENTER skip applies — resize allowed',
+  },
+
+  // ---- skip cells (the bugs that motivated the helper) -------------------
+  {
+    frame: { layoutMode: 'HORIZONTAL', primaryAxisSizingMode: 'AUTO' },
+    contextMaxWidth: 600,
+    expect: undefined,
+    note: 'HORIZONTAL + AUTO = HUG: inline-flex pill case (fix-site c) — must NOT resize',
+  },
+  {
+    frame: {
+      layoutMode: 'HORIZONTAL',
+      primaryAxisAlignItems: 'CENTER',
+      primaryAxisSizingMode: 'AUTO',
+    },
+    contextMaxWidth: 600,
+    expect: undefined,
+    note: 'HORIZONTAL + CENTER: numbered-circle case — must NOT resize',
+  },
+  {
+    frame: {
+      layoutMode: 'HORIZONTAL',
+      primaryAxisAlignItems: 'CENTER',
+      primaryAxisSizingMode: 'FIXED',
+    },
+    contextMaxWidth: 600,
+    expect: undefined,
+    note: 'HORIZONTAL + CENTER + FIXED: still CENTER skip applies — must NOT resize',
+  },
+
+  // ---- edge cases --------------------------------------------------------
+  {
+    frame: { layoutMode: 'NONE' },
+    contextMaxWidth: undefined,
+    expect: undefined,
+    note: 'missing context maxWidth: no resize',
+  },
+  {
+    frame: { layoutMode: 'NONE' },
+    contextMaxWidth: null,
+    expect: undefined,
+    note: 'null context maxWidth: no resize',
+  },
+  {
+    frame: { layoutMode: 'NONE' },
+    contextMaxWidth: 0,
+    expect: undefined,
+    note: 'zero context maxWidth: no resize',
+  },
+  {
+    frame: { layoutMode: 'NONE', paddingLeft: 400, paddingRight: 400 },
+    contextMaxWidth: 600,
+    expect: undefined,
+    note: 'padding > maxWidth: target would be negative — no resize (no degenerate textNode.resize(0))',
+  },
+];
+
+function runRegression(): void {
+  const failures: string[] = [];
+
+  for (let i = 0; i < CELLS.length; i++) {
+    const cell = CELLS[i]!;
+    const frame = makeFrame(cell.frame);
+    const result = resolveTextResizeWidth(frame, cell.contextMaxWidth);
+    if (result !== cell.expect) {
+      failures.push(
+        `cell ${i}: expected ${cell.expect}, got ${result}\n  → ${cell.note}\n  → frame=${JSON.stringify(cell.frame)} ctxMaxWidth=${cell.contextMaxWidth}`,
+      );
+    }
+  }
+
+  if (failures.length > 0) {
+    for (const msg of failures) console.error('  ✗ ' + msg);
+    assert.fail(`${failures.length}/${CELLS.length} text-resize matrix cells failed`);
+  }
+
+  console.log(`text-resize-matrix-regression: PASS (${CELLS.length} cells)`);
+}
+
+try {
+  runRegression();
+} catch (err) {
+  console.error('text-resize-matrix-regression: FAIL');
+  console.error(err);
+  process.exit(1);
+}

package/scanner/transform-math-regression.ts

@@ -2,7 +2,7 @@ import assert from 'node:assert/strict';
 import {
   centerPlacedRotationTransform,
   rotationTransformAroundPointRadians,
-} from '../src/transform-math';
+} from '../src/tailwind/transform-math';
 
 function approxEqual(actual: number, expected: number, epsilon = 0.0001): void {
   assert.ok(Math.abs(actual - expected) <= epsilon, `expected ${expected}, got ${actual}`);

package/scanner/types.ts

@@ -41,13 +41,23 @@ export interface StoryInfo {
 }
 
 /**
- * A single component usage found in a story (flat extraction)
+ * A single component usage found in a story (flat extraction).
+ *
+ * `props` is a string map for ordinary attributes (`variant="default"`,
+ * `size="sm"`, `className="..."`) but the scanner also stuffs a special
+ * `__jsxChildren` key with a `JsxNode[]` payload when the component has
+ * structural children that need to be re-rendered (e.g. a `<DialogTrigger>`
+ * inside `<Dialog>`). Consumers either treat props as the string map or
+ * read `__jsxChildren` after a runtime `Array.isArray` check.
  */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- props mixes string attrs with __jsxChildren: JsxNode[]
+export type ComponentInstanceProps = Record<string, any>;
+
 export interface ComponentInstance {
   /** Component tag name (e.g., "Button", "Card") */
   componentName: string;
   /** Props on the component (e.g., { variant: "default", size: "sm" }) */
-  props: Record<string, any>;
+  props: ComponentInstanceProps;
   /** Text content children */
   children?: string;
 }
@@ -295,4 +305,18 @@ export interface EnrichedComponentAnalysis {
   responsive: ResponsiveInfo;
   /** Light/dark mode class split */
   colorScheme: ColorSchemeInfo;
+  /** Atomic design classification inferred from component graph + structure */
+  kind?: AtomicKind;
+  /** Number of unique components this component references in stories */
+  usesCount?: number;
+  /** Number of unique components that reference this component in stories */
+  usedByCount?: number;
+  /** True when this component references no other component */
+  isLeaf?: boolean;
+  /** Whether this component should be emitted as a reusable Figma symbol candidate */
+  symbolCandidate?: boolean;
+  /** Precomputed safe text override prop keys for non-CVA/non-compound symbol inference */
+  safeTextOverrideProps?: string[];
 }
+
+export type AtomicKind = 'atom' | 'molecule' | 'organism' | 'utility' | 'other';

package/src/cache/frame-cache.ts

@@ -0,0 +1,150 @@
+/**
+ * frame-cache.ts — Incremental re-render helpers
+ *
+ * ## Why this exists
+ * The Design System page used to be rebuilt from scratch on every plugin run:
+ * every node was deleted and recreated. This destroyed Figma node IDs, which
+ * meant any designer annotations, comments, or manual repositioning attached
+ * to component frames were lost.
+ *
+ * ## How it works
+ * Each component block frame stores a content hash in Figma plugin data
+ * (key: "inkbridge:hash"). On the next run we compare the stored hash against
+ * a freshly computed one. If they match, the frame is left completely untouched
+ * — its node ID, position, and any attached annotations survive. Only frames
+ * whose hash changed (or that are newly added) are removed and rebuilt.
+ *
+ * ## Hash strategy
+ * Two inputs are combined per component block:
+ *   defHash   — hash of the component definition (name, type, stories, classes)
+ *   tokenHash — hash of the global TOKENS object (covers all themes)
+ *
+ * blockHash = defHash + ":" + tokenHash
+ *
+ * If only tokens changed, all component blocks are rebuilt (they carry colour
+ * and radius information). If only one component's code changed, only that
+ * component's block is rebuilt. Everything else is preserved.
+ *
+ * ## Hash algorithm
+ * djb2 — simple, deterministic, no crypto API needed in the Figma sandbox.
+ * Output is a base-36 string (~7 chars), compact and alphanumeric.
+ *
+ * ## Plugin data key
+ * "inkbridge:hash" is written to every component block frame and to the
+ * Design Tokens row. No other Figma data is modified.
+ */
+
+const PLUGIN_HASH_KEY = 'inkbridge:hash';
+
+/**
+ * djb2 string hash. Works in Figma plugin sandbox (no crypto API required).
+ * Returns a base-36 string.
+ */
+export function hashString(s: string): string {
+  let h = 5381;
+  for (let i = 0; i < s.length; i++) {
+    h = (((h << 5) + h) ^ s.charCodeAt(i)) >>> 0;
+  }
+  return h.toString(36);
+}
+
+/**
+ * Stable JSON stringify with recursive key sorting.
+ * Prevents hash churn when equivalent objects are created with different key order.
+ */
+export function stableStringify(value: unknown): string {
+  if (value === null || value === undefined) return 'null';
+  const t = typeof value;
+  if (t === 'string' || t === 'number' || t === 'boolean') return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return '[' + value.map(stableStringify).join(',') + ']';
+  }
+  if (t === 'object') {
+    const obj = value as Record<string, unknown>;
+    const keys = Object.keys(obj).sort();
+    const parts: string[] = [];
+    for (let i = 0; i < keys.length; i++) {
+      const k = keys[i];
+      const v = obj[k];
+      if (typeof v === 'undefined') continue;
+      parts.push(JSON.stringify(k) + ':' + stableStringify(v));
+    }
+    return '{' + parts.join(',') + '}';
+  }
+  return JSON.stringify(String(value));
+}
+
+/**
+ * Compute a stable hash for a component definition.
+ *
+ * Only fields that affect rendering are included. Transient scanner metadata
+ * (generatedAt, schemaVersion, file path) is excluded so a re-scan that
+ * produces identical components does not trigger unnecessary rebuilds.
+ */
+export function hashDef(def: Record<string, unknown>): string {
+  const stable = {
+    name: def.name,
+    type: def.type,
+    stories: def.stories,
+    classes: def.classes,
+    baseClasses: def.baseClasses,
+    variants: def.variants,
+    states: def.states,
+    subComponents: def.subComponents,
+  };
+  // Use stableStringify so nested object key-order differences from scanner
+  // output do not trigger false-positive "changed" component hashes.
+  return hashString(stableStringify(stable));
+}
+
+/**
+ * Read the stored content hash from a Figma frame's plugin data.
+ * Returns null if no hash has been stored (e.g. frame was built before
+ * incremental re-render was introduced, or plugin data is unavailable).
+ */
+export function getFrameHash(frame: BaseNode): string | null {
+  try {
+    const v = frame.getPluginData(PLUGIN_HASH_KEY);
+    return v || null;
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * Store a content hash on a Figma frame via plugin data.
+ * Silently ignored if the node type does not support plugin data.
+ */
+export function setFrameHash(frame: BaseNode, hash: string): void {
+  try {
+    frame.setPluginData(PLUGIN_HASH_KEY, hash);
+  } catch (_e) {
+    // Some node types (e.g. text nodes) do not support plugin data — ignore.
+  }
+}
+
+/**
+ * Find the first direct child of `parent` whose `.name` matches `name`.
+ * Returns null if not found or if parent has no children.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function findChildByName(parent: any, name: string): any | null {
+  if (!parent || !parent.children) return null;
+  for (let i = 0; i < parent.children.length; i++) {
+    if (parent.children[i].name === name) return parent.children[i];
+  }
+  return null;
+}
+
+/**
+ * Find the index of the first direct child of `parent` whose `.name` matches
+ * `name`. Returns -1 if not found.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function findChildIndexByName(parent: any, name: string): number {
+  if (!parent || !parent.children) return -1;
+  for (let i = 0; i < parent.children.length; i++) {
+    if (parent.children[i].name === name) return i;
+  }
+  return -1;
+}

package/src/cache/index.ts

@@ -0,0 +1,2 @@
+export * from './frame-cache';
+export * from './image-cache';

package/src/{component-defs.ts → components/component-defs.ts}

@@ -1,12 +1,27 @@
-import { COMPONENT_DEFS } from './tokens';
+import { COMPONENT_DEFS } from '../tokens';
+import type {
+  ComponentAnalysis,
+  CVAComponentAnalysis,
+  CompoundComponentAnalysis,
+  EnrichedComponentAnalysis,
+  StateComponentAnalysis,
+  SubComponentInfo,
+} from '../../scanner/types';
 
 // --- Component Definition Helpers ---
 // These helpers let the plugin dynamically read from scanned component definitions
 
-export function getComponentDef(name: string): any | null {
+type RawEntry = EnrichedComponentAnalysis | ComponentAnalysis;
+
+function unwrap(raw: RawEntry): ComponentAnalysis {
+  return 'analysis' in raw ? raw.analysis : raw;
+}
+
+export function getComponentDef(name: string): ComponentAnalysis | null {
   if (!COMPONENT_DEFS || !COMPONENT_DEFS.components) return null;
-  for (const raw of COMPONENT_DEFS.components) {
-    const def = raw && raw.analysis ? raw.analysis : raw;
+  for (const raw of COMPONENT_DEFS.components as RawEntry[]) {
+    if (!raw) continue;
+    const def = unwrap(raw);
     if (def && def.name && def.name.toLowerCase() === name.toLowerCase()) {
       return def;
     }
@@ -14,7 +29,7 @@ export function getComponentDef(name: string): any | null {
   return null;
 }
 
-export function getCVAComponentVariants(name: string): any | null {
+export function getCVAComponentVariants(name: string): CVAComponentAnalysis['variants'] | null {
   const def = getComponentDef(name);
   if (!def || def.type !== 'cva') return null;
   return def.variants;
@@ -36,19 +51,19 @@ export function getCVAComponentClasses(name: string, variantName?: string, varia
 export function getStateComponentStates(name: string): string[] | null {
   const def = getComponentDef(name);
   if (!def || def.type !== 'state') return null;
-  return Object.keys(def.states);
+  return Object.keys((def as StateComponentAnalysis).states);
 }
 
-export function getCompoundSubComponents(name: string): any[] | null {
+export function getCompoundSubComponents(name: string): SubComponentInfo[] | null {
   const def = getComponentDef(name);
   if (!def || def.type !== 'compound') return null;
-  return def.subComponents;
+  return (def as CompoundComponentAnalysis).subComponents;
 }
 
 export function listAllComponents(): { name: string; type: string }[] {
   if (!COMPONENT_DEFS || !COMPONENT_DEFS.components) return [];
-  return COMPONENT_DEFS.components.map((raw: any) => {
-    const def = raw && raw.analysis ? raw.analysis : raw;
+  return (COMPONENT_DEFS.components as RawEntry[]).map((raw) => {
+    const def = unwrap(raw);
     return { name: def?.name, type: def?.type };
   });
 }