@fragments-sdk/cli 0.3.2 → 0.4.0

package/src/theme/index.ts

@@ -0,0 +1,61 @@
+/**
+ * Theme Customization Module
+ *
+ * Provides theme configuration, validation, serialization, and generation
+ */
+
+// Types
+export type {
+  ThemeConfig,
+  ThemeColors,
+  ThemeSurfaces,
+  ThemeText,
+  ThemeBorders,
+  ThemeTypography,
+  ThemeRadius,
+  ThemeShadows,
+  ThemeDarkMode,
+  TokenOutputFormat,
+  TokenGeneratorOptions,
+  TokenGeneratorResult,
+  PresetName,
+} from "./types.js";
+
+// Schema validation
+export {
+  themeConfigSchema,
+  themeColorsSchema,
+  themeSurfacesSchema,
+  themeTextSchema,
+  themeBordersSchema,
+  themeTypographySchema,
+  themeRadiusSchema,
+  themeShadowsSchema,
+  themeDarkModeSchema,
+  validateThemeConfig,
+} from "./schema.js";
+export type { ThemeValidationResult } from "./schema.js";
+
+// Serialization
+export {
+  encodeThemeToUrl,
+  decodeThemeFromUrl,
+  compressTheme,
+  decompressTheme,
+} from "./serializer.js";
+
+// Generation
+export {
+  generateScssTokens,
+  generateCssTokens,
+  generateTokenFiles,
+} from "./generator.js";
+
+// Presets
+export {
+  DEFAULT_PRESET,
+  PRESETS,
+  getPreset,
+  listPresets,
+  isValidPresetName,
+} from "./presets.js";

package/src/theme/presets.ts

@@ -0,0 +1,189 @@
+/**
+ * Theme Presets
+ *
+ * Built-in theme presets including the default theme
+ * Values extracted from libs/ui/src/tokens/_variables.scss
+ */
+
+import type { ThemeConfig, PresetName } from "./types.js";
+
+/**
+ * Default preset - matches libs/ui/src/tokens/_variables.scss exactly
+ */
+export const DEFAULT_PRESET: ThemeConfig = {
+  name: "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, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif",
+    fontMono: "'SF Mono', SFMono-Regular, ui-monospace, Menlo, 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), 0 2px 4px -2px rgba(0, 0, 0, 0.1)",
+  },
+  dark: {
+    surfaces: {
+      bgPrimary: "#0f172a",
+      bgSecondary: "#1e293b",
+      bgTertiary: "#334155",
+      bgElevated: "#1e293b",
+      bgHover: "rgba(255, 255, 255, 0.06)",
+      bgActive: "rgba(255, 255, 255, 0.08)",
+    },
+    text: {
+      primary: "#f8fafc",
+      secondary: "#94a3b8",
+      tertiary: "#64748b",
+      inverse: "#0f172a",
+    },
+    borders: {
+      default: "#334155",
+      strong: "#475569",
+    },
+    shadows: {
+      sm: "0 1px 2px 0 rgba(0, 0, 0, 0.3)",
+      md: "0 4px 6px -1px rgba(0, 0, 0, 0.4), 0 2px 4px -2px rgba(0, 0, 0, 0.3)",
+    },
+    dangerBg: "rgba(239, 68, 68, 0.15)",
+    successBg: "rgba(34, 197, 94, 0.15)",
+    warningBg: "rgba(245, 158, 11, 0.15)",
+    infoBg: "rgba(59, 130, 246, 0.15)",
+    backdrop: "rgba(0, 0, 0, 0.7)",
+  },
+};
+
+/**
+ * Neutral preset - gray-based accent colors (Zinc)
+ */
+const NEUTRAL_PRESET: ThemeConfig = {
+  name: "Neutral",
+  extends: "default",
+  colors: {
+    accent: "#71717a",      // zinc-500
+    accentHover: "#52525b", // zinc-600
+    accentActive: "#3f3f46", // zinc-700
+  },
+};
+
+/**
+ * Slate preset - blue-gray based colors
+ */
+const SLATE_PRESET: ThemeConfig = {
+  name: "Slate",
+  extends: "default",
+  colors: {
+    accent: "#64748b",      // slate-500
+    accentHover: "#475569", // slate-600
+    accentActive: "#334155", // slate-700
+  },
+  surfaces: {
+    bgSecondary: "#f1f5f9", // slate-100
+    bgTertiary: "#e2e8f0",  // slate-200
+  },
+};
+
+/**
+ * Emerald preset - green accent colors
+ */
+const EMERALD_PRESET: ThemeConfig = {
+  name: "Emerald",
+  extends: "default",
+  colors: {
+    accent: "#10b981",      // emerald-500
+    accentHover: "#059669", // emerald-600
+    accentActive: "#047857", // emerald-700
+  },
+};
+
+/**
+ * Rose preset - pink accent colors
+ */
+const ROSE_PRESET: ThemeConfig = {
+  name: "Rose",
+  extends: "default",
+  colors: {
+    accent: "#f43f5e",      // rose-500
+    accentHover: "#e11d48", // rose-600
+    accentActive: "#be123c", // rose-700
+  },
+};
+
+/**
+ * All built-in presets
+ */
+export const PRESETS: Record<string, ThemeConfig> = {
+  default: DEFAULT_PRESET,
+  neutral: NEUTRAL_PRESET,
+  slate: SLATE_PRESET,
+  emerald: EMERALD_PRESET,
+  rose: ROSE_PRESET,
+};
+
+/**
+ * Get a preset by name
+ *
+ * @param name - Preset name
+ * @returns Theme configuration or null if not found
+ */
+export function getPreset(name: string): ThemeConfig | null {
+  return PRESETS[name] ?? null;
+}
+
+/**
+ * List all available preset names
+ *
+ * @returns Array of preset names
+ */
+export function listPresets(): string[] {
+  return Object.keys(PRESETS);
+}
+
+/**
+ * Check if a string is a valid preset name
+ *
+ * @param name - Name to check
+ * @returns true if valid preset name
+ */
+export function isValidPresetName(name: string): name is PresetName {
+  return name in PRESETS;
+}

package/src/theme/schema.ts

@@ -0,0 +1,193 @@
+/**
+ * Theme Configuration Zod Schemas
+ *
+ * Provides validation for theme configuration objects
+ */
+
+import { z } from "zod";
+import type { ThemeConfig } from "./types.js";
+
+/**
+ * Regex patterns for color validation
+ */
+const HEX_COLOR_REGEX = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+const RGB_COLOR_REGEX = /^rgba?\(\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*\d{1,3}\s*(,\s*(0|1|0?\.\d+))?\s*\)$/;
+const HSL_COLOR_REGEX = /^hsla?\(\s*\d{1,3}\s*,\s*\d{1,3}%\s*,\s*\d{1,3}%\s*(,\s*(0|1|0?\.\d+))?\s*\)$/;
+
+/**
+ * CSS color string validator
+ */
+const colorSchema = z.string().refine(
+  (val) => {
+    return (
+      HEX_COLOR_REGEX.test(val) ||
+      RGB_COLOR_REGEX.test(val) ||
+      HSL_COLOR_REGEX.test(val)
+    );
+  },
+  { message: "Invalid color format. Use hex (#rrggbb), rgb(), rgba(), hsl(), or hsla()" }
+);
+
+/**
+ * CSS size value validator (px, rem, em, etc.)
+ */
+const sizeSchema = z.string().refine(
+  (val) => {
+    // Match number followed by unit, or just a number (for unitless values like 9999px)
+    return /^-?\d*\.?\d+(px|rem|em|%|vw|vh)?$/.test(val);
+  },
+  { message: "Invalid size format. Use px, rem, em, %, vw, or vh" }
+);
+
+/**
+ * Shadow value validator (more permissive for complex shadow syntax)
+ */
+const shadowSchema = z.string();
+
+/**
+ * Font stack validator
+ */
+const fontStackSchema = z.string();
+
+/**
+ * Font weight validator (100-900 in increments of 100)
+ */
+const fontWeightSchema = z.number().int().min(100).max(900);
+
+/**
+ * Theme colors schema
+ */
+export const themeColorsSchema = z.object({
+  accent: colorSchema.optional(),
+  accentHover: colorSchema.optional(),
+  accentActive: colorSchema.optional(),
+  danger: colorSchema.optional(),
+  dangerHover: colorSchema.optional(),
+  success: colorSchema.optional(),
+  warning: colorSchema.optional(),
+  info: colorSchema.optional(),
+  dangerBg: colorSchema.optional(),
+  successBg: colorSchema.optional(),
+  warningBg: colorSchema.optional(),
+  infoBg: colorSchema.optional(),
+}).strict();
+
+/**
+ * Theme surfaces schema
+ */
+export const themeSurfacesSchema = z.object({
+  bgPrimary: colorSchema.optional(),
+  bgSecondary: colorSchema.optional(),
+  bgTertiary: colorSchema.optional(),
+  bgElevated: colorSchema.optional(),
+  bgHover: colorSchema.optional(),
+  bgActive: colorSchema.optional(),
+}).strict();
+
+/**
+ * Theme text schema
+ */
+export const themeTextSchema = z.object({
+  primary: colorSchema.optional(),
+  secondary: colorSchema.optional(),
+  tertiary: colorSchema.optional(),
+  inverse: colorSchema.optional(),
+}).strict();
+
+/**
+ * Theme borders schema
+ */
+export const themeBordersSchema = z.object({
+  default: colorSchema.optional(),
+  strong: colorSchema.optional(),
+}).strict();
+
+/**
+ * Theme typography schema
+ */
+export const themeTypographySchema = z.object({
+  fontSans: fontStackSchema.optional(),
+  fontMono: fontStackSchema.optional(),
+  fontWeightNormal: fontWeightSchema.optional(),
+  fontWeightMedium: fontWeightSchema.optional(),
+  fontWeightSemibold: fontWeightSchema.optional(),
+}).strict();
+
+/**
+ * Theme radius schema
+ */
+export const themeRadiusSchema = z.object({
+  sm: sizeSchema.optional(),
+  md: sizeSchema.optional(),
+  lg: sizeSchema.optional(),
+  full: sizeSchema.optional(),
+}).strict();
+
+/**
+ * Theme shadows schema
+ */
+export const themeShadowsSchema = z.object({
+  sm: shadowSchema.optional(),
+  md: shadowSchema.optional(),
+}).strict();
+
+/**
+ * Theme dark mode schema
+ */
+export const themeDarkModeSchema = z.object({
+  surfaces: themeSurfacesSchema.optional(),
+  text: themeTextSchema.optional(),
+  borders: themeBordersSchema.optional(),
+  shadows: themeShadowsSchema.optional(),
+  dangerBg: colorSchema.optional(),
+  successBg: colorSchema.optional(),
+  warningBg: colorSchema.optional(),
+  infoBg: colorSchema.optional(),
+  backdrop: colorSchema.optional(),
+}).strict();
+
+/**
+ * Complete theme configuration schema
+ */
+export const themeConfigSchema = z.object({
+  name: z.string().min(1, "Theme name is required"),
+  version: z.string().optional(),
+  extends: z.string().optional(),
+  colors: themeColorsSchema.optional(),
+  surfaces: themeSurfacesSchema.optional(),
+  text: themeTextSchema.optional(),
+  borders: themeBordersSchema.optional(),
+  typography: themeTypographySchema.optional(),
+  radius: themeRadiusSchema.optional(),
+  shadows: themeShadowsSchema.optional(),
+  dark: themeDarkModeSchema.optional(),
+}).strict();
+
+/**
+ * Type for the inferred schema
+ */
+export type ThemeConfigInput = z.input<typeof themeConfigSchema>;
+export type ThemeConfigOutput = z.output<typeof themeConfigSchema>;
+
+/**
+ * Validation result type
+ */
+export type ThemeValidationResult =
+  | { success: true; data: ThemeConfig }
+  | { success: false; error: z.ZodError };
+
+/**
+ * Validate a theme configuration object
+ *
+ * @param config - The theme configuration to validate
+ * @returns Validation result with either the parsed data or error details
+ */
+export function validateThemeConfig(config: unknown): ThemeValidationResult {
+  const result = themeConfigSchema.safeParse(config);
+
+  if (result.success) {
+    return { success: true, data: result.data as ThemeConfig };
+  }
+
+  return { success: false, error: result.error };
+}

package/src/theme/serializer.ts

@@ -0,0 +1,123 @@
+/**
+ * Theme Serialization
+ *
+ * Encodes/decodes theme configurations to/from URL-safe strings
+ * using zlib compression and base64url encoding.
+ */
+
+import { deflateSync, inflateSync } from "node:zlib";
+import { validateThemeConfig } from "./schema.js";
+import type { ThemeConfig } from "./types.js";
+
+const DEFAULT_BASE_URL = "https://fragments.dev/init";
+
+/**
+ * Convert a Buffer to base64url encoding (URL-safe base64)
+ */
+function toBase64Url(buffer: Buffer): string {
+  return buffer
+    .toString("base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=/g, "");
+}
+
+/**
+ * Convert a base64url string to Buffer
+ */
+function fromBase64Url(str: string): Buffer {
+  // Restore standard base64 characters
+  let base64 = str.replace(/-/g, "+").replace(/_/g, "/");
+
+  // Add padding if needed
+  const pad = base64.length % 4;
+  if (pad) {
+    base64 += "=".repeat(4 - pad);
+  }
+
+  return Buffer.from(base64, "base64");
+}
+
+/**
+ * Compress a theme configuration to a URL-safe string
+ *
+ * Process: JSON → deflate → base64url
+ *
+ * @param config - Theme configuration to compress
+ * @returns URL-safe encoded string
+ */
+export function compressTheme(config: ThemeConfig): string {
+  const json = JSON.stringify(config);
+  const compressed = deflateSync(Buffer.from(json, "utf-8"), { level: 9 });
+  return toBase64Url(compressed);
+}
+
+/**
+ * Decompress a URL-safe string back to theme configuration
+ *
+ * Process: base64url → inflate → JSON
+ *
+ * @param encoded - URL-safe encoded string
+ * @returns Theme configuration or null if invalid
+ */
+export function decompressTheme(encoded: string): ThemeConfig | null {
+  try {
+    const buffer = fromBase64Url(encoded);
+    const decompressed = inflateSync(buffer);
+    const json = decompressed.toString("utf-8");
+    const parsed = JSON.parse(json);
+
+    // Validate the parsed object
+    const result = validateThemeConfig(parsed);
+    if (result.success) {
+      return result.data;
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Encode a theme configuration to a full URL with ?preset= parameter
+ *
+ * @param config - Theme configuration to encode
+ * @param baseUrl - Base URL (default: https://fragments.dev/init)
+ * @returns Full URL with encoded theme as preset parameter
+ */
+export function encodeThemeToUrl(
+  config: ThemeConfig,
+  baseUrl: string = DEFAULT_BASE_URL
+): string {
+  const encoded = compressTheme(config);
+  const url = new URL(baseUrl);
+  url.searchParams.set("preset", encoded);
+  return url.toString();
+}
+
+/**
+ * Decode a theme from a URL or raw encoded string
+ *
+ * Handles:
+ * - Full URLs with ?preset= parameter
+ * - Raw encoded strings (compressed theme data)
+ *
+ * @param input - URL or encoded string
+ * @returns Theme configuration or null if invalid
+ */
+export function decodeThemeFromUrl(input: string): ThemeConfig | null {
+  // Try to parse as URL first
+  try {
+    const url = new URL(input);
+    const preset = url.searchParams.get("preset");
+    if (preset) {
+      return decompressTheme(preset);
+    }
+    // URL parsed but no preset param
+    return null;
+  } catch {
+    // Not a valid URL, try as raw encoded string
+    return decompressTheme(input);
+  }
+}