@fragments-sdk/cli 0.2.2

package/src/viewer/jsx-parser.ts

@@ -0,0 +1,485 @@
+/**
+ * JSX Parser
+ *
+ * Parses JSX strings into a structured component tree that can be
+ * used for rendering multi-component compositions.
+ */
+
+import { parse } from "@babel/parser";
+import type {
+  JSXElement,
+  JSXFragment,
+  JSXText,
+  JSXExpressionContainer,
+  JSXAttribute,
+  JSXSpreadAttribute,
+  Expression,
+  Node,
+} from "@babel/types";
+
+/**
+ * Represents a parsed JSX component node
+ */
+export interface ComponentNode {
+  /** Component name (e.g., "Button", "Card") or HTML element name (e.g., "div") */
+  name: string;
+  /** Whether this is an HTML element (lowercase) vs custom component (PascalCase) */
+  isHtmlElement: boolean;
+  /** Props/attributes passed to the component */
+  props: Record<string, unknown>;
+  /** Child nodes (can be ComponentNode, string, or expression) */
+  children: Array<ComponentNode | string>;
+}
+
+/**
+ * Result of parsing a JSX string
+ */
+export interface ParseResult {
+  /** The root component tree */
+  tree: ComponentNode | ComponentNode[];
+  /** List of all unique component names found (excluding HTML elements) */
+  components: string[];
+  /** Any parsing errors */
+  errors: string[];
+}
+
+/**
+ * Parse a JSX string into a component tree.
+ *
+ * @param jsx - The JSX string to parse
+ * @returns ParseResult with the component tree and metadata
+ *
+ * @example
+ * ```ts
+ * const result = parseJSX('<Card><Button variant="primary">Click</Button></Card>');
+ * // result.tree = { name: 'Card', props: {}, children: [{ name: 'Button', props: { variant: 'primary' }, children: ['Click'] }] }
+ * // result.components = ['Card', 'Button']
+ * ```
+ */
+export function parseJSX(jsx: string): ParseResult {
+  const errors: string[] = [];
+  const components = new Set<string>();
+
+  try {
+    // Wrap in a fragment to handle multiple root elements
+    const wrappedJsx = `<>${jsx}</>`;
+
+    const ast = parse(wrappedJsx, {
+      sourceType: "module",
+      plugins: ["jsx"],
+    });
+
+    // Find the expression statement containing our JSX
+    const program = ast.program;
+    const firstStatement = program.body[0];
+
+    if (firstStatement?.type !== "ExpressionStatement") {
+      return {
+        tree: [],
+        components: [],
+        errors: ["Invalid JSX: expected expression statement"],
+      };
+    }
+
+    const expression = firstStatement.expression;
+
+    if (expression.type !== "JSXFragment" && expression.type !== "JSXElement") {
+      return {
+        tree: [],
+        components: [],
+        errors: ["Invalid JSX: expected JSX element or fragment"],
+      };
+    }
+
+    // Parse the JSX tree
+    const parseNode = (
+      node: JSXElement | JSXFragment | JSXText | JSXExpressionContainer
+    ): ComponentNode | string | null => {
+      if (node.type === "JSXText") {
+        const text = node.value.trim();
+        return text || null;
+      }
+
+      if (node.type === "JSXExpressionContainer") {
+        // Handle expressions like {variable} or {condition && <Component />}
+        const exprValue = evaluateExpression(node.expression);
+        // Convert to string or return null if not renderable
+        if (exprValue === null || exprValue === undefined) {
+          return null;
+        }
+        if (typeof exprValue === "string") {
+          return exprValue;
+        }
+        // For non-string primitives, convert to string
+        return String(exprValue);
+      }
+
+      if (node.type === "JSXFragment") {
+        // For fragments, return children directly
+        const children = node.children
+          .map((child) => parseNode(child as JSXElement | JSXFragment | JSXText | JSXExpressionContainer))
+          .filter((c): c is ComponentNode | string => c !== null);
+
+        // If only one child, return it directly
+        if (children.length === 1 && typeof children[0] !== "string") {
+          return children[0];
+        }
+
+        // Return a special fragment node
+        return {
+          name: "Fragment",
+          isHtmlElement: false,
+          props: {},
+          children,
+        };
+      }
+
+      if (node.type === "JSXElement") {
+        const openingElement = node.openingElement;
+        let name: string;
+
+        if (openingElement.name.type === "JSXIdentifier") {
+          name = openingElement.name.name;
+        } else if (openingElement.name.type === "JSXMemberExpression") {
+          // Handle things like MyLib.Button
+          name = getMemberExpressionName(openingElement.name);
+        } else {
+          name = "Unknown";
+        }
+
+        // Check if it's an HTML element (lowercase first letter)
+        const isHtmlElement = /^[a-z]/.test(name);
+
+        // Track custom components
+        if (!isHtmlElement && name !== "Fragment") {
+          components.add(name);
+        }
+
+        // Parse props
+        const props: Record<string, unknown> = {};
+        for (const attr of openingElement.attributes) {
+          if (attr.type === "JSXAttribute") {
+            const propName = attr.name.type === "JSXIdentifier" ? attr.name.name : String(attr.name.name);
+            const propValue = parseAttributeValue(attr);
+            props[propName] = propValue;
+          } else if (attr.type === "JSXSpreadAttribute") {
+            // Handle spread attributes {...props}
+            const spreadValue = evaluateExpression(attr.argument);
+            if (typeof spreadValue === "object" && spreadValue !== null) {
+              Object.assign(props, spreadValue);
+            }
+          }
+        }
+
+        // Parse children
+        const children = node.children
+          .map((child) => parseNode(child as JSXElement | JSXFragment | JSXText | JSXExpressionContainer))
+          .filter((c): c is ComponentNode | string => c !== null);
+
+        return {
+          name,
+          isHtmlElement,
+          props,
+          children,
+        };
+      }
+
+      return null;
+    };
+
+    // Parse the root
+    const rootNode = parseNode(expression);
+
+    if (rootNode === null) {
+      return {
+        tree: [],
+        components: [],
+        errors: ["Failed to parse JSX"],
+      };
+    }
+
+    // If we got a Fragment with multiple children from our wrapper, unwrap it
+    if (
+      typeof rootNode !== "string" &&
+      rootNode.name === "Fragment" &&
+      rootNode.children.length > 0
+    ) {
+      // Check if all children are component nodes
+      const componentChildren = rootNode.children.filter(
+        (c): c is ComponentNode => typeof c !== "string"
+      );
+
+      if (componentChildren.length === 1) {
+        return {
+          tree: componentChildren[0],
+          components: Array.from(components).sort(),
+          errors,
+        };
+      }
+
+      if (componentChildren.length > 1) {
+        return {
+          tree: componentChildren,
+          components: Array.from(components).sort(),
+          errors,
+        };
+      }
+    }
+
+    return {
+      tree: typeof rootNode === "string" ? [] : rootNode,
+      components: Array.from(components).sort(),
+      errors,
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown parse error";
+    return {
+      tree: [],
+      components: [],
+      errors: [message],
+    };
+  }
+}
+
+/**
+ * Get the full name from a JSX member expression (e.g., MyLib.Button)
+ */
+function getMemberExpressionName(node: any): string {
+  if (node.type === "JSXIdentifier") {
+    return node.name;
+  }
+  if (node.type === "JSXMemberExpression") {
+    return `${getMemberExpressionName(node.object)}.${node.property.name}`;
+  }
+  return "Unknown";
+}
+
+/**
+ * Parse a JSX attribute value
+ */
+function parseAttributeValue(attr: JSXAttribute): unknown {
+  const value = attr.value;
+
+  // Boolean attribute (no value means true)
+  if (value === null || value === undefined) {
+    return true;
+  }
+
+  // String literal
+  if (value.type === "StringLiteral") {
+    return (value as { value: string }).value;
+  }
+
+  // Expression container {value}
+  if (value.type === "JSXExpressionContainer") {
+    return evaluateExpression((value as JSXExpressionContainer).expression);
+  }
+
+  // JSX element as attribute value
+  if (value.type === "JSXElement" || value.type === "JSXFragment") {
+    // This would be something like <Component prop={<Other />} />
+    // We'll return a string representation for now
+    return "[JSX Element]";
+  }
+
+  return null;
+}
+
+/**
+ * Evaluate a JavaScript expression from JSX.
+ * This handles common cases but is intentionally limited for safety.
+ */
+function evaluateExpression(expr: Expression | Node): unknown {
+  if (!expr || expr.type === "JSXEmptyExpression") {
+    return null;
+  }
+
+  switch (expr.type) {
+    case "StringLiteral":
+      return expr.value;
+
+    case "NumericLiteral":
+      return expr.value;
+
+    case "BooleanLiteral":
+      return expr.value;
+
+    case "NullLiteral":
+      return null;
+
+    case "Identifier":
+      // Handle special identifiers
+      if (expr.name === "undefined") return undefined;
+      if (expr.name === "true") return true;
+      if (expr.name === "false") return false;
+      // Return the identifier name as a placeholder
+      return `{${expr.name}}`;
+
+    case "TemplateLiteral":
+      // Handle template literals with no expressions
+      if (expr.expressions.length === 0 && expr.quasis.length === 1) {
+        return expr.quasis[0].value.cooked || expr.quasis[0].value.raw;
+      }
+      // For template literals with expressions, return a placeholder
+      return "[Template Literal]";
+
+    case "ObjectExpression":
+      // Parse object literals like {{ key: 'value' }}
+      const obj: Record<string, unknown> = {};
+      for (const prop of expr.properties) {
+        if (prop.type === "ObjectProperty") {
+          const key =
+            prop.key.type === "Identifier"
+              ? prop.key.name
+              : prop.key.type === "StringLiteral"
+              ? prop.key.value
+              : String(prop.key);
+          obj[key] = evaluateExpression(prop.value as Expression);
+        }
+      }
+      return obj;
+
+    case "ArrayExpression":
+      // Parse array literals like {[1, 2, 3]}
+      return expr.elements.map((el) =>
+        el ? evaluateExpression(el as Expression) : null
+      );
+
+    case "ArrowFunctionExpression":
+    case "FunctionExpression":
+      // Return a placeholder for functions
+      return "[Function]";
+
+    case "UnaryExpression":
+      // Handle negation like {-5}
+      if (expr.operator === "-" && expr.argument.type === "NumericLiteral") {
+        return -expr.argument.value;
+      }
+      if (expr.operator === "!" && expr.argument.type === "BooleanLiteral") {
+        return !expr.argument.value;
+      }
+      return null;
+
+    case "ConditionalExpression":
+      // Ternary operator - return a placeholder
+      return "[Conditional]";
+
+    case "LogicalExpression":
+      // && or || - return a placeholder
+      return "[Logical Expression]";
+
+    case "MemberExpression":
+      // Something like obj.prop - return placeholder
+      return "[Member Expression]";
+
+    case "CallExpression":
+      // Function call - return placeholder
+      return "[Function Call]";
+
+    default:
+      return null;
+  }
+}
+
+/**
+ * Extract all component names from a parsed tree
+ */
+export function extractComponents(tree: ComponentNode | ComponentNode[]): string[] {
+  const components = new Set<string>();
+
+  const visit = (node: ComponentNode) => {
+    if (!node.isHtmlElement && node.name !== "Fragment") {
+      components.add(node.name);
+    }
+    for (const child of node.children) {
+      if (typeof child !== "string") {
+        visit(child);
+      }
+    }
+  };
+
+  if (Array.isArray(tree)) {
+    for (const node of tree) {
+      visit(node);
+    }
+  } else {
+    visit(tree);
+  }
+
+  return Array.from(components).sort();
+}
+
+/**
+ * Validate that all components in the tree exist in the available components
+ */
+export function validateComponents(
+  tree: ComponentNode | ComponentNode[],
+  availableComponents: string[]
+): { valid: boolean; missing: string[]; suggestions: Map<string, string[]> } {
+  const used = extractComponents(tree);
+  const available = new Set(availableComponents.map((c) => c.toLowerCase()));
+  const availableOriginal = new Map(
+    availableComponents.map((c) => [c.toLowerCase(), c])
+  );
+
+  const missing: string[] = [];
+  const suggestions = new Map<string, string[]>();
+
+  for (const component of used) {
+    const lower = component.toLowerCase();
+    if (!available.has(lower)) {
+      missing.push(component);
+
+      // Find similar components for suggestions
+      const similar = availableComponents.filter((c) => {
+        const clower = c.toLowerCase();
+        // Check for partial matches
+        return (
+          clower.includes(lower) ||
+          lower.includes(clower) ||
+          levenshteinDistance(lower, clower) <= 2
+        );
+      });
+
+      if (similar.length > 0) {
+        suggestions.set(component, similar.slice(0, 3));
+      }
+    }
+  }
+
+  return {
+    valid: missing.length === 0,
+    missing,
+    suggestions,
+  };
+}
+
+/**
+ * Simple Levenshtein distance for fuzzy matching
+ */
+function levenshteinDistance(a: string, b: string): number {
+  const matrix: number[][] = [];
+
+  for (let i = 0; i <= b.length; i++) {
+    matrix[i] = [i];
+  }
+  for (let j = 0; j <= a.length; j++) {
+    matrix[0][j] = j;
+  }
+
+  for (let i = 1; i <= b.length; i++) {
+    for (let j = 1; j <= a.length; j++) {
+      if (b.charAt(i - 1) === a.charAt(j - 1)) {
+        matrix[i][j] = matrix[i - 1][j - 1];
+      } else {
+        matrix[i][j] = Math.min(
+          matrix[i - 1][j - 1] + 1,
+          matrix[i][j - 1] + 1,
+          matrix[i - 1][j] + 1
+        );
+      }
+    }
+  }
+
+  return matrix[b.length][a.length];
+}

package/src/viewer/postcss.config.js

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};

package/src/viewer/preview-frame-entry.tsx

@@ -0,0 +1,25 @@
+/**
+ * Preview Frame Entry Point
+ *
+ * This is the entry point for the isolated iframe that renders component previews.
+ * It runs inside the iframe and receives render requests from the parent window
+ * via postMessage.
+ */
+
+import { createRoot } from 'react-dom/client';
+import { PreviewFrameHost } from './components/PreviewFrameHost.js';
+
+// Mount the preview host
+const rootElement = document.getElementById('preview-root');
+
+if (rootElement) {
+  const root = createRoot(rootElement);
+  root.render(<PreviewFrameHost />);
+}
+
+// HMR support
+// @ts-expect-error Vite HMR types
+if (import.meta.hot) {
+  // @ts-expect-error Vite HMR types
+  import.meta.hot.accept();
+}

package/src/viewer/preview-frame.html

@@ -0,0 +1,109 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Fragment Preview</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap"
+      rel="stylesheet"
+    />
+    <style>
+      /* Reset and base styles for isolated preview */
+      *, *::before, *::after {
+        box-sizing: border-box;
+      }
+
+      html, body {
+        margin: 0;
+        padding: 0;
+        font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+        -webkit-font-smoothing: antialiased;
+        -moz-osx-font-smoothing: grayscale;
+        width: 100%;
+        height: 100%;
+        overflow: auto;
+      }
+
+      body {
+        background: transparent;
+        min-height: 100%;
+      }
+
+      #preview-root {
+        width: 100%;
+        min-height: 100%;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        padding: 24px;
+        box-sizing: border-box;
+      }
+
+      /* Hide scrollbars but allow scrolling */
+      html::-webkit-scrollbar {
+        width: 0;
+        height: 0;
+      }
+
+      html {
+        scrollbar-width: none;
+      }
+
+      /* Error display styles */
+      .preview-error {
+        padding: 16px;
+        background: #fef2f2;
+        border: 1px solid #fecaca;
+        border-radius: 8px;
+        color: #dc2626;
+        font-size: 14px;
+        max-width: 400px;
+      }
+
+      .preview-error pre {
+        margin: 8px 0 0;
+        padding: 8px;
+        background: #fff;
+        border-radius: 4px;
+        overflow-x: auto;
+        font-size: 12px;
+        font-family: 'JetBrains Mono', ui-monospace, monospace;
+      }
+
+      /* Loading indicator */
+      .preview-loading {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        gap: 8px;
+        color: #6b7280;
+        font-size: 14px;
+      }
+
+      .preview-loading .spinner {
+        width: 20px;
+        height: 20px;
+        border: 2px solid #e5e7eb;
+        border-top-color: #3b82f6;
+        border-radius: 50%;
+        animation: spin 0.8s linear infinite;
+      }
+
+      @keyframes spin {
+        to { transform: rotate(360deg); }
+      }
+    </style>
+  </head>
+  <body>
+    <div id="preview-root">
+      <div class="preview-loading">
+        <div class="spinner"></div>
+        <span>Loading preview...</span>
+      </div>
+    </div>
+    <script type="module" src="/src/preview-frame-entry.tsx"></script>
+  </body>
+</html>

package/src/viewer/render-template.html

@@ -0,0 +1,68 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Segments Render</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap"
+      rel="stylesheet"
+    />
+    <style>
+      /* Reset and base styles for isolated rendering */
+      *, *::before, *::after {
+        box-sizing: border-box;
+      }
+
+      html, body {
+        margin: 0;
+        padding: 0;
+        font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+        -webkit-font-smoothing: antialiased;
+        -moz-osx-font-smoothing: grayscale;
+      }
+
+      body {
+        background: #ffffff;
+        min-height: 100vh;
+      }
+
+      #render-root {
+        padding: 16px;
+        display: inline-block;
+      }
+
+      /* Signal that rendering is complete */
+      #render-root.ready {
+        /* Used by Playwright to know when to capture */
+      }
+
+      /* Error display */
+      .render-error {
+        padding: 16px;
+        background: #fef2f2;
+        border: 1px solid #fecaca;
+        border-radius: 8px;
+        color: #dc2626;
+        font-size: 14px;
+      }
+
+      .render-error pre {
+        margin: 8px 0 0;
+        padding: 8px;
+        background: #fff;
+        border-radius: 4px;
+        overflow-x: auto;
+        font-size: 12px;
+        font-family: 'JetBrains Mono', monospace;
+      }
+    </style>
+    <!-- PROJECT_STYLES_PLACEHOLDER -->
+  </head>
+  <body>
+    <div id="render-root"></div>
+    <!-- RENDER_SCRIPT_PLACEHOLDER -->
+  </body>
+</html>