@signalflare-ai/ui 0.5.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.slice(start, i + 1);
+      }
+    }
+  }
+  return null;
+}
+
+// =============================================================================
+// Semantic Color Parsing
+// =============================================================================
+
+let _semanticColorNames: string[] | null = null;
+
+/**
+ * Parse theme-sf.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-sf.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-sf-base", "text-sf-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-sf-line
+    // Also handles variants like: hover:bg-primary, disabled:text-sf-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 (/^data-\[state=[^\]]+\]:/.test(cls)) {
+      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,262 @@
+/**
+ * Variant parsing for component registry generation.
+ *
+ * Extracts SF_*_VARIANTS, SF_*_DEFAULT_VARIANTS, and SF_*_STYLING from component files
+ * using regex parsing to avoid import issues with JSX/React dependencies.
+ */
+
+import { readFileSync } from "node:fs";
+
+import type { ComponentStyling } from "./types.js";
+import { extractBalancedBraces, extractStateClasses } from "./utils.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 SF_*_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 SF_*_BASE_STYLES = "..." or '...' or `...`
+    // Handles multi-line strings with template literals
+    const baseStylesMatch = content.match(
+      /export\s+const\s+SF_\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 SF_*_VARIANTS and SF_*_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 SF_*_VARIANTS export start position
+    const variantsStartMatch = content.match(
+      /export\s+const\s+SF_\w+_VARIANTS\s*=\s*/
+    );
+    // Find SF_*_DEFAULT_VARIANTS export start position
+    const defaultsStartMatch = content.match(
+      /export\s+const\s+SF_\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)
+    // oxlint-disable-next-line eslint/no-new-func, typescript/no-implied-eval
+    const parsed = new Function(`return ${cleanedStr}`)();
+
+    return parsed as ComponentStyling;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extract SF_*_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 SF_*_STYLING export start position
+    const stylingStartMatch = content.match(
+      /export\s+const\s+SF_\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,117 @@
+import { execFileSync } from "node:child_process";
+import {
+  copyFileSync,
+  mkdirSync,
+  existsSync,
+  readdirSync,
+  statSync,
+} from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const srcDir = join(__dirname, "../src/styles");
+const distDir = join(__dirname, "../dist/styles");
+const blocksSrcDir = join(__dirname, "../src/blocks");
+const blocksDistDir = join(__dirname, "../dist/src/blocks");
+
+// 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[] = [
+  "sf.css",
+  "sf-binding.css",
+  "theme-sf.css",
+  "theme-fedramp.css",
+  "theme-minimal.css",
+  "theme-navigator.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, "sf-standalone.css");
+  const standaloneOutput = join(distDir, "sf-standalone.css");
+
+  // Tailwind v4 exposes its CLI via @tailwindcss/cli, not the tailwindcss package.
+  execFileSync(
+    "bunx",
+    [
+      "@tailwindcss/cli",
+      "-i",
+      standaloneInput,
+      "-o",
+      standaloneOutput,
+      "--minify",
+    ],
+    { stdio: "inherit" }
+  );
+
+  console.log("✓ Compiled sf-standalone.css");
+} catch (error) {
+  console.error("❌ Failed to compile standalone CSS:", error);
+  process.exit(1);
+}
+
+console.log("✅ CSS build complete");
+
+// Copy block source files to dist for CLI `sf add` command
+console.log("📦 Copying block source files...");
+
+function copyBlockFiles(srcDir: string, destDir: string): void {
+  if (!existsSync(srcDir)) {
+    console.warn(`⚠ Warning: blocks source directory not found at ${srcDir}`);
+    return;
+  }
+
+  const blockDirs = readdirSync(srcDir).filter((item) => {
+    const itemPath = join(srcDir, item);
+    return statSync(itemPath).isDirectory();
+  });
+
+  for (const blockDir of blockDirs) {
+    const blockSrcPath = join(srcDir, blockDir);
+    const blockDestPath = join(destDir, blockDir);
+
+    // Create destination directory
+    if (!existsSync(blockDestPath)) {
+      mkdirSync(blockDestPath, { recursive: true });
+    }
+
+    // Copy only .tsx files (source files needed by CLI)
+    // We skip index.ts barrel files to avoid TypeScript resolution issues
+    // in other packages that might reference dist/src/blocks
+    const files = readdirSync(blockSrcPath);
+    for (const file of files) {
+      if (file.endsWith(".tsx")) {
+        const srcFile = join(blockSrcPath, file);
+        const destFile = join(blockDestPath, file);
+        // Only copy if it's a file (not directory)
+        if (statSync(srcFile).isFile()) {
+          copyFileSync(srcFile, destFile);
+          console.log(`  ✓ Copied ${blockDir}/${file}`);
+        }
+      }
+    }
+  }
+}
+
+copyBlockFiles(blocksSrcDir, blocksDistDir);
+console.log("✅ Block source files copied");