@fragments-sdk/cli 0.2.2

package/src/viewer/render-utils.ts

@@ -0,0 +1,170 @@
+/**
+ * Render utilities for AI preview endpoint.
+ * Generates code to render design system components in isolation.
+ */
+
+export interface RenderRequest {
+  /** Component name (e.g., "Button", "Card") */
+  component: string;
+  /** Props to pass to the component */
+  props?: Record<string, unknown>;
+  /** Viewport dimensions */
+  viewport?: {
+    width: number;
+    height: number;
+  };
+}
+
+export interface SegmentInfo {
+  name: string;
+  path: string;
+}
+
+/**
+ * Serialize a value to JavaScript code string.
+ * Handles strings, numbers, booleans, null, undefined, arrays, and objects.
+ */
+export 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)) {
+    return `[${value.map(serializeValue).join(", ")}]`;
+  }
+  if (typeof value === "object") {
+    const entries = Object.entries(value)
+      .map(([k, v]) => `${JSON.stringify(k)}: ${serializeValue(v)}`)
+      .join(", ");
+    return `{${entries}}`;
+  }
+  // Functions and other types - skip
+  return "undefined";
+}
+
+/**
+ * Serialize props object to JSX attribute string.
+ * Example: { variant: "primary", disabled: true } -> variant="primary" disabled={true}
+ */
+export function serializePropsToJsx(props: Record<string, unknown>): string {
+  return Object.entries(props)
+    .filter(([_, v]) => v !== undefined)
+    .map(([key, value]) => {
+      if (typeof value === "string") {
+        return `${key}=${JSON.stringify(value)}`;
+      }
+      return `${key}={${serializeValue(value)}}`;
+    })
+    .join(" ");
+}
+
+/**
+ * Find a segment by component name.
+ * Returns the segment info if found, null otherwise.
+ */
+export function findSegmentByName(
+  componentName: string,
+  segments: Array<{ path: string; segment: { meta: { name: string } } }>
+): SegmentInfo | null {
+  const match = segments.find(
+    (s) => s.segment.meta.name.toLowerCase() === componentName.toLowerCase()
+  );
+
+  if (!match) return null;
+
+  return {
+    name: match.segment.meta.name,
+    path: match.path,
+  };
+}
+
+/**
+ * Get list of available component names from loaded segments.
+ */
+export function getAvailableComponents(
+  segments: Array<{ segment: { meta: { name: string } } }>
+): string[] {
+  return segments.map((s) => s.segment.meta.name).sort();
+}
+
+/**
+ * Generate the render script that will be injected into the template.
+ * This script imports the component and renders it with the given props.
+ */
+export function generateRenderScript(
+  segmentPath: string,
+  componentName: string,
+  props: Record<string, unknown> = {}
+): string {
+  const propsJsx = serializePropsToJsx(props);
+  const propsString = propsJsx ? ` ${propsJsx}` : "";
+
+  // Handle children prop specially - render as content between tags
+  const hasChildren = "children" in props && props.children !== undefined;
+  const childrenContent = hasChildren ? String(props.children) : "";
+  const propsWithoutChildren = { ...props };
+  delete propsWithoutChildren.children;
+  const propsJsxNoChildren = serializePropsToJsx(propsWithoutChildren);
+  const propsStringNoChildren = propsJsxNoChildren ? ` ${propsJsxNoChildren}` : "";
+
+  return `
+import React from "react";
+import { createRoot } from "react-dom/client";
+
+// Import the segment to get the component
+async function render() {
+  const root = document.getElementById("render-root");
+
+  try {
+    // Dynamic import of the segment file
+    const segmentModule = await import("${segmentPath}");
+    const segment = segmentModule.default;
+
+    if (!segment || !segment.component) {
+      throw new Error("Segment does not export a component");
+    }
+
+    const Component = segment.component;
+
+    // Create React root and render
+    const reactRoot = createRoot(root);
+    ${
+      hasChildren
+        ? `reactRoot.render(React.createElement(Component, ${JSON.stringify(propsWithoutChildren)}, ${JSON.stringify(childrenContent)}));`
+        : `reactRoot.render(React.createElement(Component, ${JSON.stringify(props)}));`
+    }
+
+    // Signal that rendering is complete
+    // Wait a frame for React to flush
+    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 virtual module ID for a render request.
+ * This creates a unique ID that Vite can resolve.
+ */
+export function generateRenderModuleId(componentName: string, requestId: string): string {
+  return `virtual:segments-render-${componentName}-${requestId}`;
+}

package/src/viewer/server.ts

@@ -0,0 +1,276 @@
+/**
+ * Segments Dev Server
+ *
+ * Runs a Vite dev server that:
+ * 1. Uses the project's existing Vite/build configuration
+ * 2. Has access to all project dependencies
+ * 3. Can render actual components with proper styling
+ * 4. Supports HMR for segment file changes
+ *
+ * This is the "Storybook-like" experience for Segments.
+ */
+
+import {
+  createServer,
+  mergeConfig,
+  loadConfigFromFile,
+  type ViteDevServer,
+  type InlineConfig,
+} from "vite";
+import react from "@vitejs/plugin-react";
+import tailwindcss from "tailwindcss";
+import autoprefixer from "autoprefixer";
+import { resolve, dirname, join } from "node:path";
+import { existsSync, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { loadConfig, discoverSegmentFiles } from "../core/node.js";
+import { segmentsPlugin } from "./vite-plugin.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const viewerRoot = resolve(__dirname, "..");
+const viewerTailwindConfig = resolve(viewerRoot, "tailwind.config.js");
+// The monorepo packages directory (sibling packages)
+const packagesRoot = resolve(viewerRoot, "..");
+
+export interface DevServerOptions {
+  /** Port to run the server on */
+  port?: number;
+  /** Path to segments config file */
+  configPath?: string;
+  /** Open browser on start */
+  open?: boolean;
+  /** Project root (defaults to cwd) */
+  projectRoot?: string;
+}
+
+/**
+ * Create and start the Segments dev server.
+ *
+ * The server runs WITHIN the project's context, meaning:
+ * - All project dependencies are available
+ * - SCSS, CSS modules, etc. work automatically
+ * - Path aliases from tsconfig.json work
+ * - Components render exactly as they would in the app
+ */
+export async function createDevServer(
+  options: DevServerOptions = {}
+): Promise<ViteDevServer> {
+  const startTime = performance.now();
+  const {
+    port = 6006,
+    configPath,
+    open = true,
+    projectRoot = process.cwd(),
+  } = options;
+
+  console.log("\n🔧 Loading configuration...");
+
+  // Load segments config
+  const { config, configDir } = await loadConfig(configPath);
+
+  // Discover segment files
+  const segmentFiles = await discoverSegmentFiles(config, configDir);
+  console.log(`📦 Found ${segmentFiles.length} fragment file(s)`);
+
+  // Try to load project's Vite config
+  let projectViteConfig: InlineConfig = {};
+  const viteConfigPath = findViteConfig(projectRoot);
+
+  if (viteConfigPath) {
+    console.log(`📄 Using project Vite config: ${viteConfigPath}`);
+    try {
+      const loaded = await loadConfigFromFile(
+        { command: "serve", mode: "development" },
+        viteConfigPath,
+        projectRoot
+      );
+      if (loaded) {
+        projectViteConfig = loaded.config;
+      }
+    } catch (error) {
+      console.warn("⚠️  Could not load project Vite config:", error);
+    }
+  } else {
+    console.log("ℹ️  No project Vite config found, using defaults");
+  }
+
+  // Find node_modules (handles monorepo setups)
+  const nodeModulesPath = findNodeModules(projectRoot);
+  console.log(`📁 Using node_modules: ${nodeModulesPath}`);
+
+  // Our Segments-specific configuration
+  const segmentsConfig: InlineConfig = {
+    configFile: false, // Don't load config again
+    root: projectRoot, // Run from PROJECT root
+    base: "/",
+
+    server: {
+      port,
+      open: open ? "/fragments/" : false,
+      fs: {
+        // Allow serving files from viewer package, project, and node_modules root
+        allow: [viewerRoot, projectRoot, configDir, dirname(nodeModulesPath)],
+      },
+    },
+
+    plugins: [
+      // React support (if not already in project config)
+      ...(hasReactPlugin(projectViteConfig) ? [] : [react()]),
+
+      // Segments plugins (array including SVGR)
+      ...segmentsPlugin({
+        segmentFiles,
+        config,
+        projectRoot,
+      }),
+    ],
+
+    // CSS configuration for viewer's Tailwind
+    css: {
+      postcss: {
+        plugins: [
+          tailwindcss({
+            config: viewerTailwindConfig,
+          }),
+          autoprefixer(),
+        ],
+      },
+    },
+
+    optimizeDeps: {
+      // Include common dependencies for faster startup
+      include: ["react", "react-dom", "react/jsx-runtime", "react/jsx-dev-runtime"],
+    },
+
+    // Ensure we can resolve viewer's dependencies
+    resolve: {
+      // Dedupe ensures all imports of these packages resolve to the same copy
+      dedupe: ["react", "react-dom"],
+      alias: {
+        // Allow importing from viewer package
+        "@fragments/viewer": viewerRoot,
+        // Ensure ALL react imports resolve to project's node_modules
+        // This is critical for viewer files loaded from outside project root
+        "react": safeRealpath(join(nodeModulesPath, "react")),
+        "react-dom": safeRealpath(join(nodeModulesPath, "react-dom")),
+        "react/jsx-runtime": safeRealpath(join(nodeModulesPath, "react/jsx-runtime")),
+        "react/jsx-dev-runtime": safeRealpath(join(nodeModulesPath, "react/jsx-dev-runtime")),
+        // Resolve @fragments packages - try project's node_modules first, fall back to monorepo
+        "@fragments/core": resolveFragmentsPackage("core", nodeModulesPath),
+      },
+    },
+  };
+
+  // Merge project config with our config
+  // Project config takes precedence for most things
+  const mergedConfig = mergeConfig(projectViteConfig, segmentsConfig);
+
+  console.log("🚀 Starting dev server...\n");
+
+  // Create and start the server
+  const server = await createServer(mergedConfig);
+  await server.listen();
+
+  // Log startup time
+  const startupTime = ((performance.now() - startTime) / 1000).toFixed(2);
+  console.log(`⚡ Server ready in ${startupTime}s`);
+
+  return server;
+}
+
+/**
+ * Resolve symlinks to real paths, with fallback.
+ */
+function safeRealpath(p: string): string {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+/**
+ * Resolve @fragments packages with fallback to monorepo packages.
+ * This handles the case where the viewer is served from the fragments monorepo
+ * but the user's project doesn't have @fragments packages installed.
+ */
+function resolveFragmentsPackage(packageName: string, nodeModulesPath: string): string {
+  // Try project's node_modules first
+  const projectPath = join(nodeModulesPath, `@fragments/${packageName}/dist/index.js`);
+  if (existsSync(projectPath)) {
+    return safeRealpath(projectPath);
+  }
+
+  // Fall back to monorepo packages (sibling to viewer)
+  const monorepoPath = resolve(packagesRoot, packageName, "dist/index.js");
+  if (existsSync(monorepoPath)) {
+    return safeRealpath(monorepoPath);
+  }
+
+  // Return project path anyway (will error with helpful message)
+  return projectPath;
+}
+
+/**
+ * Find node_modules directory by walking up from projectRoot.
+ * This handles monorepo setups where node_modules is at the root.
+ */
+function findNodeModules(startDir: string): string {
+  let current = startDir;
+  while (current !== dirname(current)) {
+    const nodeModulesPath = join(current, "node_modules");
+    if (existsSync(join(nodeModulesPath, "react"))) {
+      return nodeModulesPath;
+    }
+    current = dirname(current);
+  }
+  // Fallback to projectRoot/node_modules
+  return join(startDir, "node_modules");
+}
+
+/**
+ * Find Vite config file in project.
+ */
+function findViteConfig(projectRoot: string): string | null {
+  const configFiles = [
+    "vite.config.ts",
+    "vite.config.js",
+    "vite.config.mts",
+    "vite.config.mjs",
+  ];
+
+  for (const file of configFiles) {
+    const path = join(projectRoot, file);
+    if (existsSync(path)) {
+      return path;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Check if project config already has React plugin.
+ */
+function hasReactPlugin(config: InlineConfig): boolean {
+  if (!config.plugins) return false;
+
+  const plugins = Array.isArray(config.plugins)
+    ? config.plugins
+    : [config.plugins];
+
+  return plugins.some((plugin) => {
+    if (!plugin) return false;
+    if (Array.isArray(plugin)) {
+      return plugin.some(
+        (p) =>
+          p && typeof p === "object" && "name" in p && p.name?.includes("react")
+      );
+    }
+    return (
+      typeof plugin === "object" &&
+      "name" in plugin &&
+      plugin.name?.includes("react")
+    );
+  });
+}