@fragments-sdk/cli 0.3.2 → 0.4.0

package/src/theme/__tests__/serializer.test.ts

@@ -0,0 +1,326 @@
+import { describe, it, expect } from "vitest";
+import {
+  encodeThemeToUrl,
+  decodeThemeFromUrl,
+  compressTheme,
+  decompressTheme,
+} from "../serializer.js";
+import type { ThemeConfig } from "../types.js";
+
+describe("Theme Serializer", () => {
+  describe("compression", () => {
+    it("should compress large theme to shorter string than JSON", () => {
+      // Use a large theme to demonstrate compression benefit
+      // (small themes may be larger after base64 encoding)
+      const theme: ThemeConfig = {
+        name: "Complete Theme",
+        version: "1.0.0",
+        extends: "default",
+        colors: {
+          accent: "#6366f1",
+          accentHover: "#4f46e5",
+          accentActive: "#4338ca",
+          danger: "#ef4444",
+          dangerHover: "#dc2626",
+          success: "#22c55e",
+          warning: "#f59e0b",
+          info: "#3b82f6",
+          dangerBg: "rgba(239, 68, 68, 0.1)",
+          successBg: "rgba(34, 197, 94, 0.1)",
+          warningBg: "rgba(245, 158, 11, 0.1)",
+          infoBg: "rgba(59, 130, 246, 0.1)",
+        },
+        surfaces: {
+          bgPrimary: "#ffffff",
+          bgSecondary: "#f8fafc",
+          bgTertiary: "#f1f5f9",
+          bgElevated: "#ffffff",
+          bgHover: "rgba(0, 0, 0, 0.04)",
+          bgActive: "rgba(0, 0, 0, 0.06)",
+        },
+        text: {
+          primary: "#0f172a",
+          secondary: "#64748b",
+          tertiary: "#94a3b8",
+          inverse: "#ffffff",
+        },
+        borders: {
+          default: "#e2e8f0",
+          strong: "#cbd5e1",
+        },
+      };
+
+      const jsonString = JSON.stringify(theme);
+      const compressed = compressTheme(theme);
+
+      // For large themes, compression should help
+      expect(compressed.length).toBeLessThan(jsonString.length);
+    });
+
+    it("should round-trip decompress to original theme", () => {
+      const theme: ThemeConfig = {
+        name: "Test Theme",
+        colors: {
+          accent: "#6366f1",
+        },
+      };
+
+      const compressed = compressTheme(theme);
+      const decompressed = decompressTheme(compressed);
+
+      expect(decompressed).toEqual(theme);
+    });
+
+    it("should handle minimal theme (name only)", () => {
+      const theme: ThemeConfig = {
+        name: "Minimal",
+      };
+
+      const compressed = compressTheme(theme);
+      const decompressed = decompressTheme(compressed);
+
+      expect(decompressed).toEqual(theme);
+    });
+
+    it("should handle complex theme with all fields", () => {
+      const theme: ThemeConfig = {
+        name: "Complete Theme",
+        version: "1.0.0",
+        extends: "default",
+        colors: {
+          accent: "#6366f1",
+          accentHover: "#4f46e5",
+          accentActive: "#4338ca",
+          danger: "#ef4444",
+          dangerHover: "#dc2626",
+          success: "#22c55e",
+          warning: "#f59e0b",
+          info: "#3b82f6",
+          dangerBg: "rgba(239, 68, 68, 0.1)",
+          successBg: "rgba(34, 197, 94, 0.1)",
+          warningBg: "rgba(245, 158, 11, 0.1)",
+          infoBg: "rgba(59, 130, 246, 0.1)",
+        },
+        surfaces: {
+          bgPrimary: "#ffffff",
+          bgSecondary: "#f8fafc",
+          bgTertiary: "#f1f5f9",
+          bgElevated: "#ffffff",
+          bgHover: "rgba(0, 0, 0, 0.04)",
+          bgActive: "rgba(0, 0, 0, 0.06)",
+        },
+        text: {
+          primary: "#0f172a",
+          secondary: "#64748b",
+          tertiary: "#94a3b8",
+          inverse: "#ffffff",
+        },
+        borders: {
+          default: "#e2e8f0",
+          strong: "#cbd5e1",
+        },
+        typography: {
+          fontSans: "system-ui, -apple-system, sans-serif",
+          fontMono: "'SF Mono', monospace",
+          fontWeightNormal: 400,
+          fontWeightMedium: 500,
+          fontWeightSemibold: 600,
+        },
+        radius: {
+          sm: "0.25rem",
+          md: "0.375rem",
+          lg: "0.5rem",
+          full: "9999px",
+        },
+        shadows: {
+          sm: "0 1px 2px 0 rgba(0, 0, 0, 0.05)",
+          md: "0 4px 6px -1px rgba(0, 0, 0, 0.1)",
+        },
+        dark: {
+          surfaces: {
+            bgPrimary: "#0f172a",
+            bgSecondary: "#1e293b",
+          },
+          text: {
+            primary: "#f8fafc",
+            secondary: "#94a3b8",
+          },
+        },
+      };
+
+      const compressed = compressTheme(theme);
+      const decompressed = decompressTheme(compressed);
+
+      expect(decompressed).toEqual(theme);
+    });
+  });
+
+  describe("URL encoding", () => {
+    it("should produce URL-safe base64 (no +, /, =)", () => {
+      const theme: ThemeConfig = {
+        name: "Test Theme",
+        colors: {
+          accent: "#6366f1",
+        },
+      };
+
+      const compressed = compressTheme(theme);
+
+      // base64url should not contain +, /, or =
+      expect(compressed).not.toMatch(/[+/=]/);
+      // Should only contain alphanumeric, -, and _
+      expect(compressed).toMatch(/^[A-Za-z0-9_-]+$/);
+    });
+
+    it("should decode URL parameter back to theme", () => {
+      const theme: ThemeConfig = {
+        name: "Test Theme",
+        colors: {
+          accent: "#6366f1",
+        },
+      };
+
+      const compressed = compressTheme(theme);
+      const decoded = decompressTheme(compressed);
+
+      expect(decoded).toEqual(theme);
+    });
+
+    it("should return null for invalid encoded string", () => {
+      const result = decompressTheme("not-valid-base64-at-all!!!");
+      expect(result).toBeNull();
+    });
+
+    it("should return null for corrupted/truncated data", () => {
+      const theme: ThemeConfig = {
+        name: "Test Theme",
+      };
+
+      const compressed = compressTheme(theme);
+      // Truncate the compressed string
+      const truncated = compressed.slice(0, 10);
+
+      const result = decompressTheme(truncated);
+      expect(result).toBeNull();
+    });
+
+    it("should return null for valid base64 but invalid JSON", () => {
+      // Create a valid base64url string that doesn't decode to valid JSON
+      const result = decompressTheme("YWJj"); // "abc" in base64
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("full URL format", () => {
+    it("should generate complete URL with ?preset= param", () => {
+      const theme: ThemeConfig = {
+        name: "Test Theme",
+        colors: {
+          accent: "#6366f1",
+        },
+      };
+
+      const url = encodeThemeToUrl(theme, "https://fragments.dev/create");
+
+      expect(url).toMatch(/^https:\/\/fragments\.dev\/create\?preset=/);
+    });
+
+    it("should extract theme from full URL", () => {
+      const theme: ThemeConfig = {
+        name: "Test Theme",
+        colors: {
+          accent: "#6366f1",
+        },
+      };
+
+      const url = encodeThemeToUrl(theme, "https://fragments.dev/create");
+      const decoded = decodeThemeFromUrl(url);
+
+      expect(decoded).toEqual(theme);
+    });
+
+    it("should handle URL with other query params", () => {
+      const theme: ThemeConfig = {
+        name: "Test Theme",
+      };
+
+      // Create a URL with preset param
+      const url = encodeThemeToUrl(theme, "https://fragments.dev/create");
+      // Add another param manually
+      const urlWithExtra = url + "&foo=bar";
+
+      const decoded = decodeThemeFromUrl(urlWithExtra);
+      expect(decoded).toEqual(theme);
+    });
+
+    it("should decode raw encoded string (not in URL)", () => {
+      const theme: ThemeConfig = {
+        name: "Test Theme",
+      };
+
+      const compressed = compressTheme(theme);
+      const decoded = decodeThemeFromUrl(compressed);
+
+      expect(decoded).toEqual(theme);
+    });
+
+    it("should return null for URL without preset param", () => {
+      const url = "https://fragments.dev/create?foo=bar";
+      const decoded = decodeThemeFromUrl(url);
+
+      expect(decoded).toBeNull();
+    });
+
+    it("should return null for invalid URL", () => {
+      const decoded = decodeThemeFromUrl("not a valid url or encoded string!!!");
+      expect(decoded).toBeNull();
+    });
+
+    it("should use default base URL when not provided", () => {
+      const theme: ThemeConfig = {
+        name: "Test Theme",
+      };
+
+      const url = encodeThemeToUrl(theme);
+      expect(url).toMatch(/^https:\/\/fragments\.dev\/init\?preset=/);
+    });
+  });
+
+  describe("edge cases", () => {
+    it("should handle theme names with special characters", () => {
+      const theme: ThemeConfig = {
+        name: "Theme with 'quotes' and \"double quotes\"",
+      };
+
+      const compressed = compressTheme(theme);
+      const decompressed = decompressTheme(compressed);
+
+      expect(decompressed).toEqual(theme);
+    });
+
+    it("should handle unicode characters", () => {
+      const theme: ThemeConfig = {
+        name: "Theme with emoji 🎨 and unicode",
+      };
+
+      const compressed = compressTheme(theme);
+      const decompressed = decompressTheme(compressed);
+
+      expect(decompressed).toEqual(theme);
+    });
+
+    it("should handle empty optional fields", () => {
+      const theme: ThemeConfig = {
+        name: "Test",
+        colors: {},
+        surfaces: {},
+        dark: {},
+      };
+
+      const compressed = compressTheme(theme);
+      const decompressed = decompressTheme(compressed);
+
+      expect(decompressed).toEqual(theme);
+    });
+  });
+});

package/src/theme/generator.ts

@@ -0,0 +1,355 @@
+/**
+ * Theme Token Generator
+ *
+ * Generates SCSS and CSS token files from theme configurations
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type {
+  ThemeConfig,
+  TokenGeneratorOptions,
+  TokenGeneratorResult,
+} from "./types.js";
+
+const DEFAULT_FILE_PREFIX = "_theme-tokens";
+
+/**
+ * Token mapping from ThemeConfig structure to SCSS variable names
+ */
+const TOKEN_MAPPINGS = {
+  colors: {
+    accent: "fui-color-accent",
+    accentHover: "fui-color-accent-hover",
+    accentActive: "fui-color-accent-active",
+    danger: "fui-color-danger",
+    dangerHover: "fui-color-danger-hover",
+    success: "fui-color-success",
+    warning: "fui-color-warning",
+    info: "fui-color-info",
+    dangerBg: "fui-color-danger-bg",
+    successBg: "fui-color-success-bg",
+    warningBg: "fui-color-warning-bg",
+    infoBg: "fui-color-info-bg",
+  },
+  surfaces: {
+    bgPrimary: "fui-bg-primary",
+    bgSecondary: "fui-bg-secondary",
+    bgTertiary: "fui-bg-tertiary",
+    bgElevated: "fui-bg-elevated",
+    bgHover: "fui-bg-hover",
+    bgActive: "fui-bg-active",
+  },
+  text: {
+    primary: "fui-text-primary",
+    secondary: "fui-text-secondary",
+    tertiary: "fui-text-tertiary",
+    inverse: "fui-text-inverse",
+  },
+  borders: {
+    default: "fui-border",
+    strong: "fui-border-strong",
+  },
+  typography: {
+    fontSans: "fui-font-sans",
+    fontMono: "fui-font-mono",
+    fontWeightNormal: "fui-font-weight-normal",
+    fontWeightMedium: "fui-font-weight-medium",
+    fontWeightSemibold: "fui-font-weight-semibold",
+  },
+  radius: {
+    sm: "fui-radius-sm",
+    md: "fui-radius-md",
+    lg: "fui-radius-lg",
+    full: "fui-radius-full",
+  },
+  shadows: {
+    sm: "fui-shadow-sm",
+    md: "fui-shadow-md",
+  },
+} as const;
+
+/**
+ * Dark mode token mappings
+ */
+const DARK_TOKEN_MAPPINGS = {
+  surfaces: {
+    bgPrimary: "fui-dark-bg-primary",
+    bgSecondary: "fui-dark-bg-secondary",
+    bgTertiary: "fui-dark-bg-tertiary",
+    bgElevated: "fui-dark-bg-elevated",
+    bgHover: "fui-dark-bg-hover",
+    bgActive: "fui-dark-bg-active",
+  },
+  text: {
+    primary: "fui-dark-text-primary",
+    secondary: "fui-dark-text-secondary",
+    tertiary: "fui-dark-text-tertiary",
+    inverse: "fui-dark-text-inverse",
+  },
+  borders: {
+    default: "fui-dark-border",
+    strong: "fui-dark-border-strong",
+  },
+  shadows: {
+    sm: "fui-dark-shadow-sm",
+    md: "fui-dark-shadow-md",
+  },
+  // Direct dark mode properties
+  dangerBg: "fui-dark-color-danger-bg",
+  successBg: "fui-dark-color-success-bg",
+  warningBg: "fui-dark-color-warning-bg",
+  infoBg: "fui-dark-color-info-bg",
+  backdrop: "fui-dark-backdrop",
+} as const;
+
+/**
+ * Generate tokens for a category
+ */
+function generateCategoryTokens(
+  config: ThemeConfig,
+  categoryKey: keyof typeof TOKEN_MAPPINGS,
+  format: "scss" | "css"
+): string[] {
+  const category = config[categoryKey];
+  if (!category) return [];
+
+  const mappings = TOKEN_MAPPINGS[categoryKey];
+  const tokens: string[] = [];
+
+  for (const [key, varName] of Object.entries(mappings)) {
+    const value = (category as Record<string, unknown>)[key];
+    if (value !== undefined) {
+      if (format === "scss") {
+        tokens.push(`$${varName}: ${value} !default;`);
+      } else {
+        tokens.push(`  --${varName}: ${value};`);
+      }
+    }
+  }
+
+  return tokens;
+}
+
+/**
+ * Generate dark mode tokens
+ */
+function generateDarkTokens(
+  config: ThemeConfig,
+  format: "scss" | "css"
+): string[] {
+  if (!config.dark) return [];
+
+  const tokens: string[] = [];
+
+  // Handle nested categories
+  const nestedCategories = ["surfaces", "text", "borders", "shadows"] as const;
+  for (const category of nestedCategories) {
+    const categoryData = config.dark[category];
+    if (!categoryData) continue;
+
+    const mappings = DARK_TOKEN_MAPPINGS[category];
+    for (const [key, varName] of Object.entries(mappings)) {
+      const value = (categoryData as Record<string, unknown>)[key];
+      if (value !== undefined) {
+        if (format === "scss") {
+          tokens.push(`$${varName}: ${value} !default;`);
+        } else {
+          tokens.push(`  --${varName.replace("fui-dark-", "fui-")}: ${value};`);
+        }
+      }
+    }
+  }
+
+  // Handle direct dark mode properties
+  const directProps = ["dangerBg", "successBg", "warningBg", "infoBg", "backdrop"] as const;
+  for (const prop of directProps) {
+    const value = config.dark[prop];
+    if (value !== undefined) {
+      const varName = DARK_TOKEN_MAPPINGS[prop];
+      if (format === "scss") {
+        tokens.push(`$${varName}: ${value} !default;`);
+      } else {
+        // For CSS, use the light mode variable name in dark context
+        const cssVarName = varName.replace("fui-dark-color-", "fui-color-").replace("fui-dark-", "fui-");
+        tokens.push(`  --${cssVarName}: ${value};`);
+      }
+    }
+  }
+
+  return tokens;
+}
+
+/**
+ * Generate SCSS tokens from a theme configuration
+ *
+ * @param config - Theme configuration
+ * @returns SCSS content string
+ */
+export function generateScssTokens(config: ThemeConfig): string {
+  const lines: string[] = [];
+
+  // Header
+  lines.push("// Auto-generated by @fragments-sdk/cli");
+  lines.push(`// Theme: ${config.name}`);
+  if (config.version) {
+    lines.push(`// Version: ${config.version}`);
+  }
+  lines.push("");
+
+  // Colors
+  const colorTokens = generateCategoryTokens(config, "colors", "scss");
+  if (colorTokens.length > 0) {
+    lines.push("// Colors");
+    lines.push(...colorTokens);
+    lines.push("");
+  }
+
+  // Surfaces
+  const surfaceTokens = generateCategoryTokens(config, "surfaces", "scss");
+  if (surfaceTokens.length > 0) {
+    lines.push("// Surfaces");
+    lines.push(...surfaceTokens);
+    lines.push("");
+  }
+
+  // Text
+  const textTokens = generateCategoryTokens(config, "text", "scss");
+  if (textTokens.length > 0) {
+    lines.push("// Text");
+    lines.push(...textTokens);
+    lines.push("");
+  }
+
+  // Borders
+  const borderTokens = generateCategoryTokens(config, "borders", "scss");
+  if (borderTokens.length > 0) {
+    lines.push("// Borders");
+    lines.push(...borderTokens);
+    lines.push("");
+  }
+
+  // Typography
+  const typographyTokens = generateCategoryTokens(config, "typography", "scss");
+  if (typographyTokens.length > 0) {
+    lines.push("// Typography");
+    lines.push(...typographyTokens);
+    lines.push("");
+  }
+
+  // Border Radius
+  const radiusTokens = generateCategoryTokens(config, "radius", "scss");
+  if (radiusTokens.length > 0) {
+    lines.push("// Border Radius");
+    lines.push(...radiusTokens);
+    lines.push("");
+  }
+
+  // Shadows
+  const shadowTokens = generateCategoryTokens(config, "shadows", "scss");
+  if (shadowTokens.length > 0) {
+    lines.push("// Shadows");
+    lines.push(...shadowTokens);
+    lines.push("");
+  }
+
+  // Dark mode
+  const darkTokens = generateDarkTokens(config, "scss");
+  if (darkTokens.length > 0) {
+    lines.push("// Dark Mode");
+    lines.push(...darkTokens);
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Generate CSS custom properties from a theme configuration
+ *
+ * @param config - Theme configuration
+ * @returns CSS content string
+ */
+export function generateCssTokens(config: ThemeConfig): string {
+  const lines: string[] = [];
+
+  // Header
+  lines.push("/* Auto-generated by @fragments-sdk/cli */");
+  lines.push(`/* Theme: ${config.name} */`);
+  if (config.version) {
+    lines.push(`/* Version: ${config.version} */`);
+  }
+  lines.push("");
+
+  // Collect all light mode tokens
+  const lightTokens: string[] = [];
+
+  const categories = ["colors", "surfaces", "text", "borders", "typography", "radius", "shadows"] as const;
+  for (const category of categories) {
+    const tokens = generateCategoryTokens(config, category, "css");
+    lightTokens.push(...tokens);
+  }
+
+  if (lightTokens.length > 0) {
+    lines.push(":root {");
+    lines.push(...lightTokens);
+    lines.push("}");
+    lines.push("");
+  }
+
+  // Dark mode
+  const darkTokens = generateDarkTokens(config, "css");
+  if (darkTokens.length > 0) {
+    lines.push(':root.dark,');
+    lines.push(':root[data-theme="dark"] {');
+    lines.push(...darkTokens);
+    lines.push("}");
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Generate token files from a theme configuration
+ *
+ * @param config - Theme configuration
+ * @param options - Generator options
+ * @returns Result with file paths or error
+ */
+export async function generateTokenFiles(
+  config: ThemeConfig,
+  options: TokenGeneratorOptions
+): Promise<TokenGeneratorResult> {
+  const { format, outputDir, filePrefix = DEFAULT_FILE_PREFIX } = options;
+
+  try {
+    // Ensure output directory exists
+    await mkdir(outputDir, { recursive: true });
+
+    const result: TokenGeneratorResult = { success: true };
+
+    // Generate SCSS if requested
+    if (format === "scss" || format === "both") {
+      const scssContent = generateScssTokens(config);
+      const scssPath = join(outputDir, `${filePrefix}.scss`);
+      await writeFile(scssPath, scssContent, "utf-8");
+      result.scssPath = scssPath;
+    }
+
+    // Generate CSS if requested
+    if (format === "css" || format === "both") {
+      const cssContent = generateCssTokens(config);
+      const cssPath = join(outputDir, `${filePrefix}.css`);
+      await writeFile(cssPath, cssContent, "utf-8");
+      result.cssPath = cssPath;
+    }
+
+    return result;
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "Unknown error",
+    };
+  }
+}