@fragments-sdk/cli 0.7.2 → 0.7.4

package/src/viewer/render-utils.ts

@@ -8,6 +8,8 @@ export interface RenderRequest {
   component: string;
   /** Props to pass to the component */
   props?: Record<string, unknown>;
+  /** Variant name to render (uses variant's render function) */
+  variant?: string;
   /** Viewport dimensions */
   viewport?: {
     width: number;
@@ -161,6 +163,145 @@ render();
 `;
 }
 
+/**
+ * Generate a render script that renders a specific variant by name.
+ * The variant lookup happens in the browser using the fragment's variants array.
+ */
+export function generateVariantRenderScript(
+  fragmentPath: string,
+  componentName: string,
+  variantName: string
+): string {
+  const variantNameLower = JSON.stringify(variantName.toLowerCase());
+
+  return `
+import React from "react";
+import { createRoot } from "react-dom/client";
+
+async function render() {
+  const root = document.getElementById("render-root");
+
+  try {
+    const fragmentModule = await import("${fragmentPath}");
+    const fragment = fragmentModule.default;
+
+    if (!fragment || !fragment.variants || fragment.variants.length === 0) {
+      throw new Error("Fragment has no variants");
+    }
+
+    const variant = fragment.variants.find(
+      v => v.name.toLowerCase() === ${variantNameLower}
+    );
+
+    if (!variant) {
+      const available = fragment.variants.map(v => v.name).join(", ");
+      throw new Error("Variant '" + ${JSON.stringify(variantName)} + "' not found. Available: " + available);
+    }
+
+    const element = variant.render();
+
+    const reactRoot = createRoot(root);
+    reactRoot.render(element);
+
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => {
+        root.classList.add("ready");
+        window.__RENDER_READY__ = true;
+      });
+    });
+  } catch (error) {
+    console.error("Render error:", error);
+    root.innerHTML = \`
+      <div class="render-error">
+        <strong>Render Error</strong>
+        <pre>\${error.message}</pre>
+      </div>
+    \`;
+    root.classList.add("ready");
+    window.__RENDER_READY__ = true;
+    window.__RENDER_ERROR__ = error.message;
+  }
+}
+
+render();
+`;
+}
+
+/**
+ * Generate a render script that also runs axe-core for accessibility auditing.
+ * When variantName is provided, renders that specific variant; otherwise renders
+ * the component with empty props.
+ */
+export function generateA11yRenderScript(
+  fragmentPath: string,
+  componentName: string,
+  variantName?: string
+): string {
+  const variantLookup = variantName
+    ? `
+    const variant = fragment.variants?.find(
+      v => v.name.toLowerCase() === ${JSON.stringify(variantName.toLowerCase())}
+    );
+    if (!variant) {
+      throw new Error("Variant '${variantName}' not found");
+    }
+    element = variant.render();`
+    : `
+    element = React.createElement(fragment.component, {});`;
+
+  return `
+import React from "react";
+import { createRoot } from "react-dom/client";
+import axe from "axe-core";
+
+async function render() {
+  const root = document.getElementById("render-root");
+
+  try {
+    const fragmentModule = await import("${fragmentPath}");
+    const fragment = fragmentModule.default;
+
+    if (!fragment || !fragment.component) {
+      throw new Error("Fragment does not export a component");
+    }
+
+    let element;
+    ${variantLookup}
+
+    const reactRoot = createRoot(root);
+    reactRoot.render(element);
+
+    // Wait for React to flush rendering
+    await new Promise(resolve => {
+      requestAnimationFrame(() => {
+        requestAnimationFrame(resolve);
+      });
+    });
+
+    // Additional settle time for CSS/animations
+    await new Promise(resolve => setTimeout(resolve, 100));
+
+    // Run axe-core accessibility audit
+    const results = await axe.run('#render-root', {
+      runOnly: {
+        type: 'tag',
+        values: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'best-practice'],
+      },
+    });
+
+    window.__AXE_RESULTS__ = results;
+    window.__RENDER_READY__ = true;
+  } catch (error) {
+    console.error("A11y audit error:", error);
+    window.__AXE_ERROR__ = error.message;
+    window.__RENDER_READY__ = true;
+  }
+}
+
+render();
+`;
+}
+
 /**
  * Generate a virtual module ID for a render request.
  * This creates a unique ID that Vite can resolve.

package/src/viewer/styles/globals.css

@@ -65,7 +65,8 @@ html {
 }
 
 body {
-  font-family: var(--fui-font-sans, 'Geist Sans', Inter, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif);
+  margin: 0;
+  font-family: var(--fui-font-sans, Inter, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif);
   background-color: var(--bg-primary);
   color: var(--text-primary);
   -webkit-font-smoothing: antialiased;

package/src/viewer/vite-plugin.ts

@@ -28,6 +28,8 @@ import {
 import svgr from "vite-plugin-svgr";
 import {
   generateRenderScript,
+  generateVariantRenderScript,
+  generateA11yRenderScript,
   findFragmentByName,
   getAvailableComponents,
   type RenderRequest,
@@ -180,6 +182,21 @@ export function fragmentsPlugin(options: FragmentsPluginOptions): Plugin[] {
     // Add process.env shim and esbuild config for Storybook compatibility
     config() {
       return {
+        build: {
+          rollupOptions: {
+            onwarn(warning: any, defaultHandler: any) {
+              // Suppress Node.js module externalization warnings from html2canvas/sanitize-html
+              if (
+                warning.code === "MODULE_LEVEL_DIRECTIVE" ||
+                (warning.message &&
+                  warning.message.includes("has been externalized"))
+              ) {
+                return;
+              }
+              defaultHandler(warning);
+            },
+          },
+        },
         define: {
           // Shim process.env for story files that use it (e.g., process.env.STORYBOOK_*)
           "process.env": "{}",
@@ -216,7 +233,7 @@ export function fragmentsPlugin(options: FragmentsPluginOptions): Plugin[] {
           try {
             // Parse JSON body
             const body = await parseJsonBody(req);
-            const { component, props = {}, viewport } = body as RenderRequest;
+            const { component, props = {}, viewport, variant } = body as RenderRequest;
 
             if (!component) {
               res.writeHead(400, { "Content-Type": "application/json" });
@@ -258,12 +275,18 @@ export function fragmentsPlugin(options: FragmentsPluginOptions): Plugin[] {
               return;
             }
 
-            // Generate render script
-            const renderScript = generateRenderScript(
-              fragmentFile.absolutePath,
-              fragmentInfo.name,
-              props
-            );
+            // Generate render script — use variant render if specified, otherwise props
+            const renderScript = variant
+              ? generateVariantRenderScript(
+                  fragmentFile.absolutePath,
+                  fragmentInfo.name,
+                  variant
+                )
+              : generateRenderScript(
+                  fragmentFile.absolutePath,
+                  fragmentInfo.name,
+                  props
+                );
 
             // Store the render request for the render page to pick up
             const requestId =
@@ -1022,14 +1045,32 @@ export function fragmentsPlugin(options: FragmentsPluginOptions): Plugin[] {
               return;
             }
 
-            // Check if tokens are configured
+            // Auto-discover tokens when config.tokens is missing
             if (!config.tokens || !config.tokens.include || config.tokens.include.length === 0) {
-              res.writeHead(400, { "Content-Type": "application/json" });
-              res.end(JSON.stringify({
-                error: "No token configuration found",
-                suggestion: "Add 'tokens' config to fragments.config.ts to enable fix generation",
-              }));
-              return;
+              try {
+                const { discoverTokenFiles } = await import("../core/discovery.js");
+                const discovered = await discoverTokenFiles(projectRoot);
+                if (discovered.length > 0) {
+                  config.tokens = {
+                    ...config.tokens,
+                    include: discovered.map((f) => f.relativePath),
+                  };
+                } else {
+                  res.writeHead(400, { "Content-Type": "application/json" });
+                  res.end(JSON.stringify({
+                    error: "No token files found",
+                    suggestion: "Add 'tokens' config to fragments.config.ts or add token files matching default patterns (_variables.scss, tokens.scss, etc.)",
+                  }));
+                  return;
+                }
+              } catch {
+                res.writeHead(400, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({
+                  error: "No token configuration found and auto-discovery failed",
+                  suggestion: "Add 'tokens' config to fragments.config.ts to enable fix generation",
+                }));
+                return;
+              }
             }
 
             // Load fragment data
@@ -1057,23 +1098,81 @@ export function fragmentsPlugin(options: FragmentsPluginOptions): Plugin[] {
               await registry.initialize(config.tokens, projectRoot);
             }
 
-            // For now, we generate patches based on style diff data
-            // In a full implementation, we would:
-            // 1. Render the component and get computed styles
-            // 2. Compare with Figma styles to find hardcoded values
-            // 3. Generate patches for each hardcoded value
-
             // Get source file path from fragment
             const fragmentFile = fragmentFiles.find(
               (f) => f.relativePath === fragmentInfo.path
             );
             const sourceFile = fragmentFile?.relativePath || `${component}.tsx`;
 
-            // For demonstration, we'll create a placeholder response
-            // In production, this would use style comparison + AST patching
+            // Render the component and extract computed styles
+            let styleDiffs: Array<{
+              property: string;
+              figma: string;
+              rendered: string;
+              match: boolean;
+            }> = [];
+
+            if (fragmentFile) {
+              try {
+                const renderScript = generateRenderScript(
+                  fragmentFile.absolutePath,
+                  fragmentInfo.name,
+                  {}
+                );
+
+                const requestId =
+                  Date.now().toString(36) + Math.random().toString(36).slice(2);
+                pendingRenders.set(requestId, {
+                  script: renderScript,
+                  viewport: { width: 800, height: 600 },
+                });
+
+                const address = _server.httpServer?.address();
+                const port =
+                  typeof address === "object" && address ? address.port : 6006;
+
+                const { computedStyles } = await captureRenderWithStyles(
+                  `http://localhost:${port}/fragments/__render__/${requestId}`,
+                  { width: 800, height: 600 },
+                  true
+                );
+                pendingRenders.delete(requestId);
+
+                if (computedStyles) {
+                  // Build token value lookup from registry
+                  const tokenValues = new Map<string, string>();
+                  const allTokens = registry.getAllTokens();
+                  for (const t of allTokens) {
+                    if (t.resolvedValue) {
+                      tokenValues.set(t.resolvedValue, t.name);
+                    }
+                  }
+
+                  // For each computed style property, check if it uses a token
+                  for (const [prop, value] of Object.entries(computedStyles)) {
+                    if (!value || value === "transparent" || value === "rgba(0, 0, 0, 0)") continue;
+
+                    // Check if the value matches any token
+                    const matchesToken = tokenValues.has(value);
+                    if (!matchesToken) {
+                      styleDiffs.push({
+                        property: prop,
+                        figma: value, // Using rendered as "expected" since we have no Figma
+                        rendered: value,
+                        match: false,
+                      });
+                    }
+                  }
+                }
+              } catch (renderErr) {
+                // If rendering fails, continue with empty diffs
+                console.warn("[Fragments] Could not render for style extraction:", renderErr);
+              }
+            }
+
             const result = generateTokenPatches(
               component,
-              [], // Would be populated by actual style diffs
+              styleDiffs,
               registry,
               { sourceFile }
             );
@@ -1095,6 +1194,205 @@ export function fragmentsPlugin(options: FragmentsPluginOptions): Plugin[] {
           return;
         }
 
+        // Handle /fragments/a11y endpoint for accessibility auditing
+        if (req.url === "/fragments/a11y" && req.method === "POST") {
+          try {
+            const body = (await parseJsonBody(req)) as {
+              component: string;
+              variant?: string;
+              standard?: "AA" | "AAA";
+            };
+
+            const { component, variant: variantName, standard = "AA" } = body;
+
+            if (!component) {
+              res.writeHead(400, { "Content-Type": "application/json" });
+              res.end(
+                JSON.stringify({ error: "Missing required field: component" })
+              );
+              return;
+            }
+
+            // Load fragments to find the component
+            const loadedFragments = await loadFragmentsForRender(
+              fragmentFiles,
+              projectRoot
+            );
+            const fragmentInfo = findFragmentByName(component, loadedFragments);
+
+            if (!fragmentInfo) {
+              const available = getAvailableComponents(loadedFragments);
+              res.writeHead(400, { "Content-Type": "application/json" });
+              res.end(
+                JSON.stringify({
+                  error: `Component '${component}' not found. Available: ${available.join(", ")}`,
+                })
+              );
+              return;
+            }
+
+            const fragmentFile = fragmentFiles.find(
+              (f) => f.relativePath === fragmentInfo.path
+            );
+            if (!fragmentFile) {
+              res.writeHead(500, { "Content-Type": "application/json" });
+              res.end(
+                JSON.stringify({ error: "Could not resolve fragment file path" })
+              );
+              return;
+            }
+
+            // Determine which variants to audit
+            const variantNames: string[] = [];
+            if (variantName) {
+              variantNames.push(variantName);
+            } else {
+              // Load full fragment data to get variant names
+              const fullData = await loadFullFragmentData(projectRoot);
+              const fragmentData = fullData
+                ? Object.values(fullData.fragments).find(
+                    (f) => f.meta.name.toLowerCase() === component.toLowerCase()
+                  )
+                : null;
+
+              if (fragmentData && fragmentData.variants?.length > 0) {
+                for (const v of fragmentData.variants) {
+                  variantNames.push(v.name);
+                }
+              } else {
+                // Fallback: audit default render (no variant)
+                variantNames.push("Default");
+              }
+            }
+
+            // Get server address
+            const address = _server.httpServer?.address();
+            const port =
+              typeof address === "object" && address ? address.port : 6006;
+
+            // Audit each variant
+            const results: Array<{
+              variant: string;
+              violations: number;
+              passes: number;
+              incomplete: number;
+              summary: {
+                total: number;
+                critical: number;
+                serious: number;
+                moderate: number;
+                minor: number;
+              };
+              violationDetails?: Array<{
+                id: string;
+                impact: string | undefined;
+                description: string;
+                helpUrl: string;
+                nodes: number;
+              }>;
+            }> = [];
+
+            for (const vName of variantNames) {
+              // Generate a11y render script for this variant
+              const a11yScript = generateA11yRenderScript(
+                fragmentFile.absolutePath,
+                fragmentInfo.name,
+                vName === "Default" && !variantName ? undefined : vName
+              );
+
+              const requestId =
+                Date.now().toString(36) + Math.random().toString(36).slice(2);
+              pendingRenders.set(requestId, {
+                script: a11yScript,
+                viewport: { width: 800, height: 600 },
+              });
+
+              try {
+                const auditResult = await captureA11yAudit(
+                  `http://localhost:${port}/fragments/__render__/${requestId}`,
+                  { width: 800, height: 600 }
+                );
+
+                // Transform axe results into the expected shape
+                let critical = 0;
+                let serious = 0;
+                let moderate = 0;
+                let minor = 0;
+
+                for (const violation of auditResult.violations ?? []) {
+                  switch (violation.impact) {
+                    case "critical":
+                      critical++;
+                      break;
+                    case "serious":
+                      serious++;
+                      break;
+                    case "moderate":
+                      moderate++;
+                      break;
+                    case "minor":
+                      minor++;
+                      break;
+                  }
+                }
+
+                results.push({
+                  variant: vName,
+                  violations: auditResult.violations?.length ?? 0,
+                  passes: auditResult.passes?.length ?? 0,
+                  incomplete: auditResult.incomplete?.length ?? 0,
+                  summary: {
+                    total: critical + serious + moderate + minor,
+                    critical,
+                    serious,
+                    moderate,
+                    minor,
+                  },
+                  violationDetails: (auditResult.violations ?? []).map(v => ({
+                    id: v.id,
+                    impact: v.impact,
+                    description: v.description,
+                    helpUrl: v.helpUrl,
+                    nodes: v.nodes.length,
+                  })),
+                });
+              } catch (err) {
+                // If a single variant fails, report it as a result with error info
+                results.push({
+                  variant: vName,
+                  violations: 0,
+                  passes: 0,
+                  incomplete: 0,
+                  summary: {
+                    total: 0,
+                    critical: 0,
+                    serious: 0,
+                    moderate: 0,
+                    minor: 0,
+                  },
+                });
+              } finally {
+                pendingRenders.delete(requestId);
+              }
+            }
+
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({ results }));
+          } catch (error) {
+            console.error("[Fragments] Error running a11y audit:", error);
+            res.writeHead(500, { "Content-Type": "application/json" });
+            res.end(
+              JSON.stringify({
+                error:
+                  error instanceof Error
+                    ? error.message
+                    : "A11y audit failed",
+              })
+            );
+          }
+          return;
+        }
+
         // Handle /fragments/preview/ - isolated iframe for component previews
         if (req.url?.startsWith("/fragments/preview")) {
           // Redirect to trailing slash
@@ -1470,7 +1768,9 @@ export async function loadFragment(path) {
     }
   }
 
-  loadedFragments.set(path, fragment);
+  if (fragment) {
+    loadedFragments.set(path, fragment);
+  }
   return fragment;
 }
 
@@ -1673,6 +1973,81 @@ async function loadFragmentsForRender(
   });
 }
 
+/**
+ * Load full fragment data from fragments.json (includes variants).
+ * Used by the a11y endpoint to enumerate all variants.
+ */
+async function loadFullFragmentData(
+  configDir: string
+): Promise<{
+  fragments: Record<
+    string,
+    {
+      filePath: string;
+      meta: { name: string };
+      variants: Array<{ name: string; description?: string; code?: string }>;
+    }
+  >;
+} | null> {
+  const { join } = await import("node:path");
+  const fragmentsJsonPath = join(configDir, BRAND.outFile);
+
+  try {
+    const content = await readFile(fragmentsJsonPath, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Capture an accessibility audit using the shared browser pool.
+ * Navigates to the render page (which imports axe-core and runs the audit),
+ * then extracts the axe results from the page context.
+ */
+async function captureA11yAudit(
+  url: string,
+  viewport: { width: number; height: number }
+): Promise<{
+  violations: Array<{ impact?: string; id: string; description: string; helpUrl: string; nodes: Array<unknown> }>;
+  passes: Array<{ id: string }>;
+  incomplete: Array<{ id: string }>;
+}> {
+  const { pool } = await getSharedRenderPool();
+
+  const ctx = await pool.acquire();
+  const page = await ctx.newPage();
+
+  try {
+    await page.setViewportSize(viewport);
+    await page.goto(url, { waitUntil: "networkidle" });
+
+    // Wait for the render + axe audit to complete
+    await page.waitForFunction(
+      () => (window as any).__RENDER_READY__ === true,
+      { timeout: 15000 }
+    );
+
+    // Check for error
+    const error = await page.evaluate(() => (window as any).__AXE_ERROR__);
+    if (error) {
+      throw new Error(`A11y audit error: ${error}`);
+    }
+
+    // Extract axe results
+    const results = await page.evaluate(() => (window as any).__AXE_RESULTS__);
+
+    if (!results) {
+      throw new Error("Axe results not available — axe-core may not be installed");
+    }
+
+    return results;
+  } finally {
+    await page.close();
+    pool.release(ctx);
+  }
+}
+
 /**
  * Serve the render HTML page for AI preview.
  */