@fragments-sdk/cli 0.7.14 → 0.7.16

package/src/commands/init-framework.ts

@@ -0,0 +1,414 @@
+/**
+ * Framework detection and auto-configuration for fragments init.
+ *
+ * Detects the consumer's framework (Next.js, Vite, Remix, Astro)
+ * and generates appropriate configuration files.
+ */
+
+import { readFile, writeFile, access } from "node:fs/promises";
+import { join } from "node:path";
+import pc from "picocolors";
+
+// ============================================
+// Types
+// ============================================
+
+export type Framework = "nextjs" | "vite" | "remix" | "astro" | "unknown";
+
+export interface FrameworkDetection {
+  framework: Framework;
+  /** Package that triggered the detection */
+  detectedBy: string | null;
+}
+
+export interface FrameworkSetupOptions {
+  /** Project root directory */
+  projectRoot: string;
+  /** Override auto-detected framework */
+  framework?: Framework;
+  /** Seed overrides for globals.scss generation */
+  seeds?: {
+    brand?: string;
+    neutral?: string;
+    density?: string;
+    radiusStyle?: string;
+  };
+}
+
+export interface FrameworkSetupResult {
+  framework: Framework;
+  filesCreated: string[];
+  packagesToInstall: string[];
+  configModified: string[];
+  warnings: string[];
+}
+
+// ============================================
+// Framework Detection
+// ============================================
+
+/**
+ * Detect framework from package.json dependencies
+ */
+export async function detectFramework(
+  projectRoot: string
+): Promise<FrameworkDetection> {
+  try {
+    const pkgPath = join(projectRoot, "package.json");
+    const pkgContent = await readFile(pkgPath, "utf-8");
+    const pkg = JSON.parse(pkgContent);
+
+    const allDeps = {
+      ...pkg.dependencies,
+      ...pkg.devDependencies,
+    };
+
+    // Check in order of specificity
+    if (allDeps["next"]) {
+      return { framework: "nextjs", detectedBy: "next" };
+    }
+    if (allDeps["@remix-run/react"]) {
+      return { framework: "remix", detectedBy: "@remix-run/react" };
+    }
+    if (allDeps["astro"]) {
+      return { framework: "astro", detectedBy: "astro" };
+    }
+    if (allDeps["vite"]) {
+      return { framework: "vite", detectedBy: "vite" };
+    }
+
+    return { framework: "unknown", detectedBy: null };
+  } catch {
+    return { framework: "unknown", detectedBy: null };
+  }
+}
+
+// ============================================
+// Globals SCSS Generation
+// ============================================
+
+function generateGlobalsSCSS(seeds?: FrameworkSetupOptions["seeds"]): string {
+  const withClauses: string[] = [];
+
+  if (seeds?.brand) {
+    withClauses.push(`  $fui-brand: ${seeds.brand}`);
+  }
+  if (seeds?.neutral) {
+    withClauses.push(`  $fui-neutral: "${seeds.neutral}"`);
+  }
+  if (seeds?.density) {
+    withClauses.push(`  $fui-density: "${seeds.density}"`);
+  }
+  if (seeds?.radiusStyle) {
+    withClauses.push(`  $fui-radius-style: "${seeds.radiusStyle}"`);
+  }
+
+  const useStatement =
+    withClauses.length > 0
+      ? `@use '@fragments-sdk/ui/styles' with (\n${withClauses.join(",\n")}\n);`
+      : `@use '@fragments-sdk/ui/styles';`;
+
+  return `// Fragments SDK Global Styles
+// Customize seed values to theme the entire design system.
+// See: https://usefragments.com/docs/theming
+${useStatement}
+`;
+}
+
+// ============================================
+// Providers Component Generation
+// ============================================
+
+function generateProviders(): string {
+  return `'use client';
+
+import { ThemeProvider } from '@fragments-sdk/ui';
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <ThemeProvider defaultTheme="system" attribute="data-theme">
+      {children}
+    </ThemeProvider>
+  );
+}
+`;
+}
+
+// ============================================
+// Per-Framework Configuration
+// ============================================
+
+async function setupNextJS(
+  projectRoot: string,
+  options: FrameworkSetupOptions
+): Promise<FrameworkSetupResult> {
+  const result: FrameworkSetupResult = {
+    framework: "nextjs",
+    filesCreated: [],
+    packagesToInstall: [],
+    configModified: [],
+    warnings: [],
+  };
+
+  // Check if sass is installed
+  try {
+    const pkgContent = await readFile(
+      join(projectRoot, "package.json"),
+      "utf-8"
+    );
+    const pkg = JSON.parse(pkgContent);
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (!allDeps["sass"]) {
+      result.packagesToInstall.push("sass");
+    }
+  } catch {
+    // Proceed without checking
+  }
+
+  // Update next.config if transpilePackages is needed
+  const nextConfigPaths = [
+    "next.config.ts",
+    "next.config.mjs",
+    "next.config.js",
+  ];
+
+  for (const configName of nextConfigPaths) {
+    const configPath = join(projectRoot, configName);
+    try {
+      await access(configPath);
+      const content = await readFile(configPath, "utf-8");
+
+      if (!content.includes("transpilePackages")) {
+        // Add transpilePackages to the config
+        if (content.includes("const nextConfig")) {
+          const updated = content.replace(
+            /const nextConfig\s*=\s*\{/,
+            `const nextConfig = {\n  transpilePackages: ['@fragments-sdk/ui'],`
+          );
+          await writeFile(configPath, updated, "utf-8");
+          result.configModified.push(configName);
+        } else {
+          result.warnings.push(
+            `Could not auto-modify ${configName}. Add transpilePackages: ['@fragments-sdk/ui'] manually.`
+          );
+        }
+      }
+      break;
+    } catch {
+      continue;
+    }
+  }
+
+  // Generate globals.scss
+  const globalsPath = join(projectRoot, "src", "styles", "globals.scss");
+  try {
+    await access(globalsPath);
+    result.warnings.push(
+      "src/styles/globals.scss already exists. Skipped generation."
+    );
+  } catch {
+    await writeFile(globalsPath, generateGlobalsSCSS(options.seeds), "utf-8");
+    result.filesCreated.push("src/styles/globals.scss");
+  }
+
+  // Generate providers.tsx
+  const providersPath = join(projectRoot, "src", "providers.tsx");
+  try {
+    await access(providersPath);
+    result.warnings.push("src/providers.tsx already exists. Skipped.");
+  } catch {
+    await writeFile(providersPath, generateProviders(), "utf-8");
+    result.filesCreated.push("src/providers.tsx");
+  }
+
+  return result;
+}
+
+async function setupVite(
+  projectRoot: string,
+  options: FrameworkSetupOptions
+): Promise<FrameworkSetupResult> {
+  const result: FrameworkSetupResult = {
+    framework: "vite",
+    filesCreated: [],
+    packagesToInstall: [],
+    configModified: [],
+    warnings: [],
+  };
+
+  // Check if sass is installed
+  try {
+    const pkgContent = await readFile(
+      join(projectRoot, "package.json"),
+      "utf-8"
+    );
+    const pkg = JSON.parse(pkgContent);
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (!allDeps["sass"]) {
+      result.packagesToInstall.push("sass");
+    }
+  } catch {
+    // Proceed
+  }
+
+  // Generate globals.scss
+  const globalsPath = join(projectRoot, "src", "styles", "globals.scss");
+  try {
+    await access(globalsPath);
+    result.warnings.push(
+      "src/styles/globals.scss already exists. Skipped generation."
+    );
+  } catch {
+    await writeFile(globalsPath, generateGlobalsSCSS(options.seeds), "utf-8");
+    result.filesCreated.push("src/styles/globals.scss");
+  }
+
+  // Generate providers.tsx
+  const providersPath = join(projectRoot, "src", "providers.tsx");
+  try {
+    await access(providersPath);
+    result.warnings.push("src/providers.tsx already exists. Skipped.");
+  } catch {
+    await writeFile(providersPath, generateProviders(), "utf-8");
+    result.filesCreated.push("src/providers.tsx");
+  }
+
+  return result;
+}
+
+async function setupRemix(
+  projectRoot: string,
+  options: FrameworkSetupOptions
+): Promise<FrameworkSetupResult> {
+  const result: FrameworkSetupResult = {
+    framework: "remix",
+    filesCreated: [],
+    packagesToInstall: [],
+    configModified: [],
+    warnings: [],
+  };
+
+  result.packagesToInstall.push("sass");
+
+  // Generate globals.scss in app/styles
+  const globalsPath = join(projectRoot, "app", "styles", "globals.scss");
+  try {
+    await access(globalsPath);
+    result.warnings.push(
+      "app/styles/globals.scss already exists. Skipped generation."
+    );
+  } catch {
+    await writeFile(globalsPath, generateGlobalsSCSS(options.seeds), "utf-8");
+    result.filesCreated.push("app/styles/globals.scss");
+  }
+
+  // Generate providers.tsx
+  const providersPath = join(projectRoot, "app", "providers.tsx");
+  try {
+    await access(providersPath);
+    result.warnings.push("app/providers.tsx already exists. Skipped.");
+  } catch {
+    await writeFile(providersPath, generateProviders(), "utf-8");
+    result.filesCreated.push("app/providers.tsx");
+  }
+
+  result.warnings.push(
+    'Add @fragments-sdk/ui to serverDependenciesToBundle in remix.config if using source imports.'
+  );
+
+  return result;
+}
+
+async function setupAstro(
+  projectRoot: string,
+  options: FrameworkSetupOptions
+): Promise<FrameworkSetupResult> {
+  const result: FrameworkSetupResult = {
+    framework: "astro",
+    filesCreated: [],
+    packagesToInstall: [],
+    configModified: [],
+    warnings: [],
+  };
+
+  result.packagesToInstall.push("sass");
+
+  // Generate globals.scss
+  const globalsPath = join(projectRoot, "src", "styles", "globals.scss");
+  try {
+    await access(globalsPath);
+    result.warnings.push(
+      "src/styles/globals.scss already exists. Skipped generation."
+    );
+  } catch {
+    await writeFile(globalsPath, generateGlobalsSCSS(options.seeds), "utf-8");
+    result.filesCreated.push("src/styles/globals.scss");
+  }
+
+  return result;
+}
+
+// ============================================
+// Main Setup Function
+// ============================================
+
+/**
+ * Set up framework-specific configuration for @fragments-sdk/ui
+ */
+export async function setupFramework(
+  options: FrameworkSetupOptions
+): Promise<FrameworkSetupResult> {
+  const { projectRoot } = options;
+
+  // Detect or use provided framework
+  let framework = options.framework;
+  if (!framework || framework === "unknown") {
+    const detection = await detectFramework(projectRoot);
+    framework = detection.framework;
+
+    if (detection.detectedBy) {
+      console.log(
+        pc.green(`  Detected ${frameworkLabel(framework)}`) +
+          pc.dim(` (via ${detection.detectedBy})`)
+      );
+    }
+  } else {
+    console.log(pc.green(`  Framework: ${frameworkLabel(framework)}`));
+  }
+
+  switch (framework) {
+    case "nextjs":
+      return setupNextJS(projectRoot, options);
+    case "vite":
+      return setupVite(projectRoot, options);
+    case "remix":
+      return setupRemix(projectRoot, options);
+    case "astro":
+      return setupAstro(projectRoot, options);
+    default:
+      return {
+        framework: "unknown",
+        filesCreated: [],
+        packagesToInstall: ["sass"],
+        configModified: [],
+        warnings: [
+          "Could not detect framework. Install sass and import @fragments-sdk/ui/styles manually.",
+        ],
+      };
+  }
+}
+
+function frameworkLabel(framework: Framework): string {
+  switch (framework) {
+    case "nextjs":
+      return "Next.js";
+    case "vite":
+      return "Vite";
+    case "remix":
+      return "Remix";
+    case "astro":
+      return "Astro";
+    default:
+      return "Unknown";
+  }
+}

package/src/commands/init.ts

@@ -14,6 +14,11 @@ import pc from "picocolors";
 import { BRAND } from "../core/index.js";
 import fg from "fast-glob";
 import { input, confirm, select } from "@inquirer/prompts";
+import {
+  setupFramework,
+  detectFramework,
+  type Framework,
+} from "./init-framework.js";
 
 export interface InitOptions {
   /** Project root directory */
@@ -22,6 +27,8 @@ export interface InitOptions {
   force?: boolean;
   /** Non-interactive mode - auto-detect and use defaults */
   yes?: boolean;
+  /** Explicit framework override */
+  framework?: string;
 }
 
 export interface InitResult {
@@ -596,7 +603,40 @@ export async function init(options: InitOptions = {}): Promise<InitResult> {
     }
   }
 
-  // Step 6: Show next steps or start server
+  // Step 6: Framework-specific configuration
+  console.log(pc.dim("\nConfiguring framework integration...\n"));
+
+  const frameworkOverride = options.framework as Framework | undefined;
+  const frameworkResult = await setupFramework({
+    projectRoot,
+    framework: frameworkOverride,
+  });
+
+  if (frameworkResult.filesCreated.length > 0) {
+    for (const file of frameworkResult.filesCreated) {
+      console.log(pc.green(`✓ Created ${file}`));
+    }
+  }
+
+  if (frameworkResult.configModified.length > 0) {
+    for (const file of frameworkResult.configModified) {
+      console.log(pc.green(`✓ Updated ${file}`));
+    }
+  }
+
+  if (frameworkResult.packagesToInstall.length > 0) {
+    const pkgs = frameworkResult.packagesToInstall.join(" ");
+    console.log(
+      pc.yellow(`\n⚠ Install required dependencies: `) +
+        pc.bold(`pnpm add -D ${pkgs}`)
+    );
+  }
+
+  for (const warning of frameworkResult.warnings) {
+    console.log(pc.yellow(`  Note: ${warning}`));
+  }
+
+  // Step 7: Show next steps or start server
   if (errors.length === 0) {
     console.log(pc.green("\n✓ Setup complete!\n"));
 

package/src/core/__tests__/preview-runtime.test.tsx

@@ -0,0 +1,111 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  executeVariantLoaders,
+  resolvePreviewRuntimeState,
+  type PreviewVariantLike,
+} from "../preview-runtime.js";
+
+describe("executeVariantLoaders", () => {
+  it("returns host loadedData when no loaders are defined", async () => {
+    const loadedData = { source: "host", count: 1 };
+    const result = await executeVariantLoaders(undefined, loadedData);
+    expect(result).toEqual(loadedData);
+  });
+
+  it("merges loader results and applies host loadedData last", async () => {
+    const result = await executeVariantLoaders(
+      [
+        async () => ({ count: 1, fromFirst: true }),
+        async () => ({ count: 2, fromSecond: true }),
+      ],
+      { count: 3, fromHost: true },
+    );
+
+    expect(result).toEqual({
+      count: 3,
+      fromFirst: true,
+      fromSecond: true,
+      fromHost: true,
+    });
+  });
+});
+
+describe("resolvePreviewRuntimeState", () => {
+  it("renders variants with no loaders", async () => {
+    const variant: PreviewVariantLike = {
+      render: () => "Preview content",
+    };
+
+    const state = await resolvePreviewRuntimeState({ variant });
+
+    expect(state.isLoading).toBe(false);
+    expect(state.error).toBeNull();
+    expect(state.content).toBe("Preview content");
+  });
+
+  it("renders with successful loaders", async () => {
+    const variant: PreviewVariantLike = {
+      loaders: [async () => ({ label: "from-loader" })],
+      render: (options) => `Loaded: ${String(options?.loadedData?.label)}`,
+    };
+
+    const state = await resolvePreviewRuntimeState({ variant });
+
+    expect(state.error).toBeNull();
+    expect(state.loadedData).toEqual({ label: "from-loader" });
+    expect(state.content).toBe("Loaded: from-loader");
+  });
+
+  it("returns an error when a loader rejects", async () => {
+    const variant: PreviewVariantLike = {
+      loaders: [async () => { throw new Error("loader failed"); }],
+      render: () => "should not render",
+    };
+
+    const state = await resolvePreviewRuntimeState({ variant });
+
+    expect(state.content).toBeNull();
+    expect(state.error?.message).toContain("loader failed");
+  });
+
+  it("returns an error when render throws", async () => {
+    const variant: PreviewVariantLike = {
+      render: () => {
+        throw new Error("render failed");
+      },
+    };
+
+    const state = await resolvePreviewRuntimeState({ variant });
+
+    expect(state.content).toBeNull();
+    expect(state.error?.message).toContain("render failed");
+  });
+
+  it("normalizes non-Error throwables", async () => {
+    const variant: PreviewVariantLike = {
+      loaders: [async () => { throw "string-failure"; }],
+      render: () => "never",
+    };
+
+    const state = await resolvePreviewRuntimeState({ variant });
+    expect(state.error).not.toBeNull();
+    expect(state.error?.message).toContain("string-failure");
+  });
+
+  it("uses host data as override input in render options", async () => {
+    const renderSpy = vi.fn((options?: { loadedData?: Record<string, unknown> }) => options?.loadedData);
+    const variant: PreviewVariantLike = {
+      loaders: [async () => ({ count: 1 })],
+      render: renderSpy,
+    };
+
+    const state = await resolvePreviewRuntimeState({
+      variant,
+      loadedData: { count: 2, source: "host" },
+    });
+
+    expect(renderSpy).toHaveBeenCalledTimes(1);
+    expect(state.loadedData).toEqual({ count: 2, source: "host" });
+    expect(state.content).toEqual({ count: 2, source: "host" });
+  });
+});

package/src/core/index.ts

@@ -161,3 +161,16 @@ export type {
   CompositionSuggestion,
   CompositionGuideline,
 } from "./composition.js";
+
+// Shared preview runtime
+export {
+  executeVariantLoaders,
+  resolvePreviewRuntimeState,
+  usePreviewVariantRuntime,
+  PreviewVariantRuntime,
+} from "./preview-runtime.js";
+export type {
+  PreviewVariantLike,
+  PreviewRuntimeState,
+  PreviewRuntimeOptions,
+} from "./preview-runtime.js";