@sarjallab09/figma-intelligence 1.0.0

package/figma-intelligence-layer/src/tools/phase2-accuracy/variant-expander/index.ts

@@ -0,0 +1,429 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// Variant Expander
+// Generates a full set of component variants by taking a cartesian product of
+// the requested dimension values, cloning the base component for each
+// combination, applying per-dimension token overrides, and grouping everything
+// into a Figma Component Set.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import { getBridge } from "../../../shared/figma-bridge.js";
+import { decisionLog } from "../../../shared/decision-log.js";
+import { FontConfig, resolveFontConfig, generateFontLoadScript } from "../../../shared/font-config.js";
+import { DIMENSION_OVERRIDES } from "./token-override-maps.js";
+
+// ─── Public types ─────────────────────────────────────────────────────────────
+
+export interface VariantDimensions {
+  state?: string[];  // e.g. ["default","hover","pressed","disabled","loading"]
+  size?: string[];
+  theme?: string[];
+  type?: string[];
+}
+
+export interface VariantExpanderArgs {
+  nodeId: string;
+  dimensions: VariantDimensions;
+  namingConvention: "figma" | "storybook";
+  autoApplyTokens: boolean;
+  arrangeInGrid?: boolean;
+  fonts?: Partial<FontConfig>;
+}
+
+export interface VariantCombination {
+  key: string;                          // rendered name
+  props: Record<string, string>;        // e.g. { state: "hover", size: "md" }
+  clonedNodeId?: string;
+  tokenOverrides: TokenOverride[];
+}
+
+export interface TokenOverride {
+  property: string;
+  value: string | number;
+  description: string;
+}
+
+export interface CoverageReport {
+  totalCombinations: number;
+  created: number;
+  failed: number;
+  componentSetId: string | null;
+  combinations: VariantCombination[];
+  logEntryId: string;
+}
+
+// ─── Naming helpers ───────────────────────────────────────────────────────────
+
+function toFigmaName(props: Record<string, string>): string {
+  // Figma convention: "Property=Value, Property2=Value2"
+  return Object.entries(props)
+    .map(([k, v]) => `${capitalize(k)}=${capitalize(v)}`)
+    .join(", ");
+}
+
+function toStorybookName(props: Record<string, string>): string {
+  // Storybook convention: "componentName--size-state-theme-type"
+  return Object.values(props)
+    .map((v) => v.toLowerCase().replace(/\s+/g, "-"))
+    .join("--");
+}
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+// ─── Cartesian product ────────────────────────────────────────────────────────
+
+function cartesian(dimensions: VariantDimensions): Array<Record<string, string>> {
+  const entries = Object.entries(dimensions).filter(
+    ([, values]) => values && values.length > 0
+  ) as Array<[string, string[]]>;
+
+  if (entries.length === 0) return [{}];
+
+  return entries.reduce<Array<Record<string, string>>>(
+    (acc, [key, values]) => {
+      const expanded: Array<Record<string, string>> = [];
+      for (const existing of acc) {
+        for (const value of values) {
+          expanded.push({ ...existing, [key]: value });
+        }
+      }
+      return expanded;
+    },
+    [{}]
+  );
+}
+
+// ─── Per-dimension token overrides ───────────────────────────────────────────
+
+/**
+ * Resolve token overrides from the unified DIMENSION_OVERRIDES maps.
+ * This replaces the previous inline logic with a single source of truth.
+ */
+function resolveTokenOverrides(props: Record<string, string>): TokenOverride[] {
+  const overrides: TokenOverride[] = [];
+
+  for (const [dimension, dimValue] of Object.entries(props)) {
+    const dimKey = dimension.toLowerCase() as keyof typeof DIMENSION_OVERRIDES;
+    const overrideMap = DIMENSION_OVERRIDES[dimKey];
+    if (!overrideMap) continue;
+
+    const valueKey = dimValue.toLowerCase();
+    const mapOverrides = overrideMap[valueKey];
+    if (!mapOverrides) continue;
+
+    for (const mo of mapOverrides) {
+      // Convert override map entries to the TokenOverride format used by the expander
+      if (mo.property === "background") {
+        overrides.push({
+          property: "fills[0]",
+          value: mo.token,
+          description: `${dimension}:${dimValue} — background: ${mo.token}`,
+        });
+      } else if (mo.property === "textColor") {
+        overrides.push({
+          property: "textFill",
+          value: mo.token,
+          description: `${dimension}:${dimValue} — text color: ${mo.token}`,
+        });
+      } else if (mo.property === "borderColor") {
+        overrides.push({
+          property: "strokes[0]",
+          value: mo.token,
+          description: `${dimension}:${dimValue} — border: ${mo.token}`,
+        });
+      } else if (mo.property === "opacity") {
+        overrides.push({
+          property: "opacity",
+          value: mo.rawValue ?? 1,
+          description: `${dimension}:${dimValue} — opacity: ${mo.rawValue}`,
+        });
+      } else if (mo.property === "fontSize") {
+        overrides.push({
+          property: "style.fontSize",
+          value: mo.rawValue ?? 16,
+          description: `${dimension}:${dimValue} — fontSize: ${mo.rawValue}px`,
+        });
+      } else if (mo.property === "paddingX") {
+        overrides.push(
+          { property: "paddingLeft", value: mo.rawValue ?? 16, description: `${dimension}:${dimValue} — paddingX: ${mo.rawValue}px` },
+          { property: "paddingRight", value: mo.rawValue ?? 16, description: `${dimension}:${dimValue} — paddingX: ${mo.rawValue}px` }
+        );
+      } else if (mo.property === "paddingY") {
+        overrides.push(
+          { property: "paddingTop", value: mo.rawValue ?? 8, description: `${dimension}:${dimValue} — paddingY: ${mo.rawValue}px` },
+          { property: "paddingBottom", value: mo.rawValue ?? 8, description: `${dimension}:${dimValue} — paddingY: ${mo.rawValue}px` }
+        );
+      } else if (mo.property === "height") {
+        overrides.push({
+          property: "height",
+          value: mo.rawValue ?? 40,
+          description: `${dimension}:${dimValue} — height: ${mo.rawValue}px`,
+        });
+      } else if (mo.property === "borderWidth") {
+        overrides.push({
+          property: "strokeWeight",
+          value: mo.rawValue ?? 1,
+          description: `${dimension}:${dimValue} — borderWidth: ${mo.rawValue}`,
+        });
+      } else if (mo.property === "text") {
+        overrides.push({
+          property: "characters",
+          value: mo.rawValue ?? "",
+          description: `${dimension}:${dimValue} — text: ${mo.rawValue}`,
+        });
+      }
+    }
+  }
+
+  return overrides;
+}
+
+// ─── Figma script builders ────────────────────────────────────────────────────
+
+function buildCloneScript(
+  baseNodeId: string,
+  variantName: string,
+  overrides: TokenOverride[]
+): string {
+  const overrideLines: string[] = [];
+
+  for (const o of overrides) {
+    if (o.property === "opacity") {
+      overrideLines.push(`  clone.opacity = ${o.value};`);
+    } else if (o.property === "characters") {
+      overrideLines.push(
+        `  const textNodes = clone.findAll ? clone.findAll(n => n.type === 'TEXT') : [];`,
+        `  for (const t of textNodes) { t.characters = ${JSON.stringify(o.value)}; }`
+      );
+    } else if (o.property.startsWith("padding")) {
+      const field = o.property; // e.g. "paddingLeft"
+      overrideLines.push(`  if ('${field}' in clone) clone.${field} = ${o.value};`);
+    } else if (o.property === "variableMode") {
+      // Dark mode is set on the collection; we record it as a variant property here
+      overrideLines.push(`  /* variableMode:${o.value} — handled by component set variant */`);
+    }
+    // fills and style overrides require variable binding; we annotate for now
+  }
+
+  const overrideBlock = overrideLines.join("\n") || "  /* no overrides */";
+
+  return `
+    (async () => {
+      const base = await figma.getNodeByIdAsync(${JSON.stringify(baseNodeId)});
+      if (!base) throw new Error('Base node not found: ${baseNodeId}');
+      const clone = base.clone();
+      clone.name = ${JSON.stringify(variantName)};
+      ${overrideBlock}
+      // Place clone next to base temporarily
+      base.parent.appendChild(clone);
+      return clone.id;
+    })()
+  `.trim();
+}
+
+function buildComponentSetScript(componentIds: string[]): string {
+  return `
+    (async () => {
+      const components = [];
+      for (const id of ${JSON.stringify(componentIds)}) {
+        const n = await figma.getNodeByIdAsync(id);
+        if (n) components.push(n);
+      }
+      if (components.length === 0) throw new Error('No components found to group');
+      const set = figma.combineAsVariants(components, figma.currentPage);
+      return set.id;
+    })()
+  `.trim();
+}
+
+function buildGridArrangeScript(componentSetId: string, columnCount: number): string {
+  const COL_WIDTH = 200;
+  const ROW_HEIGHT = 150;
+  const GAP = 24;
+
+  return `
+    (async () => {
+      const set = await figma.getNodeByIdAsync(${JSON.stringify(componentSetId)});
+      if (!set || !set.children) throw new Error('Component set not found');
+      const children = [...set.children];
+      children.forEach((child, i) => {
+        const col = i % ${columnCount};
+        const row = Math.floor(i / ${columnCount});
+        child.x = col * (${COL_WIDTH} + ${GAP});
+        child.y = row * (${ROW_HEIGHT} + ${GAP});
+      });
+      return { arranged: children.length };
+    })()
+  `.trim();
+}
+
+// ─── Main handler ─────────────────────────────────────────────────────────────
+
+export async function variantExpanderHandler(
+  args: VariantExpanderArgs
+): Promise<CoverageReport> {
+  const {
+    nodeId,
+    dimensions,
+    namingConvention,
+    autoApplyTokens,
+    arrangeInGrid = false,
+  } = args;
+
+  if (!nodeId) throw new Error("variantExpander: `nodeId` is required.");
+
+  const bridge = await getBridge();
+
+  // 1. Verify the base component node exists
+  const baseNode = await bridge.getNode(nodeId);
+  if (!baseNode) throw new Error(`variantExpander: Node "${nodeId}" not found.`);
+
+  // 2. Generate all combinations
+  const combinations: VariantCombination[] = cartesian(dimensions).map((props) => {
+    const key =
+      namingConvention === "figma"
+        ? toFigmaName(props)
+        : toStorybookName(props);
+
+    const tokenOverrides = autoApplyTokens ? resolveTokenOverrides(props) : [];
+
+    return { key, props, tokenOverrides };
+  });
+
+  if (combinations.length === 0) {
+    throw new Error("variantExpander: No combinations generated. Check `dimensions` input.");
+  }
+
+  // 3. Clone and apply overrides for each combination (batched in a single execute)
+  let created = 0;
+  let failed = 0;
+  const clonedIds: string[] = [];
+
+  // Build a single script that creates ALL clones at once
+  const BATCH_SIZE = 25;
+  for (let batchStart = 0; batchStart < combinations.length; batchStart += BATCH_SIZE) {
+    const batch = combinations.slice(batchStart, batchStart + BATCH_SIZE);
+    const cloneLines: string[] = [];
+    for (const combo of batch) {
+      const overrideLines: string[] = [];
+      for (const o of combo.tokenOverrides) {
+        if (o.property === "opacity") {
+          overrideLines.push(`clone.opacity = ${o.value};`);
+        } else if (o.property === "characters") {
+          overrideLines.push(`var textNodes = clone.findAll(function(n) { return n.type === 'TEXT'; }); for (var ti = 0; ti < textNodes.length; ti++) { textNodes[ti].characters = ${JSON.stringify(o.value)}; }`);
+        } else if (o.property.startsWith("padding") || o.property === "strokeWeight") {
+          overrideLines.push(`if ('${o.property}' in clone) clone.${o.property} = ${o.value};`);
+        } else if (o.property === "height") {
+          overrideLines.push(`try { clone.resize(clone.width, ${o.value}); } catch(e) {}`);
+        } else if (o.property === "style.fontSize") {
+          overrideLines.push(`var textNodes = clone.findAll(function(n) { return n.type === 'TEXT'; }); for (var ti = 0; ti < textNodes.length; ti++) { textNodes[ti].fontSize = ${o.value}; }`);
+        }
+      }
+      cloneLines.push(`
+        try {
+          var clone = base.clone();
+          clone.name = ${JSON.stringify(combo.key)};
+          ${overrideLines.join("\n          ")}
+          base.parent.appendChild(clone);
+          ids.push(clone.id);
+        } catch(e) { errors++; }
+      `);
+    }
+
+    const fontConfig = resolveFontConfig(args.fonts);
+    const fontLoads = generateFontLoadScript(fontConfig);
+
+    const batchScript = `
+      (async () => {
+        ${fontLoads}
+        var base = await figma.getNodeByIdAsync(${JSON.stringify(nodeId)});
+        if (!base) throw new Error('Base node not found');
+        var ids = [];
+        var errors = 0;
+        ${cloneLines.join("\n")}
+        return { ids: ids, errors: errors };
+      })()
+    `.trim();
+
+    try {
+      const batchResult = await bridge.execute(batchScript);
+      if (batchResult.success && batchResult.result) {
+        const { ids, errors } = batchResult.result as { ids: string[]; errors: number };
+        clonedIds.push(...ids);
+        created += ids.length;
+        failed += errors;
+        // Assign clonedNodeId back to each combo
+        for (let i = 0; i < batch.length && i < ids.length; i++) {
+          batch[i].clonedNodeId = ids[i];
+        }
+      } else {
+        failed += batch.length;
+      }
+    } catch {
+      failed += batch.length;
+    }
+  }
+
+  // 4. Group into a Component Set
+  let componentSetId: string | null = null;
+
+  if (clonedIds.length > 0) {
+    try {
+      const setScript = buildComponentSetScript(clonedIds);
+      const setResult = await bridge.execute(setScript);
+
+      if (setResult.success && setResult.result) {
+        componentSetId = setResult.result as string;
+      } else {
+        console.error(`variantExpander: combineAsVariants failed: ${setResult.error}`);
+      }
+    } catch (err) {
+      console.error("variantExpander: Exception creating component set:", err);
+    }
+  }
+
+  // 5. Arrange in grid if requested
+  if (arrangeInGrid && componentSetId) {
+    try {
+      // Determine a sensible column count (square-ish grid)
+      const cols = Math.ceil(Math.sqrt(clonedIds.length));
+      const gridScript = buildGridArrangeScript(componentSetId, cols);
+      await bridge.execute(gridScript);
+    } catch (err) {
+      console.error("variantExpander: Grid arrangement failed:", err);
+    }
+  }
+
+  // 6. Log the decision
+  const allTokenNames = combinations
+    .flatMap((c) => c.tokenOverrides.map((o) => o.property))
+    .filter((v, i, arr) => arr.indexOf(v) === i);
+
+  const logEntry = await decisionLog.log({
+    tool: "variant-expander",
+    nodeIds: [nodeId, ...(componentSetId ? [componentSetId] : [])],
+    rationale: `Expanded "${baseNode.name}" into ${combinations.length} variants (${Object.keys(dimensions).join(", ")}). Created ${created}, failed ${failed}. ComponentSet: ${componentSetId ?? "none"}.`,
+    tokens: allTokenNames,
+    reversible: true,
+    metadata: {
+      baseNodeId: nodeId,
+      namingConvention,
+      autoApplyTokens,
+      arrangeInGrid,
+      totalCombinations: combinations.length,
+      created,
+      failed,
+      componentSetId,
+    },
+  });
+
+  return {
+    totalCombinations: combinations.length,
+    created,
+    failed,
+    componentSetId,
+    combinations,
+    logEntryId: logEntry.id,
+  };
+}

package/figma-intelligence-layer/src/tools/phase2-accuracy/variant-expander/token-override-maps.ts

@@ -0,0 +1,226 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// Token Override Maps
+// Defines how token values change across variant dimensions (state, size,
+// theme, type).  Used by the variant-expander to apply token overrides
+// when generating variant matrices.
+//
+// Heights on 8px grid: xs(24h), sm(32h), md(40h), lg(48h), xl(56h)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface TokenOverride {
+  property: string;     // e.g. "background", "opacity", "fontSize"
+  token: string;        // design token name
+  rawValue?: string | number;
+}
+
+export type OverrideMap = Record<string, TokenOverride[]>;
+
+/**
+ * State dimension overrides.
+ */
+export const STATE_OVERRIDES: OverrideMap = {
+  default: [],
+  hover: [
+    { property: "background", token: "color/semantic/actions/primary/bg/hover" },
+  ],
+  pressed: [
+    { property: "background", token: "color/semantic/actions/primary/bg/pressed" },
+  ],
+  focused: [
+    { property: "borderColor", token: "color/semantic/border/focus" },
+    { property: "borderWidth", token: "border/width/strong", rawValue: 2 },
+  ],
+  disabled: [
+    { property: "opacity", token: "opacity/disabled", rawValue: 0.4 },
+  ],
+  loading: [
+    { property: "icon", token: "Spinner" },
+    { property: "text", token: "", rawValue: "Loading…" },
+  ],
+  error: [
+    { property: "borderColor", token: "color/semantic/feedback/danger/text" },
+    { property: "background", token: "color/semantic/feedback/danger/bg" },
+  ],
+  success: [
+    { property: "borderColor", token: "color/semantic/feedback/success/text" },
+    { property: "background", token: "color/semantic/feedback/success/bg" },
+  ],
+  warning: [
+    { property: "borderColor", token: "color/semantic/feedback/warning/text" },
+    { property: "background", token: "color/semantic/feedback/warning/bg" },
+  ],
+  active: [
+    { property: "background", token: "color/semantic/actions/primary/bg/pressed" },
+    { property: "borderColor", token: "color/semantic/border/focus" },
+  ],
+};
+
+/**
+ * Size dimension overrides.
+ * All heights on 8px grid: xs=24, sm=32, md=40, lg=48, xl=56
+ */
+export const SIZE_OVERRIDES: OverrideMap = {
+  xs: [
+    { property: "paddingY", token: "space/0.5", rawValue: 2 },
+    { property: "paddingX", token: "space/1", rawValue: 4 },
+    { property: "fontSize", token: "typography/size/xs", rawValue: 12 },
+    { property: "height", token: "", rawValue: 24 },
+  ],
+  sm: [
+    { property: "paddingY", token: "space/1", rawValue: 4 },
+    { property: "paddingX", token: "space/2", rawValue: 8 },
+    { property: "fontSize", token: "typography/size/sm", rawValue: 14 },
+    { property: "height", token: "", rawValue: 32 },
+  ],
+  md: [
+    { property: "paddingY", token: "space/2", rawValue: 8 },
+    { property: "paddingX", token: "space/4", rawValue: 16 },
+    { property: "fontSize", token: "typography/size/md", rawValue: 16 },
+    { property: "height", token: "", rawValue: 40 },
+  ],
+  lg: [
+    { property: "paddingY", token: "space/4", rawValue: 16 },
+    { property: "paddingX", token: "space/6", rawValue: 24 },
+    { property: "fontSize", token: "typography/size/lg", rawValue: 18 },
+    { property: "height", token: "", rawValue: 48 },
+  ],
+  xl: [
+    { property: "paddingY", token: "space/6", rawValue: 24 },
+    { property: "paddingX", token: "space/8", rawValue: 32 },
+    { property: "fontSize", token: "typography/size/xl", rawValue: 20 },
+    { property: "height", token: "", rawValue: 56 },
+  ],
+};
+
+/**
+ * Theme dimension overrides.
+ */
+export const THEME_OVERRIDES: OverrideMap = {
+  light: [],
+  dark: [
+    { property: "background", token: "color/semantic/surface/default" },
+    { property: "textColor", token: "color/semantic/text/primary" },
+    { property: "borderColor", token: "color/semantic/border/default" },
+  ],
+  "high-contrast": [
+    { property: "background", token: "color/semantic/surface/default" },
+    { property: "textColor", token: "color/semantic/text/primary" },
+    { property: "borderColor", token: "color/semantic/border/strong" },
+  ],
+};
+
+/**
+ * Type / variant-purpose dimension overrides.
+ */
+export const TYPE_OVERRIDES: OverrideMap = {
+  primary: [
+    { property: "background", token: "color/semantic/actions/primary/bg/default" },
+    { property: "textColor", token: "color/semantic/text/on-color" },
+  ],
+  secondary: [
+    { property: "background", token: "color/semantic/actions/secondary/bg/default" },
+    { property: "textColor", token: "color/semantic/text/primary" },
+    { property: "borderColor", token: "color/semantic/actions/secondary/border/default" },
+  ],
+  ghost: [
+    { property: "background", token: "transparent" },
+    { property: "textColor", token: "color/semantic/actions/primary/bg/default" },
+  ],
+  destructive: [
+    { property: "background", token: "color/semantic/actions/destructive/bg/default" },
+    { property: "textColor", token: "color/semantic/text/on-color" },
+  ],
+  outline: [
+    { property: "background", token: "transparent" },
+    { property: "textColor", token: "color/semantic/actions/primary/bg/default" },
+    { property: "borderColor", token: "color/semantic/actions/primary/bg/default" },
+    { property: "borderWidth", token: "border/width/default", rawValue: 1.5 },
+  ],
+  link: [
+    { property: "background", token: "transparent" },
+    { property: "textColor", token: "color/semantic/actions/primary/bg/default" },
+    { property: "textDecoration", token: "", rawValue: "underline" },
+  ],
+};
+
+// ─── Concept-Aware State Overrides ──────────────────────────────────────────
+// When the concept taxonomy provides additional state context, use these
+// concept-specific overrides instead of the generic STATE_OVERRIDES.
+
+import { getConceptForComponent, type ConceptDefinition } from "../../../shared/concept-taxonomy.js";
+
+/**
+ * Concept-specific state overrides that supplement the generic STATE_OVERRIDES.
+ * Keys are concept IDs, values are state → overrides maps.
+ */
+const CONCEPT_STATE_OVERRIDES: Record<string, OverrideMap> = {
+  navigation: {
+    visited: [
+      { property: "textColor", token: "color/semantic/text/secondary" },
+    ],
+    active: [
+      { property: "background", token: "color/semantic/actions/primary/bg/default" },
+      { property: "textColor", token: "color/semantic/text/on-color" },
+      { property: "borderColor", token: "color/semantic/border/focus" },
+    ],
+  },
+  field: {
+    error: [
+      { property: "borderColor", token: "color/semantic/feedback/danger/text" },
+      { property: "background", token: "color/semantic/field/bg/default" },
+      { property: "helperColor", token: "color/semantic/feedback/danger/text" },
+    ],
+    success: [
+      { property: "borderColor", token: "color/semantic/feedback/success/text" },
+      { property: "background", token: "color/semantic/field/bg/default" },
+    ],
+  },
+  selection: {
+    checked: [
+      { property: "background", token: "color/semantic/actions/primary/bg/default" },
+      { property: "iconColor", token: "color/semantic/text/on-color" },
+    ],
+    indeterminate: [
+      { property: "background", token: "color/semantic/actions/primary/bg/default" },
+      { property: "iconColor", token: "color/semantic/text/on-color" },
+    ],
+  },
+  toggles: {
+    on: [
+      { property: "background", token: "color/semantic/actions/primary/bg/default" },
+    ],
+    off: [
+      { property: "background", token: "color/semantic/surface/subtle" },
+    ],
+  },
+};
+
+/**
+ * Get state overrides for a component, merging concept-specific overrides
+ * with the generic STATE_OVERRIDES. Concept overrides take priority.
+ */
+export function getStateOverridesForComponent(
+  componentType: string,
+  stateName: string,
+): TokenOverride[] {
+  const concept = getConceptForComponent(componentType);
+
+  // Check concept-specific overrides first
+  if (concept) {
+    const conceptOverrides = CONCEPT_STATE_OVERRIDES[concept.id];
+    if (conceptOverrides?.[stateName]) {
+      return conceptOverrides[stateName];
+    }
+  }
+
+  // Fall back to generic state overrides
+  return STATE_OVERRIDES[stateName] ?? [];
+}
+
+/** All dimension maps for convenient iteration. */
+export const DIMENSION_OVERRIDES = {
+  state: STATE_OVERRIDES,
+  size: SIZE_OVERRIDES,
+  theme: THEME_OVERRIDES,
+  type: TYPE_OVERRIDES,
+} as const;