@fragments-sdk/cli 0.14.3 → 0.15.0

package/src/viewer/preview-adapter.ts

@@ -0,0 +1,116 @@
+/**
+ * Preview Adapter — generates render modules from contract.json metadata.
+ *
+ * Each adapter takes a CompiledFragment sourced from a .contract.json
+ * and produces a virtual ES module string that a bundler (Vite) can serve.
+ */
+
+import type { CompiledFragment } from '@fragments-sdk/core';
+
+export interface PreviewConfig {
+  setupModule?: string;
+  wrapperModule?: string;
+  wrapperExport?: string;
+  css?: string[];
+  theme?: 'light' | 'dark';
+}
+
+export interface PreviewAdapter {
+  framework: string;
+  canHandle(fragment: CompiledFragment): boolean;
+  generateRenderModule(
+    fragment: CompiledFragment,
+    variant: string,
+    previewConfig: PreviewConfig,
+  ): string;
+}
+
+/**
+ * React preview adapter — generates a virtual module that:
+ * 1. Imports the component from sourcePath/exportName
+ * 2. Wraps with providers from project config
+ * 3. Renders with args from the selected example
+ * 4. Injects CSS from config
+ */
+class ReactPreviewAdapter implements PreviewAdapter {
+  framework = 'react';
+
+  canHandle(fragment: CompiledFragment): boolean {
+    return (fragment.framework ?? 'react') === 'react';
+  }
+
+  generateRenderModule(
+    fragment: CompiledFragment,
+    variant: string,
+    config: PreviewConfig,
+  ): string {
+    if (!fragment.sourcePath || !fragment.exportName) {
+      throw new Error(
+        `Cannot preview ${fragment.meta.name}: missing sourcePath or exportName`,
+      );
+    }
+
+    const example = fragment.variants.find((v) => v.name === variant) ??
+      fragment.variants[0];
+
+    const args = example?.args ?? {};
+    const argsStr = JSON.stringify(args);
+
+    const lines: string[] = [];
+
+    // Setup module (global CSS, MSW, etc.)
+    if (config.setupModule) {
+      lines.push(`import '${config.setupModule}';`);
+    }
+
+    // CSS imports
+    if (config.css?.length) {
+      for (const css of config.css) {
+        lines.push(`import '${css}';`);
+      }
+    }
+
+    // Import React
+    lines.push(`import React from 'react';`);
+
+    // Import the component
+    lines.push(`import { ${fragment.exportName} } from '${fragment.sourcePath}';`);
+
+    // Import wrapper if configured
+    if (config.wrapperModule && config.wrapperExport) {
+      lines.push(`import { ${config.wrapperExport} } from '${config.wrapperModule}';`);
+    }
+
+    // Generate the render function
+    lines.push('');
+    lines.push(`const args = ${argsStr};`);
+    lines.push('');
+    lines.push('export default function PreviewRender() {');
+
+    if (config.wrapperModule && config.wrapperExport) {
+      lines.push(`  return React.createElement(${config.wrapperExport}, null,`);
+      lines.push(`    React.createElement(${fragment.exportName}, args)`);
+      lines.push('  );');
+    } else {
+      lines.push(`  return React.createElement(${fragment.exportName}, args);`);
+    }
+
+    lines.push('}');
+
+    return lines.join('\n');
+  }
+}
+
+/**
+ * Create a preview adapter for the given framework.
+ */
+export function createPreviewAdapter(
+  framework: string,
+  _config: PreviewConfig,
+): PreviewAdapter {
+  if (framework === 'react') {
+    return new ReactPreviewAdapter();
+  }
+  // Future: Vue, Svelte adapters
+  throw new Error(`No preview adapter available for framework: ${framework}`);
+}

package/src/viewer/style-utils.ts

@@ -1,414 +1,29 @@
 /**
- * Style comparison utilities for comparing Figma design properties
- * with rendered component computed styles.
- */
-
-/**
- * Style diff result for a single CSS property
- */
-export interface StyleDiffItem {
-  /** CSS property name */
-  property: string;
-  /** Expected value from Figma */
-  figma: string;
-  /** Actual value from rendered component */
-  rendered: string;
-  /** Whether values match (within tolerance) */
-  match: boolean;
-}
-
-/**
- * Result of comparing styles
- */
-export interface StyleComparisonResult {
-  /** Whether all styles match */
-  match: boolean;
-  /** Individual property comparisons */
-  properties: StyleDiffItem[];
-  /** CSS properties from Figma design */
-  figmaStyles: Record<string, string>;
-  /** Computed CSS properties from rendered component */
-  renderedStyles: Record<string, string>;
-}
-
-/**
- * Compare Figma CSS properties with rendered computed styles.
- */
-export function compareStyles(
-  figmaStyles: Record<string, string | undefined>,
-  renderedStyles: Record<string, string>
-): StyleComparisonResult {
-  const properties: StyleDiffItem[] = [];
-  const cleanFigmaStyles: Record<string, string> = {};
-
-  // Properties to compare
-  const propsToCompare = [
-    "backgroundColor",
-    "borderColor",
-    "borderWidth",
-    "borderRadius",
-    "fontFamily",
-    "fontSize",
-    "fontWeight",
-    "lineHeight",
-    "letterSpacing",
-    "textAlign",
-    "boxShadow",
-    "padding",
-    "gap",
-    "opacity",
-  ];
-
-  for (const prop of propsToCompare) {
-    const figmaValue = figmaStyles[prop];
-    const renderedValue = renderedStyles[prop];
-
-    if (figmaValue !== undefined) {
-      cleanFigmaStyles[prop] = figmaValue;
-
-      const match = compareStyleValue(prop, figmaValue, renderedValue || "");
-      properties.push({
-        property: prop,
-        figma: figmaValue,
-        rendered: renderedValue || "(not set)",
-        match,
-      });
-    }
-  }
-
-  const allMatch = properties.every((p) => p.match);
-
-  return {
-    match: allMatch,
-    properties,
-    figmaStyles: cleanFigmaStyles,
-    renderedStyles,
-  };
-}
-
-/**
- * Compare a single style value with tolerance for color and numeric differences.
- */
-export function compareStyleValue(
-  prop: string,
-  figma: string,
-  rendered: string
-): boolean {
-  // Normalize values for comparison
-  const normalizedFigma = normalizeStyleValue(prop, figma);
-  const normalizedRendered = normalizeStyleValue(prop, rendered);
-
-  // Direct match
-  if (normalizedFigma === normalizedRendered) {
-    return true;
-  }
-
-  // Color comparison with tolerance
-  if (prop === "backgroundColor" || prop === "borderColor") {
-    return compareColors(normalizedFigma, normalizedRendered, 5);
-  }
-
-  // Numeric comparison with tolerance (for pixels)
-  if (
-    ["borderWidth", "borderRadius", "fontSize", "padding", "gap"].includes(prop)
-  ) {
-    return compareNumericValues(normalizedFigma, normalizedRendered, 1);
-  }
-
-  return false;
-}
-
-/**
- * Normalize a style value for comparison.
- */
-export function normalizeStyleValue(prop: string, value: string): string {
-  // Remove extra whitespace
-  let normalized = value.trim().replace(/\s+/g, " ");
-
-  // Normalize "none" shadow to empty
-  if (prop === "boxShadow" && normalized === "none") {
-    normalized = "";
-  }
-
-  // Normalize rgba(0, 0, 0, 0) to "transparent"
-  if (normalized.match(/rgba\(\s*0\s*,\s*0\s*,\s*0\s*,\s*0\s*\)/)) {
-    normalized = "transparent";
-  }
-
-  return normalized;
-}
-
-/**
- * Compare two color values with tolerance.
- */
-export function compareColors(
-  color1: string,
-  color2: string,
-  tolerance: number
-): boolean {
-  const rgb1 = parseColor(color1);
-  const rgb2 = parseColor(color2);
-
-  if (!rgb1 || !rgb2) {
-    return color1 === color2;
-  }
-
-  return (
-    Math.abs(rgb1.r - rgb2.r) <= tolerance &&
-    Math.abs(rgb1.g - rgb2.g) <= tolerance &&
-    Math.abs(rgb1.b - rgb2.b) <= tolerance &&
-    Math.abs((rgb1.a ?? 1) - (rgb2.a ?? 1)) <= 0.05
-  );
-}
-
-/**
- * Parse a color string to RGB values.
- */
-export function parseColor(
-  color: string
-): { r: number; g: number; b: number; a?: number } | null {
-  // Handle hex colors
-  const hexMatch = color.match(/^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i);
-  if (hexMatch) {
-    return {
-      r: parseInt(hexMatch[1], 16),
-      g: parseInt(hexMatch[2], 16),
-      b: parseInt(hexMatch[3], 16),
-    };
-  }
-
-  // Handle rgb/rgba
-  const rgbaMatch = color.match(
-    /rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*([\d.]+))?\s*\)/
-  );
-  if (rgbaMatch) {
-    return {
-      r: parseInt(rgbaMatch[1], 10),
-      g: parseInt(rgbaMatch[2], 10),
-      b: parseInt(rgbaMatch[3], 10),
-      a: rgbaMatch[4] ? parseFloat(rgbaMatch[4]) : 1,
-    };
-  }
-
-  return null;
-}
-
-/**
- * Compare numeric values (e.g., "10px" vs "11px") with tolerance.
- */
-export function compareNumericValues(
-  value1: string,
-  value2: string,
-  tolerance: number
-): boolean {
-  const num1 = parseFloat(value1);
-  const num2 = parseFloat(value2);
-
-  if (isNaN(num1) || isNaN(num2)) {
-    return value1 === value2;
-  }
-
-  return Math.abs(num1 - num2) <= tolerance;
-}
-
-// ----- Enhanced Token-Aware Style Comparison -----
-
-import type {
-  EnhancedStyleDiffItem,
-  TokenFix,
-  TokenUsageSummary,
-  DesignToken,
-} from "../core/index.js";
-
-/**
- * Enhanced style diff result with token information
- */
-export interface EnhancedStyleComparisonResult extends StyleComparisonResult {
-  /** Individual property comparisons with token info */
-  properties: EnhancedStyleDiffItem[];
-  /** Token usage summary */
-  tokenSummary?: TokenUsageSummary;
-}
-
-/**
- * Token registry interface for style comparison
- * (subset of TokenRegistryManager methods needed here)
- */
-export interface TokenLookup {
-  findByValue(value: string, theme?: string): string[];
-  getToken(name: string): DesignToken | undefined;
-  calculateUsageSummary(
-    styleDiffs: Array<{
-      property: string;
-      figma: string;
-      rendered: string;
-      match: boolean;
-    }>,
-    theme?: string
-  ): TokenUsageSummary;
-}
-
-/**
- * Compare styles with token awareness.
+ * Style comparison utilities — thin re-export from @fragments-sdk/core.
  *
- * This enhanced version:
- * 1. Performs normal style comparison
- * 2. Identifies which values match design tokens
- * 3. Flags hardcoded values that should use tokens
- * 4. Generates fix suggestions
- */
-export function compareStylesWithTokens(
-  figmaStyles: Record<string, string | undefined>,
-  renderedStyles: Record<string, string>,
-  tokenLookup?: TokenLookup,
-  theme = "default"
-): EnhancedStyleComparisonResult {
-  const properties: EnhancedStyleDiffItem[] = [];
-  const cleanFigmaStyles: Record<string, string> = {};
-
-  // Properties to compare
-  const propsToCompare = [
-    "backgroundColor",
-    "borderColor",
-    "borderWidth",
-    "borderRadius",
-    "fontFamily",
-    "fontSize",
-    "fontWeight",
-    "lineHeight",
-    "letterSpacing",
-    "textAlign",
-    "boxShadow",
-    "padding",
-    "gap",
-    "opacity",
-    "color",
-  ];
-
-  for (const prop of propsToCompare) {
-    const figmaValue = figmaStyles[prop];
-    const renderedValue = renderedStyles[prop];
-
-    if (figmaValue !== undefined) {
-      cleanFigmaStyles[prop] = figmaValue;
-
-      const match = compareStyleValue(prop, figmaValue, renderedValue || "");
-
-      // Build enhanced diff item
-      const item: EnhancedStyleDiffItem = {
-        property: prop,
-        figma: figmaValue,
-        rendered: renderedValue || "(not set)",
-        match,
-        isHardcoded: false,
-      };
-
-      // Add token information if registry is available
-      if (tokenLookup) {
-        const figmaTokens = tokenLookup.findByValue(figmaValue, theme);
-        const renderedTokens = renderedValue
-          ? tokenLookup.findByValue(renderedValue, theme)
-          : [];
-
-        if (figmaTokens.length > 0) {
-          item.figmaToken = figmaTokens[0];
-        }
-
-        if (renderedTokens.length > 0) {
-          item.renderedToken = renderedTokens[0];
-        }
-
-        // Determine if this is a hardcoded value
-        // Hardcoded = Figma matches a token, but rendered doesn't use a token
-        item.isHardcoded = !!item.figmaToken && !item.renderedToken;
-
-        // Generate fix suggestion if hardcoded
-        if (item.isHardcoded && item.figmaToken) {
-          const token = tokenLookup.getToken(item.figmaToken);
-          if (token) {
-            const cssProperty = toCssProperty(prop);
-            item.suggestedFix = {
-              tokenName: item.figmaToken,
-              tokenValue: token.resolvedValue,
-              codeFix: `${cssProperty}: var(${item.figmaToken});`,
-              confidence: 0.9,
-              reason: `Figma uses token ${item.figmaToken} (${token.resolvedValue}). Replace hardcoded value with token for consistency.`,
-            };
-          }
-        }
-      }
-
-      properties.push(item);
-    }
-  }
-
-  const allMatch = properties.every((p) => p.match);
-
-  // Calculate token summary if registry available
-  let tokenSummary: TokenUsageSummary | undefined;
-  if (tokenLookup) {
-    tokenSummary = tokenLookup.calculateUsageSummary(
-      properties.map((p) => ({
-        property: p.property,
-        figma: p.figma,
-        rendered: p.rendered,
-        match: p.match,
-      })),
-      theme
-    );
-  }
-
-  return {
-    match: allMatch,
-    properties,
-    figmaStyles: cleanFigmaStyles,
-    renderedStyles,
-    tokenSummary,
-  };
-}
-
-/**
- * Convert camelCase to kebab-case CSS property
- */
-function toCssProperty(prop: string): string {
-  return prop.replace(/([A-Z])/g, "-$1").toLowerCase();
-}
-
-/**
- * Format token summary for display
- */
-export function formatTokenSummary(summary: TokenUsageSummary): string {
-  const lines: string[] = [];
-
-  lines.push(`Token Compliance: ${summary.compliancePercent}%`);
-  lines.push(
-    `${summary.usingTokens}/${summary.totalProperties} properties using tokens`
-  );
-
-  if (summary.hardcoded > 0) {
-    lines.push(`${summary.hardcoded} hardcoded value(s) detected`);
-  }
-
-  if (summary.implicitMatches > 0) {
-    lines.push(`${summary.implicitMatches} implicit match(es)`);
-  }
-
-  return lines.join("\n");
-}
-
-/**
- * Get status badge for token compliance
- */
-export function getComplianceBadge(
-  compliancePercent: number
-): { label: string; color: string } {
-  if (compliancePercent >= 100) {
-    return { label: "Excellent", color: "green" };
-  } else if (compliancePercent >= 80) {
-    return { label: "Good", color: "blue" };
-  } else if (compliancePercent >= 50) {
-    return { label: "Fair", color: "yellow" };
-  } else {
-    return { label: "Poor", color: "red" };
-  }
-}
+ * The canonical comparison engine lives in @fragments-sdk/core/style-comparison.
+ * This file exists for backwards compatibility with existing imports.
+ */
+export {
+  // Types
+  type StyleDiffItem,
+  type StyleComparisonResult,
+  type EnhancedStyleComparisonResult,
+  type TokenLookup,
+  type NormalizedToken,
+  type NormalizedStyleMap,
+  type StyleComparisonOptions,
+  // Functions
+  compareStyles,
+  compareStyleValue,
+  compareStylesWithTokens,
+  normalizeStyleValue,
+  compareColors,
+  parseColor,
+  compareNumericValues,
+  formatTokenSummary,
+  getComplianceBadge,
+  // Constants
+  DEFAULT_STYLE_PROPERTIES,
+  DEFAULT_ENHANCED_STYLE_PROPERTIES,
+} from "@fragments-sdk/core";

package/src/viewer/vite-plugin.ts

@@ -1532,9 +1532,9 @@ export function fragmentsPlugin(options: FragmentsPluginOptions): Plugin[] {
       return null;
     },
 
-    // Handle HMR for fragment files
+    // Handle HMR for fragment and contract files
     handleHotUpdate({ file, server }) {
-      if (fragmentFileSet.has(file)) {
+      if (fragmentFileSet.has(file) || file.endsWith('.contract.json')) {
         // Invalidate the virtual fragments module
         const mod = server.moduleGraph.getModuleById(VIRTUAL_FRAGMENTS_RESOLVED);
         if (mod) {