@almadar/ui 5.128.0 → 5.130.0

package/scripts/audit-tailwind-safelist.ts

@@ -0,0 +1,237 @@
+#!/usr/bin/env npx tsx
+/**
+ * Tailwind Safelist Audit
+ *
+ * Scans all @almadar/ui source files for Tailwind classes that need
+ * to be in the safelist (because consuming apps can't extract them
+ * from compiled dist/ files). Compares against the current safelist
+ * in tailwind-preset.cjs and reports missing entries.
+ *
+ * Classes that need safelisting:
+ * 1. Arbitrary value classes: bg-[var(--color-X)], min-h-[200px], etc.
+ * 2. Opacity modifiers on semantic colors: bg-primary/10, text-foreground/60
+ * 3. Responsive prefixes on dynamic values: sm:grid-cols-2
+ * 4. State prefixes on CSS vars: hover:bg-[var(--color-X)]
+ *
+ * Standard utility classes (flex, p-4, rounded-lg) are fine because
+ * the shell template's tailwind.config.js includes the dist/ path in
+ * content scanning. But CSS-variable-based arbitrary classes use bracket
+ * notation that Tailwind can't extract from minified JS.
+ *
+ * Usage:
+ *   npx tsx scripts/audit-tailwind-safelist.ts
+ *   npx tsx scripts/audit-tailwind-safelist.ts --fix  (appends missing to preset)
+ *
+ * @packageDocumentation
+ */
+
+import { readFileSync, writeFileSync, readdirSync, statSync } from 'fs';
+import { join, relative } from 'path';
+
+const ROOT = join(import.meta.dirname, '..');
+const PRESET_PATH = join(ROOT, 'tailwind-preset.cjs');
+const SCAN_DIRS = ['components', 'runtime', 'renderer', 'context', 'providers', 'hooks'];
+
+// ---------------------------------------------------------------------------
+// Regex patterns for classes that need safelisting
+// ---------------------------------------------------------------------------
+
+// Matches arbitrary value classes: bg-[var(...)], min-h-[200px], w-[300px], etc.
+// Requires a hyphen before the bracket to avoid matching JS array access like arr[0]
+const ARBITRARY_RE = /(?:^|\s|["'`])([a-z][a-z0-9]*(?::[a-z][a-z0-9-]*)+-\[[^\]]+\]|[a-z][a-z0-9]*-[a-z0-9-]*-\[[^\]]+\]|[a-z][a-z0-9]*-\[[^\]]+\])/g;
+
+// Matches opacity modifiers on semantic colors: bg-primary/10, text-foreground/60
+const OPACITY_RE = /(?:^|\s|["'`])((?:bg|text|border|ring|from|to|via|hover:bg|hover:text|hover:border|dark:bg|dark:hover:bg|group-hover:bg|group-hover:text|peer-focus:ring|focus:ring)-(?:primary|secondary|muted|accent|foreground|card|surface|background|border|error|success|warning|info|ring|input|muted-foreground|card-foreground|primary-foreground|secondary-foreground|error-foreground|success-foreground|warning-foreground|info-foreground)\/\d+)/g;
+
+// Matches classes with [var(--...)] or [length:var(--...)]
+const CSS_VAR_RE = /(?:^|\s|["'`])([a-z][a-z0-9-]*(?::[a-z][a-z0-9-]*)*-\[(?:length:|color:)?var\(--[a-z0-9-]+\)[^\]]*\])/g;
+
+// ---------------------------------------------------------------------------
+// File scanner
+// ---------------------------------------------------------------------------
+
+function getAllFiles(dir: string, ext = '.tsx'): string[] {
+  const results: string[] = [];
+  try {
+    for (const entry of readdirSync(dir)) {
+      const full = join(dir, entry);
+      const stat = statSync(full);
+      if (stat.isDirectory() && entry !== 'node_modules' && entry !== 'dist' && entry !== '.storybook') {
+        results.push(...getAllFiles(full, ext));
+      } else if (entry.endsWith(ext) || entry.endsWith('.ts')) {
+        results.push(full);
+      }
+    }
+  } catch {
+    // directory doesn't exist
+  }
+  return results;
+}
+
+function extractSafelistCandidates(content: string): Set<string> {
+  const candidates = new Set<string>();
+
+  // Find arbitrary value classes
+  for (const match of content.matchAll(ARBITRARY_RE)) {
+    const cls = match[1];
+    if (cls && !cls.startsWith('//') && !cls.startsWith('*')) {
+      candidates.add(cls);
+    }
+  }
+
+  // Find opacity modifier classes
+  for (const match of content.matchAll(OPACITY_RE)) {
+    if (match[1]) candidates.add(match[1]);
+  }
+
+  // Find CSS variable classes
+  for (const match of content.matchAll(CSS_VAR_RE)) {
+    if (match[1]) candidates.add(match[1]);
+  }
+
+  return candidates;
+}
+
+// ---------------------------------------------------------------------------
+// Safelist parser
+// ---------------------------------------------------------------------------
+
+function getCurrentSafelist(): Set<string> {
+  const content = readFileSync(PRESET_PATH, 'utf-8');
+  const safelist = new Set<string>();
+
+  // Find the safelist array - match from 'safelist: [' to the matching ']'
+  const startIdx = content.indexOf('safelist:');
+  if (startIdx === -1) return safelist;
+
+  const bracketStart = content.indexOf('[', startIdx);
+  if (bracketStart === -1) return safelist;
+
+  // Find the matching closing bracket (handle nested brackets)
+  let depth = 0;
+  let bracketEnd = -1;
+  for (let i = bracketStart; i < content.length; i++) {
+    if (content[i] === '[') depth++;
+    if (content[i] === ']') {
+      depth--;
+      if (depth === 0) { bracketEnd = i; break; }
+    }
+  }
+  if (bracketEnd === -1) return safelist;
+
+  const safelistContent = content.slice(bracketStart + 1, bracketEnd);
+  const entries = safelistContent.matchAll(/['"]([^'"]+)['"]/g);
+  for (const m of entries) {
+    if (m[1]) safelist.add(m[1]);
+  }
+
+  return safelist;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+const fix = process.argv.includes('--fix');
+
+console.log('Tailwind Safelist Audit');
+console.log('='.repeat(60));
+console.log(`Scanning: ${SCAN_DIRS.join(', ')}`);
+console.log(`Preset: ${relative(ROOT, PRESET_PATH)}`);
+console.log();
+
+// Scan all source files
+const allCandidates = new Map<string, Set<string>>(); // class -> set of files
+let fileCount = 0;
+
+for (const dir of SCAN_DIRS) {
+  const files = getAllFiles(join(ROOT, dir));
+  for (const file of files) {
+    if (file.includes('.stories.') || file.includes('.test.') || file.includes('.spec.')) continue;
+    fileCount++;
+    const content = readFileSync(file, 'utf-8');
+    const candidates = extractSafelistCandidates(content);
+    for (const cls of candidates) {
+      if (!allCandidates.has(cls)) allCandidates.set(cls, new Set());
+      allCandidates.get(cls)!.add(relative(ROOT, file));
+    }
+  }
+}
+
+console.log(`Scanned ${fileCount} files, found ${allCandidates.size} safelist candidates`);
+console.log();
+
+// Compare against current safelist
+const currentSafelist = getCurrentSafelist();
+const missing: Array<{ cls: string; files: string[] }> = [];
+const alreadySafe: string[] = [];
+
+for (const [cls, files] of allCandidates) {
+  if (currentSafelist.has(cls)) {
+    alreadySafe.push(cls);
+  } else {
+    missing.push({ cls, files: Array.from(files) });
+  }
+}
+
+// Also exclude standard utility classes that Tailwind extracts from dist/ scanning.
+// Only arbitrary values ([...]), opacity modifiers (/N), and CSS var classes need safelisting.
+const needsSafelist = (cls: string) =>
+  cls.includes('[') || cls.includes('/') || cls.includes('var(');
+
+const filtered = missing.filter(m => needsSafelist(m.cls));
+const skipped = missing.filter(m => !needsSafelist(m.cls));
+missing.length = 0;
+missing.push(...filtered);
+
+// Report
+console.log(`Current safelist: ${currentSafelist.size} entries`);
+console.log(`Already safelisted: ${alreadySafe.length}`);
+console.log(`Standard utilities (no safelist needed): ${skipped.length}`);
+console.log(`Missing from safelist: ${missing.length}`);
+console.log();
+
+if (missing.length === 0) {
+  console.log('All safelist candidates are covered. No changes needed.');
+  process.exit(0);
+}
+
+// Sort missing by class name
+missing.sort((a, b) => a.cls.localeCompare(b.cls));
+
+console.log('Missing classes:');
+for (const { cls, files } of missing) {
+  console.log(`  ${cls}`);
+  for (const f of files.slice(0, 3)) {
+    console.log(`    <- ${f}`);
+  }
+  if (files.length > 3) {
+    console.log(`    ... and ${files.length - 3} more files`);
+  }
+}
+
+if (fix) {
+  console.log();
+  console.log('Appending missing classes to safelist...');
+
+  const presetContent = readFileSync(PRESET_PATH, 'utf-8');
+
+  // Find the end of the safelist array and insert before the closing ]
+  const safelistEndIdx = presetContent.indexOf('],', presetContent.indexOf('safelist:'));
+  if (safelistEndIdx === -1) {
+    console.error('Could not find safelist closing bracket in preset file');
+    process.exit(1);
+  }
+
+  const newEntries = missing.map(m => `  '${m.cls}',`).join('\n');
+  const comment = `  // Auto-added by audit-tailwind-safelist.ts (${new Date().toISOString().split('T')[0]})`;
+  const updated = presetContent.slice(0, safelistEndIdx) +
+    '\n' + comment + '\n' + newEntries + '\n' +
+    presetContent.slice(safelistEndIdx);
+
+  writeFileSync(PRESET_PATH, updated, 'utf-8');
+  console.log(`Added ${missing.length} classes to safelist.`);
+} else {
+  console.log();
+  console.log('Run with --fix to add missing classes to the preset.');
+}

package/scripts/export-static.js

@@ -0,0 +1,61 @@
+/**
+ * Export Static Design System
+ *
+ * After Storybook build, this script packages the design system
+ * into a client-ready deliverable (PDF or HTML bundle).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const STORYBOOK_DIR = path.join(__dirname, '..', 'storybook-static');
+const OUTPUT_DIR = path.join(__dirname, '..', 'exports');
+
+async function exportDesignSystem() {
+  console.log('📦 Exporting design system...');
+
+  // Ensure output directory exists
+  if (!fs.existsSync(OUTPUT_DIR)) {
+    fs.mkdirSync(OUTPUT_DIR, { recursive: true });
+  }
+
+  // Check if storybook build exists
+  if (!fs.existsSync(STORYBOOK_DIR)) {
+    console.error('❌ Storybook build not found. Run `npm run build-storybook` first.');
+    process.exit(1);
+  }
+
+  // Copy storybook-static to exports with timestamp
+  const timestamp = new Date().toISOString().split('T')[0];
+  const exportName = `design-system-${timestamp}`;
+  const exportPath = path.join(OUTPUT_DIR, exportName);
+
+  // Copy directory
+  fs.cpSync(STORYBOOK_DIR, exportPath, { recursive: true });
+
+  console.log(`✅ Design system exported to: ${exportPath}`);
+  console.log(`   Open ${exportPath}/index.html in a browser to view.`);
+
+  // Create a manifest
+  const manifest = {
+    name: '@orbital/design-system',
+    version: '1.0.0',
+    exportedAt: new Date().toISOString(),
+    themes: ['wireframe', 'minimalist', 'almadar', 'winning-11'],
+    components: {
+      atoms: ['Avatar', 'Badge', 'Button', 'Card', 'Checkbox', 'Divider', 'Input', 'Radio', 'Select', 'Spinner', 'Typography'],
+      molecules: ['Accordion', 'Alert', 'Modal', 'Tabs', 'Toast'],
+      organisms: ['ConfirmDialog', 'DataTable', 'Header', 'Sidebar', 'StatCard', 'WizardContainer'],
+      templates: ['AuthLayout', 'CounterTemplate', 'DashboardLayout', 'GameTemplate', 'GenericAppTemplate'],
+    },
+  };
+
+  fs.writeFileSync(
+    path.join(exportPath, 'manifest.json'),
+    JSON.stringify(manifest, null, 2)
+  );
+
+  console.log(`   Manifest created at: ${exportPath}/manifest.json`);
+}
+
+exportDesignSystem().catch(console.error);

package/scripts/generate-design-system.ts

@@ -0,0 +1,344 @@
+/**
+ * Unified Design System Generator
+ *
+ * Generates a complete client-specific design system from an .orb schema:
+ * 1. Generates custom theme CSS
+ * 2. Suggests domain-specific components
+ * 3. Generates component stubs
+ * 4. Builds Storybook documentation
+ * 5. Exports static design system package
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { execSync } from "child_process";
+import { generateThemeFromSchema } from "./generate-theme-from-schema";
+import {
+  suggestComponents,
+  generateComponentStubs,
+} from "./suggest-components";
+
+interface GeneratorOptions {
+  schemaPath: string;
+  outputDir: string;
+  clientName?: string;
+  buildStorybook?: boolean;
+  generateComponents?: boolean;
+  clientOnly?: boolean; // Only include client-specific components in Storybook
+}
+
+interface GeneratorResult {
+  themePath: string;
+  suggestedComponents: number;
+  generatedComponents: number;
+  storybookPath?: string;
+}
+
+/**
+ * Main generator function
+ */
+export async function generateDesignSystem(
+  options: GeneratorOptions,
+): Promise<GeneratorResult> {
+  const {
+    schemaPath,
+    outputDir,
+    clientName,
+    buildStorybook = true,
+    generateComponents = true,
+    clientOnly = false,
+  } = options;
+
+  console.log("🎨 Orbital Design System Generator");
+  console.log("==================================\n");
+
+  // Validate schema exists
+  if (!fs.existsSync(schemaPath)) {
+    throw new Error(`Schema file not found: ${schemaPath}`);
+  }
+
+  // Read schema to get name
+  const schemaContent = fs.readFileSync(schemaPath, "utf-8");
+  const schema = JSON.parse(schemaContent);
+  const name =
+    clientName || schema.name.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+
+  console.log(`📋 Processing schema: ${schema.name}`);
+  console.log(`📁 Output directory: ${outputDir}\n`);
+
+  // Create output directory
+  const clientOutputDir = path.join(outputDir, name);
+  if (!fs.existsSync(clientOutputDir)) {
+    fs.mkdirSync(clientOutputDir, { recursive: true });
+  }
+
+  // Step 1: Generate theme
+  console.log("1️⃣  Generating theme...");
+  const themePath = path.join(clientOutputDir, `${name}-theme.css`);
+  generateThemeFromSchema(schemaPath, themePath);
+  console.log(`   ✅ Theme generated: ${themePath}\n`);
+
+  // Step 2: Suggest components
+  console.log("2️⃣  Analyzing schema for component suggestions...");
+  const { domains, suggestions } = suggestComponents(schemaPath);
+  console.log(`   📦 Detected domains: ${domains.join(", ") || "none"}`);
+  console.log(`   💡 Suggested components: ${suggestions.length}\n`);
+
+  // Step 3: Generate component stubs
+  let generatedCount = 0;
+  if (generateComponents && suggestions.length > 0) {
+    console.log("3️⃣  Generating component stubs...");
+    const componentsDir = path.join(clientOutputDir, "components");
+    generateComponentStubs(suggestions, componentsDir);
+    generatedCount = suggestions.length;
+    console.log(`   ✅ Generated ${generatedCount} component stubs\n`);
+  }
+
+  // Step 4: Copy theme to design system themes folder for Storybook
+  const designSystemThemesDir = path.join(__dirname, "..", "themes");
+  const targetThemePath = path.join(designSystemThemesDir, `${name}.css`);
+  fs.copyFileSync(themePath, targetThemePath);
+  console.log(`4️⃣  Theme copied to design system: ${targetThemePath}\n`);
+
+  // Update index.css to include the new theme
+  const indexCssPath = path.join(__dirname, "..", "index.css");
+  const indexCss = fs.readFileSync(indexCssPath, "utf-8");
+  const importStatement = `@import './themes/${name}.css';`;
+
+  if (!indexCss.includes(importStatement)) {
+    const updatedCss = indexCss.replace(
+      "@tailwind base;",
+      `${importStatement}\n\n@tailwind base;`,
+    );
+    fs.writeFileSync(indexCssPath, updatedCss);
+    console.log(`   Updated index.css with theme import\n`);
+  }
+
+  // Step 5: Update Storybook preview to include the new theme
+  const previewPath = path.join(__dirname, "..", ".storybook", "preview.tsx");
+  const previewContent = fs.readFileSync(previewPath, "utf-8");
+
+  if (!previewContent.includes(`'${name}':`)) {
+    const updatedPreview = previewContent.replace(
+      "defaultTheme: 'minimalist',",
+      `'${name}': '${name}',\n      },\n      defaultTheme: '${name}',`,
+    );
+    fs.writeFileSync(previewPath, updatedPreview);
+    console.log(`   Updated Storybook preview with theme: ${name}\n`);
+  }
+
+  // Step 6: Build Storybook (optional)
+  let storybookPath: string | undefined;
+  if (buildStorybook) {
+    console.log("5️⃣  Building Storybook...");
+    const designSystemDir = path.join(__dirname, "..");
+
+    // Determine output path for storybook
+    // For client-only, output directly to the output directory (e.g., projects/winning-11/design-system/storybook-static)
+    // For full library, output to clientOutputDir/storybook
+    storybookPath = clientOnly
+      ? path.join(outputDir, "storybook-static")
+      : path.join(clientOutputDir, "storybook");
+
+    try {
+      // Install dependencies if needed
+      if (!fs.existsSync(path.join(designSystemDir, "node_modules"))) {
+        console.log("   Installing dependencies...");
+        execSync("npm install", { cwd: designSystemDir, stdio: "inherit" });
+      }
+
+      if (clientOnly) {
+        // Use the dedicated .storybook-client config and output directly to project
+        console.log(`   📦 Building client-only Storybook for: ${name}`);
+        console.log(`   📁 Output: ${storybookPath}`);
+
+        // Build using client-only config with custom output path
+        execSync(
+          `npx storybook build -c .storybook-client -o "${storybookPath}"`,
+          {
+            cwd: designSystemDir,
+            stdio: "inherit",
+          },
+        );
+      } else {
+        // Build full storybook
+        execSync("npm run build-storybook", {
+          cwd: designSystemDir,
+          stdio: "inherit",
+        });
+
+        // Copy to output
+        const storybookStaticDir = path.join(
+          designSystemDir,
+          "storybook-static",
+        );
+        if (fs.existsSync(storybookStaticDir)) {
+          fs.cpSync(storybookStaticDir, storybookPath, { recursive: true });
+        }
+      }
+
+      console.log(`   ✅ Storybook built: ${storybookPath}\n`);
+    } catch (error) {
+      console.log(
+        "   ⚠️  Storybook build skipped (run manually with npm run build-storybook)\n",
+      );
+      storybookPath = undefined;
+    }
+  }
+
+  // Step 7: Generate client portal and deployment files
+  console.log("6️⃣  Generating client portal and deployment files...");
+  const templatesDir = path.join(__dirname, "..", "..", "templates");
+  const projectRoot = path.join(outputDir, "..");
+
+  // Template variables
+  const projectDisplayName =
+    schema.name ||
+    name.replace(/-/g, " ").replace(/\b\w/g, (c: string) => c.toUpperCase());
+  const projectId = name.toLowerCase().replace(/[^a-z0-9-]/g, "");
+  const generatedDate = new Date().toISOString().split("T")[0];
+  const version = schema.version || "1.0.0";
+
+  const replaceTemplateVars = (content: string): string => {
+    return content
+      .replace(/\{\{PROJECT_NAME\}\}/g, projectDisplayName)
+      .replace(/\{\{PROJECT_ID\}\}/g, projectId)
+      .replace(/\{\{GENERATED_DATE\}\}/g, generatedDate)
+      .replace(/\{\{VERSION\}\}/g, version);
+  };
+
+  // Files to copy and process
+  const templateFiles = [
+    { src: "client-portal.html", dest: "index.html" },
+    { src: "firebase.json", dest: "firebase.json" },
+    { src: ".firebaserc", dest: ".firebaserc" },
+    { src: "deploy.sh", dest: "deploy.sh", executable: true },
+  ];
+
+  for (const file of templateFiles) {
+    const srcPath = path.join(templatesDir, file.src);
+    const destPath = path.join(projectRoot, file.dest);
+
+    if (fs.existsSync(srcPath)) {
+      let content = fs.readFileSync(srcPath, "utf-8");
+      content = replaceTemplateVars(content);
+      fs.writeFileSync(destPath, content);
+
+      if (file.executable) {
+        fs.chmodSync(destPath, "755");
+      }
+
+      console.log(`   ✅ Generated: ${file.dest}`);
+    }
+  }
+  console.log("");
+
+  // Step 8: Generate manifest
+  const manifest = {
+    name: schema.name,
+    clientName: name,
+    generatedAt: new Date().toISOString(),
+    domains,
+    theme: {
+      path: `${name}-theme.css`,
+      variables: extractCssVariables(themePath),
+    },
+    components: {
+      suggested: suggestions.map((s) => ({
+        name: s.name,
+        category: s.category,
+        priority: s.priority,
+      })),
+      generated: generatedCount,
+    },
+    storybook: storybookPath ? "storybook/index.html" : null,
+    clientPortal: "../index.html",
+  };
+
+  const manifestPath = path.join(clientOutputDir, "manifest.json");
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+  console.log(`📄 Manifest generated: ${manifestPath}\n`);
+
+  // Summary
+  console.log("🎉 Design System Generation Complete!");
+  console.log("=====================================");
+  console.log(`   Theme: ${themePath}`);
+  console.log(`   Suggested Components: ${suggestions.length}`);
+  console.log(`   Generated Components: ${generatedCount}`);
+  if (storybookPath) {
+    console.log(`   Storybook: ${storybookPath}/index.html`);
+  }
+  console.log(`   Manifest: ${manifestPath}`);
+  console.log("");
+
+  return {
+    themePath,
+    suggestedComponents: suggestions.length,
+    generatedComponents: generatedCount,
+    storybookPath,
+  };
+}
+
+/**
+ * Extract CSS variable names from a theme file
+ */
+function extractCssVariables(themePath: string): string[] {
+  const content = fs.readFileSync(themePath, "utf-8");
+  const variablePattern = /--([a-z-]+):/g;
+  const variables: string[] = [];
+  let match;
+
+  while ((match = variablePattern.exec(content)) !== null) {
+    if (!variables.includes(`--${match[1]}`)) {
+      variables.push(`--${match[1]}`);
+    }
+  }
+
+  return variables;
+}
+
+// CLI usage
+if (require.main === module) {
+  const args = process.argv.slice(2);
+
+  if (args.length < 1) {
+    console.log(`
+Orbital Design System Generator
+
+Usage:
+  npx tsx generate-design-system.ts <schema.orb> [options]
+
+Options:
+  --output <dir>      Output directory (default: ./exports)
+  --name <name>       Client name override
+  --no-storybook      Skip Storybook build
+  --no-components     Skip component generation
+  --client-only       Only include client-specific components in Storybook (not the full library)
+
+Examples:
+  npx tsx generate-design-system.ts winning-11.orb
+  npx tsx generate-design-system.ts winning-11.orb --output ./clients
+  npx tsx generate-design-system.ts winning-11.orb --name garden-app --no-storybook
+  npx tsx generate-design-system.ts winning-11.orb --client-only
+`);
+    process.exit(1);
+  }
+
+  const schemaPath = args[0];
+  const outputIndex = args.indexOf("--output");
+  const nameIndex = args.indexOf("--name");
+
+  const options: GeneratorOptions = {
+    schemaPath,
+    outputDir:
+      outputIndex !== -1
+        ? args[outputIndex + 1]
+        : path.join(__dirname, "..", "exports"),
+    clientName: nameIndex !== -1 ? args[nameIndex + 1] : undefined,
+    buildStorybook: !args.includes("--no-storybook"),
+    generateComponents: !args.includes("--no-components"),
+    clientOnly: args.includes("--client-only"),
+  };
+
+  generateDesignSystem(options).catch(console.error);
+}