@cloudflare/kumo 1.0.0

package/scripts/component-registry/utils.ts

@@ -0,0 +1,280 @@
+/**
+ * Utility functions for component registry generation.
+ *
+ * Pure functions for string transformations and common operations.
+ */
+
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// =============================================================================
+// String Transformation Utilities
+// =============================================================================
+
+/**
+ * Convert kebab-case to PascalCase.
+ * Example: "clipboard-text" -> "ClipboardText"
+ */
+export function toPascalCase(str: string): string {
+  return str
+    .split("-")
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join("");
+}
+
+/**
+ * Convert PascalCase to SCREAMING_SNAKE_CASE.
+ * Example: "ClipboardText" -> "CLIPBOARD_TEXT"
+ */
+export function toScreamingSnakeCase(str: string): string {
+  return str
+    .replace(/([a-z])([A-Z])/g, "$1_$2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
+    .toUpperCase();
+}
+
+// =============================================================================
+// Balanced Brace Extraction
+// =============================================================================
+
+/**
+ * Extract a balanced brace block starting from a position in the string.
+ * Returns the content between the outermost braces, or null if unbalanced.
+ */
+export function extractBalancedBraces(
+  content: string,
+  startIndex: number,
+): string | null {
+  let depth = 0;
+  let start = -1;
+
+  for (let i = startIndex; i < content.length; i++) {
+    if (content[i] === "{") {
+      if (depth === 0) start = i;
+      depth++;
+    } else if (content[i] === "}") {
+      depth--;
+      if (depth === 0 && start !== -1) {
+        return content.substring(start, i + 1);
+      }
+    }
+  }
+  return null;
+}
+
+// =============================================================================
+// Semantic Color Parsing
+// =============================================================================
+
+let _semanticColorNames: string[] | null = null;
+
+/**
+ * Parse theme-kumo.css to extract semantic color names from --color-* and --text-color-* variables.
+ * Excludes raw palette colors (e.g., --color-red-650, --color-neutral-50) which have numeric suffixes.
+ * Results are cached for performance.
+ */
+export function parseSemanticColorNames(): string[] {
+  if (_semanticColorNames) {
+    return _semanticColorNames;
+  }
+
+  const themePath = join(__dirname, "../../src/styles/theme-kumo.css");
+  const content = readFileSync(themePath, "utf-8");
+
+  const colorNames = new Set<string>();
+
+  // Match semantic color variable declarations that use light-dark()
+  // Pattern: "--color-<name>: light-dark(" or "--text-color-<name>: light-dark("
+  // This excludes raw palette colors which are defined with direct values like "oklch(...)"
+  const semanticColorPattern =
+    /--(?:text-)?color-([a-zA-Z][a-zA-Z0-9-]*)\s*:\s*light-dark\(/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = semanticColorPattern.exec(content)) !== null) {
+    colorNames.add(match[1]);
+  }
+
+  _semanticColorNames = [...colorNames].sort();
+  return _semanticColorNames;
+}
+
+// Utility prefixes that use color tokens
+const COLOR_UTILITY_PREFIXES = [
+  "text",
+  "bg",
+  "ring",
+  "outline",
+  "fill",
+  "border",
+];
+
+/**
+ * Extract semantic color classes used in a source file.
+ * Returns array of Tailwind classes like ["bg-kumo-base", "text-kumo-subtle"].
+ */
+export function extractSemanticColors(sourceFile: string): string[] {
+  try {
+    const content = readFileSync(sourceFile, "utf-8");
+    const matches: string[] = [];
+    const semanticColorNames = parseSemanticColorNames();
+
+    // Build regex pattern for each prefix + semantic color combination
+    // Match patterns like: text-surface, bg-primary, border-color, ring-kumo-line
+    // Also handles variants like: hover:bg-primary, disabled:text-kumo-subtle
+    for (const prefix of COLOR_UTILITY_PREFIXES) {
+      for (const colorName of semanticColorNames) {
+        // Escape hyphens for regex and create pattern
+        const pattern = new RegExp(
+          `(?:[\\w\\[\\]=_-]+:)*(${prefix}-${colorName})(?![a-zA-Z0-9-])`,
+          "g",
+        );
+        let match: RegExpExecArray | null;
+        while ((match = pattern.exec(content)) !== null) {
+          matches.push(match[1]);
+        }
+      }
+    }
+
+    return [...new Set(matches)].sort();
+  } catch {
+    return [];
+  }
+}
+
+// =============================================================================
+// State Class Extraction
+// =============================================================================
+
+/**
+ * Extract state-specific classes from a class string.
+ * Identifies hover:*, focus:*, active:*, disabled:*, not-disabled:* prefixes.
+ * Also handles complex selectors like [&:hover>span], [&:focus-within>span].
+ */
+export function extractStateClasses(
+  classString: string,
+): Record<string, string> {
+  const states: Record<string, string> = {};
+
+  // Split by whitespace to process each class individually
+  const classes = classString.split(/\s+/);
+
+  for (const cls of classes) {
+    if (!cls) continue;
+
+    // Check for hover states
+    if (cls.startsWith("hover:") || cls.match(/^\[&:hover[^\]]*\]:/)) {
+      states.hover = states.hover ? `${states.hover} ${cls}` : cls;
+    }
+    // Check for focus states (focus, focus-visible, focus-within)
+    else if (
+      cls.match(/^(focus|focus-visible|focus-within):/) ||
+      cls.match(/^\[&:focus(-visible|-within)?[^\]]*\]:/)
+    ) {
+      states.focus = states.focus ? `${states.focus} ${cls}` : cls;
+    }
+    // Check for active state
+    else if (cls.startsWith("active:")) {
+      states.active = states.active ? `${states.active} ${cls}` : cls;
+    }
+    // Check for disabled state
+    else if (cls.startsWith("disabled:")) {
+      states.disabled = states.disabled ? `${states.disabled} ${cls}` : cls;
+    }
+    // Check for not-disabled state
+    else if (cls.startsWith("not-disabled:")) {
+      states["not-disabled"] = states["not-disabled"]
+        ? `${states["not-disabled"]} ${cls}`
+        : cls;
+    }
+    // Check for data-state
+    else if (cls.match(/^data-\[state=[^\]]+\]:/)) {
+      states["data-state"] = states["data-state"]
+        ? `${states["data-state"]} ${cls}`
+        : cls;
+    }
+  }
+
+  return states;
+}
+
+// =============================================================================
+// Block Dependency Extraction
+// =============================================================================
+
+/**
+ * Extract component dependencies from a block file.
+ * Returns array of component names imported from "../../components/*"
+ * Example: import { Tabs } from "../../components/tabs" -> ["Tabs"]
+ */
+export function extractBlockDependencies(sourceFile: string): string[] {
+  try {
+    const content = readFileSync(sourceFile, "utf-8");
+    const dependencies = new Set<string>();
+
+    // Match imports from ../../components/* or ../../blocks/*
+    // Pattern: import { Foo, Bar } from "../../components/something"
+    // Pattern: import { Foo } from "../../blocks/something"
+    const importPattern =
+      /import\s+(?:type\s+)?\{([^}]+)\}\s+from\s+["']\.\.\/\.\.\/(?:components|blocks)\/[^"']+["']/g;
+    let match: RegExpExecArray | null;
+
+    while ((match = importPattern.exec(content)) !== null) {
+      const importList = match[1];
+      // Split by comma and extract component names
+      const items = importList
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+
+      for (const item of items) {
+        // Skip type imports
+        if (item.startsWith("type ")) {
+          continue;
+        }
+        // Extract name (handle "Foo as Bar" -> "Foo")
+        const nameMatch = item.match(/^(\w+)(?:\s+as\s+\w+)?/);
+        if (nameMatch) {
+          dependencies.add(nameMatch[1]);
+        }
+      }
+    }
+
+    return [...dependencies].sort();
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Get all files for a block (main file + stories + tests if they exist)
+ * Returns array of file paths relative to the blocks directory
+ */
+export function getBlockFiles(blockDir: string, dirName: string): string[] {
+  const files: string[] = [];
+
+  // Main file (always exists)
+  files.push(`${dirName}/${dirName}.tsx`);
+
+  // Check for stories
+  const storiesPath = join(blockDir, dirName, `${dirName}.stories.tsx`);
+  try {
+    readFileSync(storiesPath);
+    files.push(`${dirName}/${dirName}.stories.tsx`);
+  } catch {
+    // Stories file doesn't exist
+  }
+
+  // Check for tests
+  const testPath = join(blockDir, dirName, `${dirName}.test.tsx`);
+  try {
+    readFileSync(testPath);
+    files.push(`${dirName}/${dirName}.test.tsx`);
+  } catch {
+    // Test file doesn't exist
+  }
+
+  return files;
+}

package/scripts/component-registry/variant-parser.ts

@@ -0,0 +1,261 @@
+/**
+ * Variant parsing for component registry generation.
+ *
+ * Extracts KUMO_*_VARIANTS, KUMO_*_DEFAULT_VARIANTS, and KUMO_*_STYLING from component files
+ * using regex parsing to avoid import issues with JSX/React dependencies.
+ */
+
+import { readFileSync } from "node:fs";
+import { extractBalancedBraces, extractStateClasses } from "./utils.js";
+import type { ComponentStyling } from "./types.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface ExtractedVariants {
+  // biome-ignore lint/suspicious/noExplicitAny: Variants have varying shapes
+  variants: Record<string, Record<string, any>>;
+  defaults: Record<string, string>;
+  baseStyles: string | null;
+}
+
+// =============================================================================
+// Base Styles Extraction
+// =============================================================================
+
+/**
+ * Extract KUMO_*_BASE_STYLES from a component file.
+ * Returns the base styles string or null if not found.
+ */
+export function extractBaseStylesFromFile(filePath: string): string | null {
+  try {
+    const content = readFileSync(filePath, "utf-8");
+
+    // Match: export const KUMO_*_BASE_STYLES = "..." or '...' or `...`
+    // Handles multi-line strings with template literals
+    const baseStylesMatch = content.match(
+      /export\s+const\s+KUMO_\w+_BASE_STYLES\s*=\s*["'`]([^"'`]+)["'`]/,
+    );
+
+    if (baseStylesMatch) {
+      return baseStylesMatch[1].trim();
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// =============================================================================
+// Variants Object Parsing
+// =============================================================================
+
+/**
+ * Parse a variants object string into a structured object.
+ * Extracts variant keys and their descriptions.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Variants have varying shapes
+export function parseVariantsObject(
+  objStr: string,
+): Record<string, Record<string, any>> {
+  // biome-ignore lint/suspicious/noExplicitAny: Variants have varying shapes
+  const result: Record<string, Record<string, any>> = {};
+
+  // Find top-level property names (e.g., shape, size, variant)
+  // These are identifiers followed by `: {` at the first nesting level
+  const topLevelPropPattern = /^\s*(\w+)\s*:\s*\{/gm;
+  let propMatch: RegExpExecArray | null;
+
+  while ((propMatch = topLevelPropPattern.exec(objStr)) !== null) {
+    const propName = propMatch[1];
+
+    // Skip nested properties like classes, description
+    if (["classes", "description"].includes(propName)) continue;
+
+    // Extract the balanced brace block for this property
+    const propStartIndex = propMatch.index + propMatch[0].length - 1; // Start at the {
+    const propBlock = extractBalancedBraces(objStr, propStartIndex);
+
+    if (!propBlock) continue;
+
+    // Now parse the variant values within this block
+    // biome-ignore lint/suspicious/noExplicitAny: Variants have varying shapes
+    const variants: Record<string, any> = {};
+    // Match variant names including quoted keys like "secondary-destructive"
+    const variantPropPattern = /^\s*(?:"([^"]+)"|'([^']+)'|(\w+))\s*:\s*\{/gm;
+    let variantMatch: RegExpExecArray | null;
+
+    while ((variantMatch = variantPropPattern.exec(propBlock)) !== null) {
+      // Capture group 1 = double-quoted, 2 = single-quoted, 3 = unquoted
+      const variantName = variantMatch[1] || variantMatch[2] || variantMatch[3];
+
+      // Skip nested properties
+      if (["classes", "description"].includes(variantName)) continue;
+
+      // Extract the balanced brace block for this variant
+      const variantStartIndex = variantMatch.index + variantMatch[0].length - 1;
+      const variantBlock = extractBalancedBraces(propBlock, variantStartIndex);
+
+      if (!variantBlock) continue;
+
+      // Extract description if present
+      const descMatch = variantBlock.match(
+        /description\s*:\s*["']([^"']*)["']/,
+      );
+      // Extract classes if present (for Figma plugin consumption)
+      const classesMatch = variantBlock.match(/classes\s*:\s*["']([^"']*)["']/);
+
+      // Extract state classes from the classes string
+      const stateClasses = classesMatch
+        ? extractStateClasses(classesMatch[1])
+        : {};
+
+      variants[variantName] = {
+        description: descMatch ? descMatch[1] : undefined,
+        ...(classesMatch && { classes: classesMatch[1] }),
+        ...(Object.keys(stateClasses).length > 0 && { stateClasses }),
+      };
+    }
+
+    if (Object.keys(variants).length > 0) {
+      result[propName] = variants;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Parse a defaults object string into a key-value map.
+ */
+export function parseDefaultsObject(objStr: string): Record<string, string> {
+  const result: Record<string, string> = {};
+
+  // Match properties like: variant: "primary", size: "base"
+  const propPattern = /(\w+)\s*:\s*["']([^"']*)["']/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = propPattern.exec(objStr)) !== null) {
+    result[match[1]] = match[2];
+  }
+
+  return result;
+}
+
+// =============================================================================
+// Main Extraction
+// =============================================================================
+
+/**
+ * Extract KUMO_*_VARIANTS and KUMO_*_DEFAULT_VARIANTS from a component file.
+ * Uses regex parsing to avoid import issues with JSX/React dependencies.
+ */
+export function extractVariantsFromFile(
+  filePath: string,
+): ExtractedVariants | null {
+  try {
+    const content = readFileSync(filePath, "utf-8");
+
+    // Find KUMO_*_VARIANTS export start position
+    const variantsStartMatch = content.match(
+      /export\s+const\s+KUMO_\w+_VARIANTS\s*=\s*/,
+    );
+    // Find KUMO_*_DEFAULT_VARIANTS export start position
+    const defaultsStartMatch = content.match(
+      /export\s+const\s+KUMO_\w+_DEFAULT_VARIANTS\s*=\s*/,
+    );
+
+    if (!variantsStartMatch || !defaultsStartMatch) {
+      return null;
+    }
+
+    // Extract balanced brace content for variants
+    const variantsStartIndex =
+      (variantsStartMatch.index ?? 0) + variantsStartMatch[0].length;
+    const variantsBlock = extractBalancedBraces(content, variantsStartIndex);
+
+    // Extract balanced brace content for defaults
+    const defaultsStartIndex =
+      (defaultsStartMatch.index ?? 0) + defaultsStartMatch[0].length;
+    const defaultsBlock = extractBalancedBraces(content, defaultsStartIndex);
+
+    if (!variantsBlock || !defaultsBlock) {
+      return null;
+    }
+
+    // Parse the variants object (may be empty for components without variants)
+    const variants = parseVariantsObject(variantsBlock);
+    const defaults = parseDefaultsObject(defaultsBlock);
+
+    // Extract base styles if present
+    const baseStyles = extractBaseStylesFromFile(filePath);
+
+    // Return even if variants is empty - component still has props to document
+    return { variants, defaults, baseStyles };
+  } catch {
+    return null;
+  }
+}
+
+// =============================================================================
+// Styling Extraction
+// =============================================================================
+
+/**
+ * Parse a styling object string into a ComponentStyling object.
+ * Handles nested objects like container, title, description, closeButton, etc.
+ */
+function parseStylingObject(objStr: string): ComponentStyling | null {
+  try {
+    // Remove 'as const' suffix if present
+    const cleanedStr = objStr.replace(/\s*as\s+const\s*$/, "");
+
+    // Use Function constructor to safely evaluate the object literal
+    // This is safe because we control the input (it comes from our own source files)
+    // biome-ignore lint/security/noGlobalEval: Safe evaluation of known source file content
+    const parsed = new Function(`return ${cleanedStr}`)();
+
+    return parsed as ComponentStyling;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extract KUMO_*_STYLING from a component file.
+ * Returns the styling object or null if not found.
+ *
+ * This allows components to define Figma-specific styling metadata
+ * that gets automatically picked up by the registry generator.
+ */
+export function extractStylingFromFile(
+  filePath: string,
+): ComponentStyling | null {
+  try {
+    const content = readFileSync(filePath, "utf-8");
+
+    // Find KUMO_*_STYLING export start position
+    const stylingStartMatch = content.match(
+      /export\s+const\s+KUMO_\w+_STYLING\s*=\s*/,
+    );
+
+    if (!stylingStartMatch) {
+      return null;
+    }
+
+    // Extract balanced brace content for styling
+    const stylingStartIndex =
+      (stylingStartMatch.index ?? 0) + stylingStartMatch[0].length;
+    const stylingBlock = extractBalancedBraces(content, stylingStartIndex);
+
+    if (!stylingBlock) {
+      return null;
+    }
+
+    return parseStylingObject(stylingBlock);
+  } catch {
+    return null;
+  }
+}

package/scripts/css-build.ts

@@ -0,0 +1,55 @@
+import { copyFileSync, mkdirSync, existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { execSync } from "child_process";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const srcDir = join(__dirname, "../src/styles");
+const distDir = join(__dirname, "../dist/styles");
+
+// Create dist/styles directory if it doesn't exist
+if (!existsSync(distDir)) {
+  mkdirSync(distDir, { recursive: true });
+}
+
+// Copy CSS files for Tailwind users (raw CSS with Tailwind directives)
+const cssFiles: string[] = [
+  "kumo.css",
+  "kumo-binding.css",
+  "theme-kumo.css",
+  "theme-fedramp.css",
+];
+
+cssFiles.forEach((file) => {
+  const srcPath = join(srcDir, file);
+  const distPath = join(distDir, file);
+
+  if (existsSync(srcPath)) {
+    copyFileSync(srcPath, distPath);
+    console.log(`✓ Copied ${file} to dist/styles/ (Tailwind version)`);
+  } else {
+    console.warn(`⚠ Warning: ${file} not found in src/styles/`);
+  }
+});
+
+// Compile standalone CSS for non-Tailwind users
+console.log("📦 Compiling standalone CSS...");
+try {
+  const standaloneInput = join(srcDir, "kumo-standalone.css");
+  const standaloneOutput = join(distDir, "kumo-standalone.css");
+
+  // Use Tailwind CLI to compile the CSS
+  execSync(
+    `npx tailwindcss -i ${standaloneInput} -o ${standaloneOutput} --minify`,
+    { stdio: "inherit" },
+  );
+
+  console.log("✓ Compiled kumo-standalone.css");
+} catch (error) {
+  console.error("❌ Failed to compile standalone CSS:", error);
+  process.exit(1);
+}
+
+console.log("✅ CSS build complete");