@fragments-sdk/cli 0.2.2

package/src/viewer/composition-renderer.ts

@@ -0,0 +1,381 @@
+/**
+ * Composition Renderer
+ *
+ * Generates render scripts for multi-component compositions.
+ * Takes a parsed JSX component tree and generates code that can
+ * render the composition in an isolated browser context.
+ */
+
+import type { ComponentNode } from "./jsx-parser.js";
+
+/**
+ * Segment file information for component lookup
+ */
+export interface SegmentFileInfo {
+  absolutePath: string;
+  relativePath: string;
+  componentName: string;
+}
+
+/**
+ * Options for generating a composition render script
+ */
+export interface CompositionRenderOptions {
+  /** The parsed component tree */
+  tree: ComponentNode | ComponentNode[];
+  /** Map of component names to their segment file paths */
+  componentPaths: Map<string, string>;
+  /** Optional theme ('light' or 'dark') */
+  theme?: "light" | "dark";
+}
+
+/**
+ * Generate a render script for a composition.
+ *
+ * This generates JavaScript code that:
+ * 1. Imports all required components in parallel
+ * 2. Builds a component map
+ * 3. Renders the nested composition using React.createElement
+ *
+ * @param options - The render options
+ * @returns JavaScript code string ready to be injected into an HTML page
+ */
+export function generateCompositionRenderScript(
+  options: CompositionRenderOptions
+): string {
+  const { tree, componentPaths, theme = "light" } = options;
+
+  // Extract all unique component names that need to be imported
+  const componentsToImport = getUniqueComponents(tree);
+
+  // Generate import statements
+  const imports = componentsToImport
+    .map((name) => {
+      const path = componentPaths.get(name);
+      if (!path) {
+        return `  // Component "${name}" not found - will use placeholder`;
+      }
+      return `  import("${path}").then(m => ({ name: "${name}", mod: m }))`;
+    })
+    .join(",\n");
+
+  // Generate the createElement tree
+  const createElementCode = generateCreateElementTree(tree);
+
+  return `
+import React from "react";
+import { createRoot } from "react-dom/client";
+
+async function render() {
+  const root = document.getElementById("render-root");
+
+  // Apply theme
+  document.documentElement.classList.toggle("dark", ${theme === "dark"});
+
+  try {
+    // Parallel import all needed components
+    const componentPromises = [
+${imports}
+    ].filter(Boolean);
+
+    const loadedComponents = await Promise.all(componentPromises);
+
+    // Build component map
+    const C = {};
+    for (const item of loadedComponents) {
+      if (item && item.mod) {
+        // Handle both default export and named component export
+        const segment = item.mod.default;
+        if (segment && segment.component) {
+          C[item.name] = segment.component;
+        } else if (typeof item.mod.default === "function") {
+          C[item.name] = item.mod.default;
+        }
+      }
+    }
+
+    // Placeholder component for missing components
+    const Placeholder = ({ name, children }) => {
+      return React.createElement("div", {
+        style: {
+          border: "2px dashed #e5e7eb",
+          borderRadius: "8px",
+          padding: "16px",
+          margin: "8px 0",
+          backgroundColor: "#f9fafb",
+          color: "#6b7280",
+          fontSize: "14px",
+          fontFamily: "system-ui, sans-serif",
+        }
+      },
+        React.createElement("div", { style: { fontWeight: 500, marginBottom: "4px" } }, "Missing: " + name),
+        children
+      );
+    };
+
+    // Helper to get component or placeholder
+    const getComponent = (name) => {
+      return C[name] || ((props) => React.createElement(Placeholder, { name, ...props }));
+    };
+
+    // Render composition
+    const reactRoot = createRoot(root);
+    const composition = ${createElementCode};
+    reactRoot.render(composition);
+
+    // Signal that rendering is complete
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => {
+        root.classList.add("ready");
+        window.__RENDER_READY__ = true;
+        window.__RENDER_COMPONENTS__ = ${JSON.stringify(componentsToImport)};
+      });
+    });
+  } catch (error) {
+    console.error("Composition render error:", error);
+    root.innerHTML = \`
+      <div class="render-error" style="
+        padding: 20px;
+        background: #fef2f2;
+        border: 1px solid #fecaca;
+        border-radius: 8px;
+        color: #991b1b;
+        font-family: system-ui, sans-serif;
+      ">
+        <strong style="display: block; margin-bottom: 8px;">Render Error</strong>
+        <pre style="
+          background: #fee2e2;
+          padding: 12px;
+          border-radius: 4px;
+          overflow: auto;
+          font-size: 13px;
+          margin: 0;
+        ">\${error.message}</pre>
+      </div>
+    \`;
+    root.classList.add("ready");
+    window.__RENDER_READY__ = true;
+    window.__RENDER_ERROR__ = error.message;
+  }
+}
+
+render();
+`;
+}
+
+/**
+ * Get all unique component names from a tree
+ */
+function getUniqueComponents(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();
+}
+
+/**
+ * Generate React.createElement tree from parsed component tree
+ */
+function generateCreateElementTree(
+  tree: ComponentNode | ComponentNode[]
+): string {
+  if (Array.isArray(tree)) {
+    if (tree.length === 0) {
+      return "null";
+    }
+    if (tree.length === 1) {
+      return generateCreateElementNode(tree[0]);
+    }
+    // Multiple root elements - wrap in Fragment
+    const children = tree.map(generateCreateElementNode).join(",\n      ");
+    return `React.createElement(React.Fragment, null,\n      ${children}\n    )`;
+  }
+
+  return generateCreateElementNode(tree);
+}
+
+/**
+ * Generate a single React.createElement call
+ */
+function generateCreateElementNode(node: ComponentNode): string {
+  const { name, isHtmlElement, props, children } = node;
+
+  // Determine the element type
+  let elementType: string;
+  if (isHtmlElement) {
+    elementType = `"${name}"`;
+  } else if (name === "Fragment") {
+    elementType = "React.Fragment";
+  } else {
+    elementType = `getComponent("${name}")`;
+  }
+
+  // Serialize props
+  const propsCode = serializeProps(props);
+
+  // Generate children
+  if (children.length === 0) {
+    return `React.createElement(${elementType}, ${propsCode})`;
+  }
+
+  const childrenCode = children
+    .map((child) => {
+      if (typeof child === "string") {
+        return JSON.stringify(child);
+      }
+      return generateCreateElementNode(child);
+    })
+    .join(",\n        ");
+
+  return `React.createElement(${elementType}, ${propsCode},\n        ${childrenCode}\n      )`;
+}
+
+/**
+ * Serialize props object to JavaScript code
+ */
+function serializeProps(props: Record<string, unknown>): string {
+  const entries = Object.entries(props);
+
+  if (entries.length === 0) {
+    return "null";
+  }
+
+  const propsStr = entries
+    .map(([key, value]) => {
+      const serializedValue = serializeValue(value);
+      // Use computed property name if key contains special characters
+      if (/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key)) {
+        return `${key}: ${serializedValue}`;
+      }
+      return `${JSON.stringify(key)}: ${serializedValue}`;
+    })
+    .join(", ");
+
+  return `{ ${propsStr} }`;
+}
+
+/**
+ * Serialize a value to JavaScript code
+ */
+function serializeValue(value: unknown): string {
+  if (value === null) return "null";
+  if (value === undefined) return "undefined";
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "number") return String(value);
+  if (typeof value === "boolean") return String(value);
+
+  if (Array.isArray(value)) {
+    const items = value.map(serializeValue).join(", ");
+    return `[${items}]`;
+  }
+
+  if (typeof value === "object") {
+    const entries = Object.entries(value)
+      .map(([k, v]) => `${JSON.stringify(k)}: ${serializeValue(v)}`)
+      .join(", ");
+    return `{ ${entries} }`;
+  }
+
+  // For placeholders like [Function] or {variable}
+  if (typeof value === "string" && value.startsWith("[") && value.endsWith("]")) {
+    // Return a no-op function for function placeholders
+    if (value === "[Function]") {
+      return "() => {}";
+    }
+    return "null";
+  }
+
+  // For identifier references like {variable}
+  if (typeof value === "string" && value.startsWith("{") && value.endsWith("}")) {
+    return "null"; // Can't resolve variables in this context
+  }
+
+  return "undefined";
+}
+
+/**
+ * Build a map of component names to their segment file paths
+ */
+export function buildComponentPathMap(
+  components: string[],
+  segments: Array<{ path: string; name: string; absolutePath: string }>
+): Map<string, string> {
+  const map = new Map<string, string>();
+
+  for (const component of components) {
+    const segment = segments.find(
+      (s) => s.name.toLowerCase() === component.toLowerCase()
+    );
+    if (segment) {
+      map.set(component, segment.absolutePath);
+    }
+  }
+
+  return map;
+}
+
+/**
+ * Generate a simple composition preview HTML
+ */
+export function generateCompositionPreviewHTML(
+  jsx: string,
+  theme: "light" | "dark" = "light"
+): string {
+  return `
+<!DOCTYPE html>
+<html lang="en" class="${theme === "dark" ? "dark" : ""}">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Composition Preview</title>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body {
+      font-family: system-ui, -apple-system, sans-serif;
+      background: ${theme === "dark" ? "#1a1a1a" : "#ffffff"};
+      color: ${theme === "dark" ? "#ffffff" : "#000000"};
+      min-height: 100vh;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      padding: 20px;
+    }
+    #render-root {
+      width: 100%;
+      max-width: 100%;
+    }
+    #render-root.ready { opacity: 1; }
+    .render-error {
+      padding: 20px;
+      background: #fef2f2;
+      border: 1px solid #fecaca;
+      border-radius: 8px;
+      color: #991b1b;
+    }
+  </style>
+</head>
+<body>
+  <div id="render-root"></div>
+  <!-- RENDER_SCRIPT_PLACEHOLDER -->
+</body>
+</html>
+`;
+}

package/src/viewer/constants/index.ts

@@ -0,0 +1 @@
+export * from './ui.js';

package/src/viewer/constants/ui.ts

@@ -0,0 +1,185 @@
+/**
+ * Shared UI constants for consistent styling across the viewer.
+ * Single source of truth for colors, status styles, and other UI config.
+ */
+
+import { BRAND } from '../../core/index.js';
+
+/**
+ * Component status definitions with consistent styling.
+ * Used in sidebar badges, component header, and filters.
+ */
+export const STATUS_CONFIG = {
+  stable: {
+    label: 'Stable',
+    badge: 'badge-success',
+    bg: 'bg-emerald-500/15',
+    text: 'text-emerald-600 dark:text-emerald-400',
+    border: 'border-emerald-500/30',
+  },
+  experimental: {
+    label: 'Experimental',
+    badge: 'badge-warning',
+    bg: 'bg-purple-500/15',
+    text: 'text-purple-600 dark:text-purple-400',
+    border: 'border-purple-500/30',
+  },
+  deprecated: {
+    label: 'Deprecated',
+    badge: 'badge-danger',
+    bg: 'bg-red-500/15',
+    text: 'text-red-600 dark:text-red-400',
+    border: 'border-red-500/30',
+  },
+  beta: {
+    label: 'Beta',
+    badge: 'badge-warning',
+    bg: 'bg-amber-500/15',
+    text: 'text-amber-600 dark:text-amber-400',
+    border: 'border-amber-500/30',
+  },
+} as const;
+
+export type ComponentStatus = keyof typeof STATUS_CONFIG;
+
+/**
+ * Get status config with fallback for unknown statuses.
+ */
+export function getStatusConfig(status: string | undefined) {
+  if (!status) return null;
+  return STATUS_CONFIG[status as ComponentStatus] || {
+    label: status,
+    badge: 'badge-default',
+    bg: 'bg-gray-500/15',
+    text: 'text-gray-600 dark:text-gray-400',
+    border: 'border-gray-500/30',
+  };
+}
+
+/**
+ * Relationship type styling for related components.
+ */
+export const RELATIONSHIP_CONFIG = {
+  alternative: {
+    label: 'Alternative',
+    bg: 'bg-blue-500/10',
+    text: 'text-blue-500',
+  },
+  parent: {
+    label: 'Parent',
+    bg: 'bg-purple-500/10',
+    text: 'text-purple-500',
+  },
+  child: {
+    label: 'Child',
+    bg: 'bg-emerald-500/10',
+    text: 'text-emerald-500',
+  },
+  sibling: {
+    label: 'Sibling',
+    bg: 'bg-amber-500/10',
+    text: 'text-amber-500',
+  },
+  related: {
+    label: 'Related',
+    bg: 'bg-[--bg-tertiary]',
+    text: 'text-secondary',
+  },
+  composition: {
+    label: 'Uses',
+    bg: 'bg-cyan-500/10',
+    text: 'text-cyan-500',
+  },
+} as const;
+
+export type RelationshipType = keyof typeof RELATIONSHIP_CONFIG;
+
+/**
+ * Get relationship config with fallback.
+ */
+export function getRelationshipConfig(relationship: string) {
+  return RELATIONSHIP_CONFIG[relationship as RelationshipType] || RELATIONSHIP_CONFIG.related;
+}
+
+/**
+ * Preview background options.
+ */
+export const BACKGROUND_OPTIONS = ['white', 'black', 'checkerboard', 'transparent'] as const;
+export type BackgroundOption = (typeof BACKGROUND_OPTIONS)[number];
+
+/**
+ * Zoom level options.
+ */
+export const ZOOM_LEVELS = [50, 75, 100, 150, 200] as const;
+export type ZoomLevel = (typeof ZOOM_LEVELS)[number];
+
+/**
+ * Viewport presets.
+ */
+export const VIEWPORT_PRESETS = {
+  responsive: { label: 'Responsive', width: null, icon: '↔' },
+  desktop: { label: 'Desktop', width: 1280, icon: '🖥' },
+  tablet: { label: 'Tablet', width: 768, icon: '📱' },
+  mobile: { label: 'Mobile', width: 375, icon: '📱' },
+} as const;
+
+export type ViewportPreset = keyof typeof VIEWPORT_PRESETS | 'custom';
+
+/**
+ * Get CSS background style for preview pane.
+ */
+export function getBackgroundStyle(bg: BackgroundOption): React.CSSProperties {
+  switch (bg) {
+    case 'white':
+      return { backgroundColor: '#ffffff' };
+    case 'black':
+      return { backgroundColor: '#000000' };
+    case 'transparent':
+      return { backgroundColor: 'transparent' };
+    case 'checkerboard':
+      return {
+        backgroundColor: '#ffffff',
+        backgroundImage: `
+          linear-gradient(45deg, #e5e5e5 25%, transparent 25%),
+          linear-gradient(-45deg, #e5e5e5 25%, transparent 25%),
+          linear-gradient(45deg, transparent 75%, #e5e5e5 75%),
+          linear-gradient(-45deg, transparent 75%, #e5e5e5 75%)
+        `,
+        backgroundSize: '16px 16px',
+        backgroundPosition: '0 0, 0 8px, 8px -8px, -8px 0px',
+      };
+    default:
+      return { backgroundColor: '#ffffff' };
+  }
+}
+
+/**
+ * Storage keys for localStorage persistence.
+ */
+export const STORAGE_KEYS = {
+  theme: `${BRAND.storagePrefix}theme`,
+  collapsedCategories: `${BRAND.storagePrefix}collapsed-categories`,
+} as const;
+
+/**
+ * HMR connection status.
+ */
+export const HMR_STATUS = {
+  connected: {
+    label: 'Connected',
+    color: 'text-emerald-500',
+    bg: 'bg-emerald-500',
+  },
+  reconnecting: {
+    label: 'Reconnecting...',
+    color: 'text-amber-500',
+    bg: 'bg-amber-500',
+  },
+  disconnected: {
+    label: 'Disconnected',
+    color: 'text-red-500',
+    bg: 'bg-red-500',
+  },
+} as const;
+
+export type HmrStatus = keyof typeof HMR_STATUS;