@sarjallab09/figma-intelligence 1.0.0

package/figma-intelligence-layer/src/tools/phase3-generation/composition-builder/index.ts

@@ -0,0 +1,540 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// figma_composition_builder — Compose multi-component patterns
+//
+// Builds composed UI patterns from natural language:
+//   - "Login form" → Modal + 2 Inputs + Button + Link, wired with layout/tokens
+//   - "Data table with filters" → Table + Search + Select + Pagination
+//   - "Card with actions" → Card + Image + Text + Button Group
+//
+// Uses the component template catalog + design system tokens to wire up
+// proper Auto Layout, spacing, and token bindings between components.
+// Outputs a single frame containing all composed children.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import { getBridge } from "../../../shared/figma-bridge.js";
+import { COMPONENT_BLUEPRINTS, ComponentBlueprint } from "../../../shared/component-templates.js";
+import { SEMANTIC_TOKEN_CATALOG } from "../../../shared/semantic-token-catalog.js";
+import { resolveDesignPalette, ResolvedPalette } from "../../../shared/token-binder.js";
+import { getDesignSystemFontFamily } from "../../../shared/design-system-tokens.js";
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface CompositionBuilderArgs {
+  /** Natural language description of the pattern to build */
+  pattern: string;
+  /** Explicit list of components to compose (overrides AI pattern matching) */
+  components?: Array<{
+    name: string;
+    props?: Record<string, string>;
+    count?: number;
+  }>;
+  /** Target frame width (default 400) */
+  frameWidth?: number;
+  /** Layout direction (default auto-detected from pattern) */
+  layoutDirection?: "VERTICAL" | "HORIZONTAL";
+  /** Spacing between components in px (default: from DS tokens or 16) */
+  spacing?: number;
+  /** Padding inside the container frame (default: 24) */
+  padding?: number;
+  /** Include a background fill */
+  includeBackground?: boolean;
+  /** Place result on a specific Figma page */
+  targetPage?: string;
+}
+
+interface CompositionPlan {
+  name: string;
+  description: string;
+  direction: "VERTICAL" | "HORIZONTAL";
+  spacing: number;
+  padding: number;
+  width: number;
+  children: Array<{
+    blueprint: ComponentBlueprint;
+    label: string;
+    variant?: Record<string, string>;
+    count: number;
+    customText?: string;
+  }>;
+  wrapperStyle?: {
+    cornerRadius?: number;
+    fill?: string;
+    stroke?: string;
+    shadow?: boolean;
+  };
+}
+
+// ─── Pattern Recognition ──────────────────────────────────────────────────
+
+const PATTERN_RECIPES: Array<{
+  keywords: RegExp;
+  name: string;
+  description: string;
+  direction: "VERTICAL" | "HORIZONTAL";
+  components: Array<{ name: string; label: string; variant?: Record<string, string>; count?: number; text?: string }>;
+  wrapper?: CompositionPlan["wrapperStyle"];
+}> = [
+  {
+    keywords: /login\s*form|sign\s*in|auth/i,
+    name: "Login Form",
+    description: "Email/password login form with submit button",
+    direction: "VERTICAL",
+    components: [
+      { name: "Input", label: "Email Input", variant: { Type: "Default" }, text: "Email address" },
+      { name: "Input", label: "Password Input", variant: { Type: "Default" }, text: "Password" },
+      { name: "Button", label: "Submit Button", variant: { Type: "Primary", Size: "lg" }, text: "Sign In" },
+      { name: "Link", label: "Forgot Password", text: "Forgot password?" },
+    ],
+    wrapper: { cornerRadius: 12, fill: "color/surface/default", shadow: true },
+  },
+  {
+    keywords: /sign\s*up|register|create\s*account/i,
+    name: "Registration Form",
+    description: "Account registration form with name, email, password fields",
+    direction: "VERTICAL",
+    components: [
+      { name: "Input", label: "Name Input", text: "Full name" },
+      { name: "Input", label: "Email Input", text: "Email address" },
+      { name: "Input", label: "Password Input", text: "Password" },
+      { name: "Input", label: "Confirm Password Input", text: "Confirm password" },
+      { name: "Checkbox", label: "Terms Checkbox", text: "I agree to the Terms of Service" },
+      { name: "Button", label: "Register Button", variant: { Type: "Primary", Size: "lg" }, text: "Create Account" },
+    ],
+    wrapper: { cornerRadius: 12, fill: "color/surface/default", shadow: true },
+  },
+  {
+    keywords: /search\s*bar|search\s*(?:with|and)\s*filter|filter\s*bar/i,
+    name: "Search with Filters",
+    description: "Search input with filter controls",
+    direction: "HORIZONTAL",
+    components: [
+      { name: "Input", label: "Search Input", variant: { Type: "Default" }, text: "Search..." },
+      { name: "Select", label: "Category Filter", text: "All categories" },
+      { name: "Button", label: "Search Button", variant: { Type: "Primary" }, text: "Search" },
+    ],
+  },
+  {
+    keywords: /card\s*(?:with|and)\s*action|action\s*card|product\s*card/i,
+    name: "Card with Actions",
+    description: "Content card with image, text, and action buttons",
+    direction: "VERTICAL",
+    components: [
+      { name: "Card", label: "Card Container" },
+      { name: "Badge", label: "Status Badge", text: "New" },
+      { name: "Button", label: "Primary Action", variant: { Type: "Primary" }, text: "View Details" },
+      { name: "Button", label: "Secondary Action", variant: { Type: "Secondary" }, text: "Save" },
+    ],
+    wrapper: { cornerRadius: 8, stroke: "color/border/default", shadow: true },
+  },
+  {
+    keywords: /nav\s*bar|navigation\s*bar|header|top\s*bar|app\s*bar/i,
+    name: "Navigation Bar",
+    description: "Top navigation with logo, links, and user actions",
+    direction: "HORIZONTAL",
+    components: [
+      { name: "Badge", label: "Logo", text: "Logo" },
+      { name: "Link", label: "Nav Link 1", text: "Home" },
+      { name: "Link", label: "Nav Link 2", text: "Products" },
+      { name: "Link", label: "Nav Link 3", text: "About" },
+      { name: "Input", label: "Search", text: "Search..." },
+      { name: "Avatar", label: "User Avatar" },
+    ],
+  },
+  {
+    keywords: /modal|dialog|popup\s*(?:with|and)\s*form/i,
+    name: "Modal Dialog",
+    description: "Modal with header, form content, and action buttons",
+    direction: "VERTICAL",
+    components: [
+      { name: "Input", label: "Form Field 1", text: "Name" },
+      { name: "Input", label: "Form Field 2", text: "Description" },
+      { name: "Textarea", label: "Long Text Field", text: "Additional details..." },
+      { name: "Button", label: "Cancel", variant: { Type: "Secondary" }, text: "Cancel" },
+      { name: "Button", label: "Submit", variant: { Type: "Primary" }, text: "Save" },
+    ],
+    wrapper: { cornerRadius: 12, fill: "color/surface/default", shadow: true },
+  },
+  {
+    keywords: /settings|preferences|config/i,
+    name: "Settings Panel",
+    description: "Settings panel with toggles and inputs",
+    direction: "VERTICAL",
+    components: [
+      { name: "Toggle", label: "Notifications Toggle", text: "Enable notifications" },
+      { name: "Toggle", label: "Dark Mode Toggle", text: "Dark mode" },
+      { name: "Select", label: "Language Select", text: "English" },
+      { name: "Input", label: "Display Name", text: "Display name" },
+      { name: "Button", label: "Save Settings", variant: { Type: "Primary" }, text: "Save Changes" },
+    ],
+  },
+  {
+    keywords: /empty\s*state|no\s*(?:data|results|items)|zero\s*state/i,
+    name: "Empty State",
+    description: "Empty state with illustration placeholder and CTA",
+    direction: "VERTICAL",
+    components: [
+      { name: "Badge", label: "Icon Placeholder", text: "📭" },
+      { name: "Badge", label: "Title", text: "No results found" },
+      { name: "Badge", label: "Description", text: "Try adjusting your search or filters" },
+      { name: "Button", label: "CTA Button", variant: { Type: "Primary" }, text: "Clear Filters" },
+    ],
+  },
+  {
+    keywords: /pagination|page\s*nav|pager/i,
+    name: "Pagination Bar",
+    description: "Page navigation with prev/next and page numbers",
+    direction: "HORIZONTAL",
+    components: [
+      { name: "Button", label: "Previous", variant: { Type: "Secondary", Size: "sm" }, text: "← Previous" },
+      { name: "Badge", label: "Page 1", text: "1" },
+      { name: "Badge", label: "Page 2", text: "2" },
+      { name: "Badge", label: "Page 3", text: "3" },
+      { name: "Button", label: "Next", variant: { Type: "Secondary", Size: "sm" }, text: "Next →" },
+    ],
+  },
+  {
+    keywords: /toolbar|action\s*bar|button\s*group|button\s*bar/i,
+    name: "Toolbar",
+    description: "Horizontal toolbar with grouped actions",
+    direction: "HORIZONTAL",
+    components: [
+      { name: "Button", label: "Action 1", variant: { Type: "Secondary", Size: "sm" }, text: "Edit" },
+      { name: "Button", label: "Action 2", variant: { Type: "Secondary", Size: "sm" }, text: "Duplicate" },
+      { name: "Button", label: "Action 3", variant: { Type: "Secondary", Size: "sm" }, text: "Delete" },
+      { name: "Button", label: "Primary Action", variant: { Type: "Primary", Size: "sm" }, text: "Publish" },
+    ],
+  },
+  {
+    keywords: /footer|page\s*footer/i,
+    name: "Footer",
+    description: "Page footer with links and copyright",
+    direction: "HORIZONTAL",
+    components: [
+      { name: "Link", label: "Link 1", text: "Privacy Policy" },
+      { name: "Link", label: "Link 2", text: "Terms of Service" },
+      { name: "Link", label: "Link 3", text: "Contact Us" },
+      { name: "Badge", label: "Copyright", text: "© 2024 Company" },
+    ],
+  },
+  {
+    keywords: /notification|toast|alert\s*banner|announcement/i,
+    name: "Notification Banner",
+    description: "Dismissible notification with icon, message, and close button",
+    direction: "HORIZONTAL",
+    components: [
+      { name: "Badge", label: "Icon", text: "ℹ️" },
+      { name: "Badge", label: "Message", text: "Your changes have been saved successfully." },
+      { name: "Button", label: "Dismiss", variant: { Type: "Ghost", Size: "sm" }, text: "✕" },
+    ],
+    wrapper: { cornerRadius: 8, fill: "color/surface/info" },
+  },
+];
+
+function matchPattern(patternText: string): typeof PATTERN_RECIPES[number] | null {
+  for (const recipe of PATTERN_RECIPES) {
+    if (recipe.keywords.test(patternText)) {
+      return recipe;
+    }
+  }
+  return null;
+}
+
+// ─── Plan builder ──────────────────────────────────────────────────────────
+
+function buildPlan(args: CompositionBuilderArgs): CompositionPlan {
+  const width = args.frameWidth ?? 400;
+  const spacing = args.spacing ?? 16;
+  const padding = args.padding ?? 24;
+
+  // Explicit component list
+  if (args.components?.length) {
+    const children = args.components.map((comp) => {
+      const blueprint = COMPONENT_BLUEPRINTS.find(
+        (b) => b.name.toLowerCase() === comp.name.toLowerCase()
+      );
+      if (!blueprint) {
+        // Fall back to a generic frame blueprint
+        return {
+          blueprint: COMPONENT_BLUEPRINTS.find((b) => b.name === "Button")!, // fallback
+          label: comp.name,
+          variant: comp.props,
+          count: comp.count ?? 1,
+          customText: comp.name,
+        };
+      }
+      return {
+        blueprint,
+        label: comp.name,
+        variant: comp.props,
+        count: comp.count ?? 1,
+      };
+    });
+
+    return {
+      name: "Custom Composition",
+      description: `Custom composition: ${args.components.map((c) => c.name).join(" + ")}`,
+      direction: args.layoutDirection ?? "VERTICAL",
+      spacing,
+      padding,
+      width,
+      children,
+    };
+  }
+
+  // Pattern matching
+  const recipe = matchPattern(args.pattern);
+  if (recipe) {
+    const children = recipe.components.map((comp) => {
+      const blueprint = COMPONENT_BLUEPRINTS.find(
+        (b) => b.name.toLowerCase() === comp.name.toLowerCase()
+      ) ?? COMPONENT_BLUEPRINTS[0]; // fallback to first blueprint
+
+      return {
+        blueprint,
+        label: comp.label,
+        variant: comp.variant,
+        count: comp.count ?? 1,
+        customText: comp.text,
+      };
+    });
+
+    return {
+      name: recipe.name,
+      description: recipe.description,
+      direction: args.layoutDirection ?? recipe.direction,
+      spacing,
+      padding,
+      width,
+      children,
+      wrapperStyle: recipe.wrapper,
+    };
+  }
+
+  // Fallback: try to extract component names from the pattern text
+  const words = args.pattern.toLowerCase().split(/[\s,+&]+/);
+  const matched: CompositionPlan["children"] = [];
+
+  for (const word of words) {
+    const blueprint = COMPONENT_BLUEPRINTS.find(
+      (b) => b.name.toLowerCase() === word || b.name.toLowerCase().includes(word)
+    );
+    if (blueprint && !matched.find((m) => m.blueprint.name === blueprint.name)) {
+      matched.push({ blueprint, label: blueprint.name, count: 1 });
+    }
+  }
+
+  if (matched.length > 0) {
+    return {
+      name: "Auto-detected Composition",
+      description: `Composed from: ${matched.map((m) => m.blueprint.name).join(", ")}`,
+      direction: args.layoutDirection ?? "VERTICAL",
+      spacing,
+      padding,
+      width,
+      children: matched,
+    };
+  }
+
+  // Ultimate fallback — empty container
+  return {
+    name: "Empty Container",
+    description: `Could not match pattern "${args.pattern}" to known recipes or components.`,
+    direction: "VERTICAL",
+    spacing,
+    padding,
+    width,
+    children: [],
+  };
+}
+
+// ─── Figma builder ─────────────────────────────────────────────────────────
+
+async function buildInFigma(plan: CompositionPlan, args: CompositionBuilderArgs): Promise<{ frameId: string; pageName?: string }> {
+  const bridge = await getBridge();
+
+  // Resolve DS palette — selected DS is authoritative
+  const dsId = bridge.getActiveDesignSystemId();
+  let palette: ResolvedPalette | undefined;
+  try {
+    const tokens = await bridge.getTokens();
+    if (dsId || tokens.length > 0) palette = resolveDesignPalette(tokens, dsId);
+  } catch {
+    if (dsId) palette = resolveDesignPalette([], dsId);
+  }
+
+  // Color helpers — use DS palette when available, else hardcoded defaults
+  const surfaceColor = palette?.surface.rgb ?? "{ r: 0.95, g: 0.95, b: 0.97 }";
+  const borderColor = palette?.border.rgb ?? "{ r: 0.85, g: 0.85, b: 0.85 }";
+  const textColor = palette ? (palette.muted.rgb !== palette.primary.rgb ? palette.muted.rgb : "{ r: 0.1, g: 0.1, b: 0.1 }") : "{ r: 0.1, g: 0.1, b: 0.1 }";
+  const accentColor = palette?.accent.rgb ?? "{ r: 0.4, g: 0.5, b: 0.9 }";
+  const bgColor = palette?.surface.rgb ?? "{ r: 1, g: 1, b: 1 }";
+  const fontFamily = (dsId ? getDesignSystemFontFamily(dsId) : null) ?? "Inter";
+
+  // Build the script to create the composition in Figma
+  const childScripts: string[] = [];
+
+  for (const child of plan.children) {
+    const bp = child.blueprint;
+    const rootNode = bp.root;
+
+    for (let i = 0; i < child.count; i++) {
+      const label = child.count > 1 ? `${child.label} ${i + 1}` : child.label;
+
+      childScripts.push(`
+        // ── ${label} ──
+        (function() {
+          var comp = figma.createFrame();
+          comp.name = '${label.replace(/'/g, "\\'")}';
+          comp.layoutMode = '${rootNode.layoutMode ?? "HORIZONTAL"}';
+          comp.primaryAxisSizingMode = 'AUTO';
+          comp.counterAxisSizingMode = 'AUTO';
+          comp.paddingLeft = ${rootNode.paddingX ?? 16};
+          comp.paddingRight = ${rootNode.paddingX ?? 16};
+          comp.paddingTop = ${rootNode.paddingY ?? 8};
+          comp.paddingBottom = ${rootNode.paddingY ?? 8};
+          comp.itemSpacing = ${rootNode.itemSpacing ?? 8};
+          comp.cornerRadius = ${rootNode.cornerRadius ?? 0};
+          ${rootNode.fillSemantic ? `comp.fills = [{ type: 'SOLID', color: ${surfaceColor} }];` : `comp.fills = [];`}
+          ${rootNode.strokeSemantic ? `comp.strokes = [{ type: 'SOLID', color: ${borderColor} }]; comp.strokeWeight = ${rootNode.strokeWeight ?? 1};` : ""}
+
+          ${rootNode.children?.map((childNode) => {
+            if (childNode.kind === "text") {
+              const text = child.customText ?? childNode.textContent ?? label;
+              return `
+                var txt = figma.createText();
+                txt.name = '${childNode.name.replace(/'/g, "\\'")}';
+                txt.characters = '${text.replace(/'/g, "\\'")}';
+                txt.fontSize = ${childNode.textContent?.includes("label") || childNode.name.includes("label") ? 14 : 14};
+                txt.fills = [{ type: 'SOLID', color: ${textColor} }];
+                comp.appendChild(txt);
+              `;
+            }
+            if (childNode.kind === "rect" || childNode.kind === "frame") {
+              return `
+                var rect = figma.createFrame();
+                rect.name = '${childNode.name.replace(/'/g, "\\'")}';
+                rect.resize(${childNode.width ?? 16}, ${childNode.height ?? 16});
+                ${childNode.cornerRadius ? `rect.cornerRadius = ${childNode.cornerRadius};` : ""}
+                ${childNode.fillSemantic ? `rect.fills = [{ type: 'SOLID', color: ${accentColor} }];` : `rect.fills = [{ type: 'SOLID', color: ${surfaceColor} }];`}
+                comp.appendChild(rect);
+              `;
+            }
+            return "";
+          }).join("\n") ?? ""}
+
+          container.appendChild(comp);
+        })();
+      `);
+    }
+  }
+
+  const wrapperFill = plan.wrapperStyle?.fill
+    ? `container.fills = [{ type: 'SOLID', color: ${bgColor} }];`
+    : args.includeBackground
+      ? `container.fills = [{ type: 'SOLID', color: ${bgColor} }];`
+      : `container.fills = [];`;
+
+  const script = `
+    (async () => {
+      await figma.loadFontAsync({ family: ${JSON.stringify(fontFamily)}, style: "Regular" }).catch(function() { return figma.loadFontAsync({ family: "Inter", style: "Regular" }); });
+      await figma.loadFontAsync({ family: ${JSON.stringify(fontFamily)}, style: "Medium" }).catch(function() { return figma.loadFontAsync({ family: "Inter", style: "Medium" }); });
+      await figma.loadFontAsync({ family: ${JSON.stringify(fontFamily)}, style: "Bold" }).catch(function() { return figma.loadFontAsync({ family: "Inter", style: "Bold" }); });
+
+      ${args.targetPage ? `
+        var targetPage = figma.root.children.find(function(p) { return p.name === '${args.targetPage.replace(/'/g, "\\'")}'; });
+        if (!targetPage) {
+          targetPage = figma.createPage();
+          targetPage.name = '${args.targetPage.replace(/'/g, "\\'")}';
+        }
+        figma.currentPage = targetPage;
+      ` : ""}
+
+      // Create container frame
+      var container = figma.createFrame();
+      container.name = '${plan.name.replace(/'/g, "\\'")}';
+      container.layoutMode = '${plan.direction}';
+      container.primaryAxisSizingMode = 'AUTO';
+      container.counterAxisSizingMode = 'FIXED';
+      container.resize(${plan.width}, 100);
+      container.paddingLeft = ${plan.padding};
+      container.paddingRight = ${plan.padding};
+      container.paddingTop = ${plan.padding};
+      container.paddingBottom = ${plan.padding};
+      container.itemSpacing = ${plan.spacing};
+      ${plan.wrapperStyle?.cornerRadius ? `container.cornerRadius = ${plan.wrapperStyle.cornerRadius};` : ""}
+      ${wrapperFill}
+      ${plan.wrapperStyle?.stroke ? `container.strokes = [{ type: 'SOLID', color: ${borderColor} }]; container.strokeWeight = 1;` : ""}
+      ${plan.wrapperStyle?.shadow ? `container.effects = [{ type: 'DROP_SHADOW', color: { r: 0, g: 0, b: 0, a: 0.1 }, offset: { x: 0, y: 4 }, radius: 12, spread: 0, visible: true }];` : ""}
+
+      // Title label
+      var titleLabel = figma.createText();
+      titleLabel.name = 'Composition Title';
+      titleLabel.fontName = { family: ${JSON.stringify(fontFamily)}, style: "Bold" };
+      titleLabel.fontSize = 18;
+      titleLabel.characters = '${plan.name.replace(/'/g, "\\'")}';
+      titleLabel.fills = [{ type: 'SOLID', color: ${textColor} }];
+      container.appendChild(titleLabel);
+
+      ${childScripts.join("\n")}
+
+      // Position on canvas
+      container.x = 100;
+      container.y = 100;
+
+      figma.currentPage.selection = [container];
+      figma.viewport.scrollAndZoomIntoView([container]);
+
+      return { frameId: container.id, pageName: figma.currentPage.name };
+    })();
+  `;
+
+  const result = await bridge.execute(script);
+  if (!result.success || !result.result) {
+    throw new Error(result.error || "Failed to build composition in Figma");
+  }
+
+  return result.result as { frameId: string; pageName: string };
+}
+
+// ─── Main handler ──────────────────────────────────────────────────────────
+
+export async function compositionBuilderHandler(args: CompositionBuilderArgs): Promise<unknown> {
+  const plan = buildPlan(args);
+
+  if (plan.children.length === 0) {
+    return {
+      error: `Could not match pattern "${args.pattern}" to any known recipe or component.`,
+      availablePatterns: PATTERN_RECIPES.map((r) => ({
+        pattern: r.name,
+        keywords: r.keywords.source,
+        components: r.components.map((c) => c.name),
+      })),
+      availableComponents: COMPONENT_BLUEPRINTS.map((b) => b.name),
+      hint: "Try a specific pattern like 'login form', 'search with filters', or 'card with actions'. Or provide explicit components via the 'components' parameter.",
+    };
+  }
+
+  // Build in Figma
+  const { frameId, pageName } = await buildInFigma(plan, args);
+
+  return {
+    composition: plan.name,
+    description: plan.description,
+    frameId,
+    pageName,
+    layout: {
+      direction: plan.direction,
+      spacing: plan.spacing,
+      padding: plan.padding,
+      width: plan.width,
+    },
+    components: plan.children.map((c) => ({
+      name: c.blueprint.name,
+      label: c.label,
+      count: c.count,
+      variant: c.variant,
+    })),
+    totalComponents: plan.children.reduce((sum, c) => sum + c.count, 0),
+    availablePatterns: PATTERN_RECIPES.map((r) => r.name),
+  };
+}