@opencosmos/ui 1.3.1

package/package.json

@@ -0,0 +1,267 @@
+{
+    "name": "@opencosmos/ui",
+    "version": "1.3.1",
+    "description": "Sage Design Engine — Make it Lovable. 100 accessible React components, three themes, user-controlled motion.",
+    "main": "dist/index.js",
+    "module": "dist/index.mjs",
+    "types": "dist/index.d.ts",
+    "sideEffects": false,
+    "license": "MIT",
+    "author": "Shalom Ormsby",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/shalomormsby/sage-design-engine.git",
+        "directory": "packages/ui"
+    },
+    "homepage": "https://thesage.dev",
+    "bugs": "https://github.com/shalomormsby/sage-design-engine/issues",
+    "keywords": [
+        "react",
+        "components",
+        "ui",
+        "design-system",
+        "tailwind",
+        "radix",
+        "accessible",
+        "themes",
+        "mcp",
+        "ai"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "bin": {
+        "opencosmos-ui": "dist/cli.mjs"
+    },
+    "files": [
+        "dist",
+        "src",
+        ".claude",
+        "README.md"
+    ],
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.mjs",
+            "require": "./dist/index.js"
+        },
+        "./tokens": {
+            "types": "./dist/tokens.d.ts",
+            "import": "./dist/tokens.mjs",
+            "require": "./dist/tokens.js"
+        },
+        "./hooks": {
+            "types": "./dist/hooks.d.ts",
+            "import": "./dist/hooks.mjs",
+            "require": "./dist/hooks.js"
+        },
+        "./utils": {
+            "types": "./dist/utils.d.ts",
+            "import": "./dist/utils.mjs",
+            "require": "./dist/utils.js"
+        },
+        "./providers": {
+            "types": "./dist/providers.d.ts",
+            "import": "./dist/providers.mjs",
+            "require": "./dist/providers.js"
+        },
+        "./webgl": {
+            "types": "./dist/webgl.d.ts",
+            "import": "./dist/webgl.mjs",
+            "require": "./dist/webgl.js"
+        },
+        "./forms": {
+            "types": "./dist/forms.d.ts",
+            "import": "./dist/forms.mjs",
+            "require": "./dist/forms.js"
+        },
+        "./dates": {
+            "types": "./dist/dates.d.ts",
+            "import": "./dist/dates.mjs",
+            "require": "./dist/dates.js"
+        },
+        "./tables": {
+            "types": "./dist/tables.d.ts",
+            "import": "./dist/tables.mjs",
+            "require": "./dist/tables.js"
+        },
+        "./dnd": {
+            "types": "./dist/dnd.d.ts",
+            "import": "./dist/dnd.mjs",
+            "require": "./dist/dnd.js"
+        },
+        "./globals.css": "./src/globals.css",
+        "./theme.css": "./src/theme.css"
+    },
+    "scripts": {
+        "build": "tsup",
+        "dev": "tsup --watch",
+        "lint": "eslint src/",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "typecheck": "tsc --noEmit",
+        "size": "size-limit",
+        "size:check": "size-limit --limit"
+    },
+    "size-limit": [
+        {
+            "name": "Core (index)",
+            "path": "dist/index.mjs",
+            "limit": "450 KB"
+        },
+        {
+            "name": "WebGL",
+            "path": "dist/webgl.mjs",
+            "limit": "10 KB"
+        },
+        {
+            "name": "Forms",
+            "path": "dist/forms.mjs",
+            "limit": "11 KB"
+        },
+        {
+            "name": "Dates",
+            "path": "dist/dates.mjs",
+            "limit": "33 KB"
+        },
+        {
+            "name": "Tables",
+            "path": "dist/tables.mjs",
+            "limit": "10 KB"
+        },
+        {
+            "name": "DnD",
+            "path": "dist/dnd.mjs",
+            "limit": "10 KB"
+        },
+        {
+            "name": "Hooks",
+            "path": "dist/hooks.mjs",
+            "limit": "40 KB"
+        },
+        {
+            "name": "Providers",
+            "path": "dist/providers.mjs",
+            "limit": "60 KB"
+        },
+        {
+            "name": "Tokens",
+            "path": "dist/tokens.mjs",
+            "limit": "70 KB"
+        },
+        {
+            "name": "Utils",
+            "path": "dist/utils.mjs",
+            "limit": "25 KB"
+        }
+    ],
+    "peerDependencies": {
+        "@dnd-kit/core": "^6.3.1",
+        "@dnd-kit/sortable": "^10.0.0",
+        "@dnd-kit/utilities": "^3.2.2",
+        "@hookform/resolvers": "^3.10.0",
+        "@tanstack/react-table": "^8.21.3",
+        "date-fns": "^4.1.0",
+        "framer-motion": "*",
+        "react": "*",
+        "react-day-picker": "^9.13.0",
+        "react-hook-form": "^7.70.0",
+        "zod": "^3.24.1"
+    },
+    "peerDependenciesMeta": {
+        "@dnd-kit/core": {
+            "optional": true
+        },
+        "@dnd-kit/sortable": {
+            "optional": true
+        },
+        "@dnd-kit/utilities": {
+            "optional": true
+        },
+        "@hookform/resolvers": {
+            "optional": true
+        },
+        "@tanstack/react-table": {
+            "optional": true
+        },
+        "date-fns": {
+            "optional": true
+        },
+        "react-day-picker": {
+            "optional": true
+        },
+        "react-hook-form": {
+            "optional": true
+        },
+        "zod": {
+            "optional": true
+        }
+    },
+    "dependencies": {
+        "@radix-ui/react-accordion": "^1.2.12",
+        "@radix-ui/react-alert-dialog": "^1.1.15",
+        "@radix-ui/react-aspect-ratio": "^1.1.8",
+        "@radix-ui/react-avatar": "^1.1.11",
+        "@radix-ui/react-checkbox": "^1.3.3",
+        "@radix-ui/react-collapsible": "^1.1.12",
+        "@radix-ui/react-context-menu": "^2.2.16",
+        "@radix-ui/react-dialog": "^1.1.15",
+        "@radix-ui/react-dropdown-menu": "^2.1.16",
+        "@radix-ui/react-hover-card": "^1.1.15",
+        "@radix-ui/react-label": "^2.1.8",
+        "@radix-ui/react-menubar": "^1.1.16",
+        "@radix-ui/react-navigation-menu": "^1.2.14",
+        "@radix-ui/react-popover": "^1.1.15",
+        "@radix-ui/react-progress": "^1.1.8",
+        "@radix-ui/react-radio-group": "^1.3.8",
+        "@radix-ui/react-scroll-area": "^1.2.10",
+        "@radix-ui/react-select": "^2.2.6",
+        "@radix-ui/react-separator": "^1.1.8",
+        "@radix-ui/react-slider": "^1.3.6",
+        "@radix-ui/react-slot": "^1.2.4",
+        "@radix-ui/react-switch": "^1.2.6",
+        "@radix-ui/react-tabs": "^1.1.13",
+        "@radix-ui/react-toggle": "^1.1.10",
+        "@radix-ui/react-toggle-group": "^1.1.11",
+        "@radix-ui/react-tooltip": "^1.2.8",
+        "class-variance-authority": "^0.7.0",
+        "clsx": "^2.1.0",
+        "cmdk": "^1.1.1",
+        "embla-carousel-react": "^8.6.0",
+        "input-otp": "^1.4.2",
+        "lucide-react": "^0.562.0",
+        "react-dropzone": "^15.0.0",
+        "react-resizable-panels": "^4.4.0",
+        "sonner": "^2.0.7",
+        "tailwind-merge": "^3.0.0",
+        "vaul": "^1.1.2",
+        "zustand": "^5.0.9"
+    },
+    "devDependencies": {
+        "@dnd-kit/core": "^6.3.1",
+        "@dnd-kit/sortable": "^10.0.0",
+        "@dnd-kit/utilities": "^3.2.2",
+        "@hookform/resolvers": "^3.10.0",
+        "@size-limit/preset-small-lib": "^12.0.0",
+        "@tanstack/react-table": "^8.21.3",
+        "@testing-library/jest-dom": "^6.9.1",
+        "@testing-library/react": "^16.3.2",
+        "@testing-library/user-event": "^14.6.1",
+        "@types/react": "^19",
+        "date-fns": "^4.1.0",
+        "eslint": "^9.39.2",
+        "eslint-plugin-react-hooks": "^5.2.0",
+        "framer-motion": "^12.26.2",
+        "jsdom": "^28.0.0",
+        "react-day-picker": "^9.13.0",
+        "react-hook-form": "^7.70.0",
+        "size-limit": "^12.0.0",
+        "tailwindcss": "^4.0.0",
+        "@tailwindcss/postcss": "^4.0.0",
+        "tsup": "^8.0.0",
+        "typescript": "^5.0.0",
+        "typescript-eslint": "^8.54.0",
+        "vitest": "^4.0.18",
+        "zod": "^3.24.1"
+    }
+}

package/src/cli.ts

@@ -0,0 +1,206 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync } from 'fs';
+import { join, dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+// ---------------------------------------------------------------------------
+// Resolve package root (works from dist/cli.js → package root)
+// ---------------------------------------------------------------------------
+const __filename_ = typeof __filename !== 'undefined' ? __filename : fileURLToPath(import.meta.url);
+const PKG_ROOT = resolve(dirname(__filename_), '..');
+
+// ---------------------------------------------------------------------------
+// Import transform
+// ---------------------------------------------------------------------------
+export function transformImports(source: string): string {
+  return source
+    // ../../lib/utils → ./utils  (cn utility — we scaffold it alongside)
+    .replace(/from\s+['"]\.\.\/\.\.\/lib\/utils['"]/g, `from './utils'`)
+    // ../../lib/* → @opencosmos/ui/utils
+    .replace(/from\s+['"]\.\.\/\.\.\/lib\/[^'"]+['"]/g, `from '@opencosmos/ui/utils'`)
+    // ../../hooks/* → @opencosmos/ui/hooks
+    .replace(/from\s+['"]\.\.\/\.\.\/hooks\/[^'"]+['"]/g, `from '@opencosmos/ui/hooks'`)
+    // ../category/Component → @opencosmos/ui  (cross-component imports)
+    .replace(/from\s+['"]\.\.\/[^.][^'"]*['"]/g, `from '@opencosmos/ui'`);
+}
+
+// ---------------------------------------------------------------------------
+// cn() utility source (scaffolded alongside ejected components)
+// ---------------------------------------------------------------------------
+const CN_UTILS_SOURCE = `import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+`;
+
+// ---------------------------------------------------------------------------
+// Scan src/components to find a component file by name (case-insensitive)
+// ---------------------------------------------------------------------------
+function findComponent(name: string): { filePath: string; category: string } | null {
+  const srcDir = join(PKG_ROOT, 'src', 'components');
+  if (!existsSync(srcDir)) {
+    return null;
+  }
+
+  const lowerName = name.toLowerCase();
+
+  for (const category of readdirSync(srcDir)) {
+    const categoryPath = join(srcDir, category);
+    if (!statSync(categoryPath).isDirectory()) continue;
+
+    for (const file of readdirSync(categoryPath)) {
+      if (file.toLowerCase() === `${lowerName}.tsx` || file.toLowerCase() === `${lowerName}.ts`) {
+        return { filePath: join(categoryPath, file), category };
+      }
+    }
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// List all available components grouped by category
+// ---------------------------------------------------------------------------
+function listComponents(): void {
+  const srcDir = join(PKG_ROOT, 'src', 'components');
+  if (!existsSync(srcDir)) {
+    console.error('Error: Could not find component source directory.');
+    process.exit(1);
+  }
+
+  console.log('\n  @opencosmos/ui — Available Components\n');
+
+  for (const category of readdirSync(srcDir).sort()) {
+    const categoryPath = join(srcDir, category);
+    if (!statSync(categoryPath).isDirectory()) continue;
+
+    const components = readdirSync(categoryPath)
+      .filter((f) => f.endsWith('.tsx') && !f.startsWith('index') && !f.includes('.test.'))
+      .map((f) => f.replace(/\.tsx$/, ''));
+
+    if (components.length === 0) continue;
+
+    console.log(`  ${category}/`);
+    for (const comp of components.sort()) {
+      console.log(`    ${comp}`);
+    }
+    console.log();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Eject a component
+// ---------------------------------------------------------------------------
+function ejectComponent(name: string, targetDir: string): void {
+  const found = findComponent(name);
+
+  if (!found) {
+    console.error(`\n  Error: Component "${name}" not found.\n`);
+    console.error('  Run `npx @opencosmos/ui eject --list` to see available components.\n');
+    process.exit(1);
+  }
+
+  const source = readFileSync(found.filePath, 'utf-8');
+  const transformed = transformImports(source);
+
+  // Ensure target directory exists
+  const resolvedDir = resolve(process.cwd(), targetDir);
+  mkdirSync(resolvedDir, { recursive: true });
+
+  // Write transformed component
+  const fileName = found.filePath.split('/').pop()!;
+  const destPath = join(resolvedDir, fileName);
+  writeFileSync(destPath, transformed, 'utf-8');
+
+  // Scaffold utils.ts if not present
+  const utilsPath = join(resolvedDir, 'utils.ts');
+  if (!existsSync(utilsPath)) {
+    writeFileSync(utilsPath, CN_UTILS_SOURCE, 'utf-8');
+  }
+
+  // Extract external dependencies from the source for user guidance
+  const deps = new Set<string>();
+  const importRegex = /from\s+['"](@[^/'"]+\/[^'"]+|[^.@/'"][^'"]*)['"]/g;
+  let match;
+  while ((match = importRegex.exec(source)) !== null) {
+    const pkg = match[1];
+    // Skip internal @opencosmos imports and react (always present)
+    if (pkg.startsWith('@opencosmos/') || pkg === 'react') continue;
+    // Normalize scoped packages to package name
+    const pkgName = pkg.startsWith('@') ? pkg.split('/').slice(0, 2).join('/') : pkg.split('/')[0];
+    deps.add(pkgName);
+  }
+
+  console.log(`\n  Ejected ${name} successfully!\n`);
+  console.log(`  ${destPath}`);
+  if (!existsSync(join(resolvedDir, 'utils.ts'))) {
+    // utils was just created
+  }
+  console.log(`  ${utilsPath} (cn utility)\n`);
+
+  if (deps.size > 0) {
+    console.log('  Required dependencies:');
+    console.log(`  pnpm add ${[...deps].sort().join(' ')}\n`);
+  }
+
+  console.log('  Update your imports:');
+  console.log(`  import { ${name} } from './${targetDir}/${name}'\n`);
+  console.log('  The ejected component still works with @opencosmos/ui themes and CSS variables.');
+  console.log('  You now own it — modify freely.\n');
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry point
+// ---------------------------------------------------------------------------
+function main(): void {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+    console.log(`
+  @opencosmos/ui eject — Copy component source into your project
+
+  Usage:
+    npx @opencosmos/ui eject <ComponentName>  [--dir <path>]
+    npx @opencosmos/ui eject --list
+
+  Options:
+    --dir <path>   Target directory (default: src/components/ui)
+    --list         List all available components
+    --help         Show this help message
+
+  Examples:
+    npx @opencosmos/ui eject Button
+    npx @opencosmos/ui eject Dialog --dir components/sage
+`);
+    return;
+  }
+
+  if (args.includes('--list')) {
+    listComponents();
+    return;
+  }
+
+  // Parse: eject <name> [--dir <path>]
+  const command = args[0];
+  if (command !== 'eject') {
+    console.error(`\n  Unknown command: ${command}\n  Run with --help for usage.\n`);
+    process.exit(1);
+  }
+
+  const componentName = args[1];
+  if (!componentName || componentName.startsWith('--')) {
+    console.error('\n  Error: Component name is required.\n  Usage: npx @opencosmos/ui eject <ComponentName>\n');
+    process.exit(1);
+  }
+
+  let targetDir = 'src/components/ui';
+  const dirIdx = args.indexOf('--dir');
+  if (dirIdx !== -1 && args[dirIdx + 1]) {
+    targetDir = args[dirIdx + 1];
+  }
+
+  ejectComponent(componentName, targetDir);
+}
+
+main();

package/src/component-registry.ts

@@ -0,0 +1,183 @@
+/**
+ * Component Registry - Source of Truth
+ *
+ * This file serves as the authoritative source for component counts,
+ * categories, and organization. Used by:
+ * - Documentation (Sage Studio)
+ * - MCP Server registry
+ * - Marketing materials
+ * - Internal tooling
+ *
+ * ⚠️ IMPORTANT: When adding a new component, follow the complete workflow:
+ * See: /.agent/workflows/register-new-component.md
+ *
+ * The workflow includes:
+ * - Creating the component in packages/ui
+ * - Registering in Sage Studio (apps/web)
+ * - Updating THIS registry file
+ * - Updating MCP server registry
+ * - Version bumping and npm publishing
+ *
+ * Last Updated: 2026-02-28
+ */
+
+export const BRAND = {
+  productName: 'Sage Design Engine',
+  productNameShort: 'Sage',
+  themeNames: {
+    organic: 'Terra',
+    technical: 'Volt',
+    neutral: 'Studio',
+  },
+  tagline: "The Solopreneur's Development Stack",
+  mission: 'AI-Native components for velocity',
+} as const;
+
+export const COMPONENT_REGISTRY = {
+  /**
+   * Total count of all exported UI components from @thesage/ui
+   */
+  totalCount: 100,
+
+  /**
+   * Core categories following functional organization pattern
+   * (what components DO, not abstract hierarchy)
+   */
+  coreCategories: {
+    actions: {
+      count: 5,
+      description: 'Components that trigger behavior',
+      examples: ['Button', 'Link', 'Toggle', 'ToggleGroup', 'Magnetic'],
+    },
+    forms: {
+      count: 19,
+      description: 'Components that collect user input',
+      examples: ['Input', 'Select', 'Checkbox', 'Switch', 'Textarea', 'ColorPicker', 'SearchBar', 'FileUpload'],
+    },
+    navigation: {
+      count: 10,
+      description: 'Components that help users move through content',
+      examples: ['Tabs', 'Breadcrumb', 'Pagination', 'NavigationMenu', 'Command'],
+    },
+    overlays: {
+      count: 12,
+      description: 'Components that display contextual content',
+      examples: ['Dialog', 'Tooltip', 'Popover', 'Drawer', 'Modal', 'Sheet', 'NotificationCenter'],
+    },
+    feedback: {
+      count: 9,
+      description: 'Components that communicate system state',
+      examples: ['Alert', 'Toast', 'Progress', 'Spinner', 'Skeleton', 'EmptyState', 'Stepper'],
+    },
+    'data-display': {
+      count: 19,
+      description: 'Components that present information',
+      examples: ['Card', 'Table', 'Badge', 'Avatar', 'Heading', 'Text', 'Code', 'Calendar', 'StatCard', 'Timeline', 'TreeView'],
+    },
+    layout: {
+      count: 18,
+      description: 'Components for spatial organization',
+      examples: ['Accordion', 'Separator', 'Stack', 'Grid', 'Container', 'ScrollArea', 'GlassSurface'],
+    },
+  },
+
+  /**
+   * Specialty categories for advanced interactions and effects
+   */
+  specialtyCategories: {
+    backgrounds: {
+      count: 2,
+      description: 'Animated background effects',
+      examples: ['WarpBackground', 'FaultyTerminal'],
+    },
+    cursor: {
+      count: 2,
+      description: 'Interactive cursor effects',
+      examples: ['SplashCursor', 'TargetCursor'],
+    },
+    blocks: {
+      count: 1,
+      description: 'Composed page blocks',
+      examples: ['Hero', 'OpenGraphCard'],
+    },
+  },
+
+  /**
+   * Supporting APIs (not counted as components)
+   */
+  supportingAPIs: {
+    providers: ['ThemeProvider'],
+    hooks: ['useTheme', 'useMotionPreference', 'useForm'],
+    utilities: ['animations', 'breadcrumbs', 'colors', 'utils', 'validation', 'syntax-parser'],
+    stores: ['themeStore', 'customizerStore'],
+  },
+} as const;
+
+/**
+ * Computed totals
+ */
+export const COMPONENT_COUNTS = {
+  core: Object.values(COMPONENT_REGISTRY.coreCategories).reduce(
+    (sum, cat) => sum + cat.count,
+    0
+  ), // 84
+  specialty: Object.values(COMPONENT_REGISTRY.specialtyCategories).reduce(
+    (sum, cat) => sum + cat.count,
+    0
+  ), // 5
+  total: COMPONENT_REGISTRY.totalCount, // 89
+} as const;
+
+/**
+ * Marketing-friendly descriptions
+ */
+export const MARKETING_COPY = {
+  short: '100 production-ready components',
+  medium: '100 components across 7 core categories, plus specialty backgrounds and motion effects',
+  long: '100 thoughtfully designed components organized by function: actions, forms, navigation, overlays, feedback, data display, and layout—plus specialty components for backgrounds, cursor interactions, and animated effects.',
+} as const;
+
+/**
+ * Documentation usage examples
+ */
+export const DOC_EXAMPLES = {
+  // For overview sections
+  overview: `${COMPONENT_COUNTS.total} components across ${Object.keys(COMPONENT_REGISTRY.coreCategories).length
+    } core categories`,
+
+  // For detailed breakdowns
+  breakdown: `
+- **Actions** (${COMPONENT_REGISTRY.coreCategories.actions.count}): ${COMPONENT_REGISTRY.coreCategories.actions.description}
+- **Forms** (${COMPONENT_REGISTRY.coreCategories.forms.count}): ${COMPONENT_REGISTRY.coreCategories.forms.description}
+- **Navigation** (${COMPONENT_REGISTRY.coreCategories.navigation.count}): ${COMPONENT_REGISTRY.coreCategories.navigation.description}
+- **Overlays** (${COMPONENT_REGISTRY.coreCategories.overlays.count}): ${COMPONENT_REGISTRY.coreCategories.overlays.description}
+- **Feedback** (${COMPONENT_REGISTRY.coreCategories.feedback.count}): ${COMPONENT_REGISTRY.coreCategories.feedback.description}
+- **Data Display** (${COMPONENT_REGISTRY.coreCategories['data-display'].count}): ${COMPONENT_REGISTRY.coreCategories['data-display'].description}
+- **Layout** (${COMPONENT_REGISTRY.coreCategories.layout.count}): ${COMPONENT_REGISTRY.coreCategories.layout.description}
+  `.trim(),
+} as const;
+
+/**
+ * Decision Documentation: Why these numbers?
+ *
+ * **What counts as a component:**
+ * - Any UI element exported from packages/ui/src/index.ts
+ * - Follows React component pattern (returns JSX)
+ * - Can be imported and used directly
+ *
+ * **What doesn't count:**
+ * - Providers (utility, not UI)
+ * - Hooks (utility, not UI)
+ * - Utility functions
+ * - Type definitions
+ *
+ * **Category philosophy:**
+ * - Functional organization (what it DOES, not what it IS)
+ * - Industry standard (matches Material UI, Radix patterns)
+ * - No arbitrary tiers - if exported, it's official
+ *
+ * **Maintenance:**
+ * - Update this file when adding/removing components
+ * - Run: grep -c "^export \* from './components/" packages/ui/src/index.ts
+ * - Verify count matches COMPONENT_REGISTRY.totalCount
+ */