@opencosmos/ui 1.3.1

package/.claude/CLAUDE.md

@@ -0,0 +1,239 @@
+# @thesage/ui — AI Context
+
+> 100 accessible React components | Radix UI + Tailwind CSS | 3 themes | TypeScript strict mode | MIT
+
+## Install
+
+```bash
+pnpm add @thesage/ui
+```
+
+## Provider Hierarchy (Required)
+
+Wrap your app root in this exact order:
+
+```tsx
+import { ThemeProvider, TooltipProvider } from '@thesage/ui/providers'
+import { Toaster } from '@thesage/ui'
+import '@thesage/ui/globals.css'
+
+export default function RootLayout({ children }) {
+  return (
+    <ThemeProvider defaultTheme="studio" defaultMode="system">
+      <TooltipProvider>
+        {children}
+        <Toaster />
+      </TooltipProvider>
+    </ThemeProvider>
+  )
+}
+```
+
+## Import Patterns
+
+```tsx
+// Main exports (most common)
+import { Button, Card, Input, Dialog, Badge } from '@thesage/ui'
+
+// Subpath exports
+import { useMotionPreference, useTheme } from '@thesage/ui/hooks'
+import { ThemeProvider, TooltipProvider } from '@thesage/ui/providers'
+import { cn } from '@thesage/ui/utils'
+import { spacing, typography } from '@thesage/ui/tokens'
+
+// Heavy/optional features (require peer dependencies)
+import { Form, FormField, FormItem } from '@thesage/ui/forms'       // react-hook-form + zod
+import { Calendar, DatePicker } from '@thesage/ui/dates'             // date-fns + react-day-picker
+import { DataTable } from '@thesage/ui/tables'                       // @tanstack/react-table
+import { DragDrop } from '@thesage/ui/dnd'                           // @dnd-kit/*
+```
+
+## Themes
+
+Three themes, each with light and dark modes:
+- **Studio** — Professional, balanced (default)
+- **Terra** — Calm, organic, warm earth tones
+- **Volt** — Bold, electric, cyberpunk neon
+
+```tsx
+import { useTheme } from '@thesage/ui/hooks'
+const { theme, setTheme, mode, setMode } = useTheme()
+setTheme('volt')
+setMode('dark')
+```
+
+## Styling Rules
+
+- Use CSS variables: `bg-background`, `text-foreground`, `border-border`
+- NEVER hardcode colors: no `bg-white`, `text-black`, `bg-neutral-100`
+- All components accept `className` for Tailwind overrides
+- Merge classes with `cn()`: `import { cn } from '@thesage/ui/utils'`
+
+## Motion
+
+Every animation MUST respect user preferences:
+```tsx
+import { useMotionPreference } from '@thesage/ui/hooks'
+const { shouldAnimate, scale } = useMotionPreference()
+```
+
+## Component Categories
+
+| Category | Count | Import | Examples |
+|----------|-------|--------|----------|
+| Actions | 5 | `@thesage/ui` | Button, Toggle, ToggleGroup, Link, Magnetic |
+| Forms | 18 | `@thesage/ui` | Input, Textarea, Select, Checkbox, Switch, Slider, Combobox, RadioGroup, Label, SearchBar |
+| Navigation | 7 | `@thesage/ui` | Tabs, Breadcrumb, Pagination, NavigationMenu, Menubar, Command |
+| Overlays | 8 | `@thesage/ui` | Dialog, AlertDialog, Popover, Tooltip, HoverCard, ContextMenu, DropdownMenu, Drawer |
+| Feedback | 6 | `@thesage/ui` | Alert, Toaster/toast, Progress, Skeleton, Spinner |
+| Data Display | 14 | `@thesage/ui` | Card, Badge, Avatar, Table, Carousel, AspectRatio, Collapsible, CodeBlock |
+| Layout | 8 | `@thesage/ui` | Accordion, Separator, ScrollArea, ResizablePanel, Sheet |
+| Features | 3 | `@thesage/ui` | CustomizerPanel, ThemeSwitcher |
+
+## High-Frequency Component Quick Reference
+
+### Button
+```tsx
+<Button variant="default|destructive|outline|secondary|ghost|link" size="sm|default|lg|icon">
+  Label
+</Button>
+```
+
+### Card
+```tsx
+<Card>
+  <CardHeader><CardTitle>Title</CardTitle><CardDescription>Desc</CardDescription></CardHeader>
+  <CardContent>Body</CardContent>
+  <CardFooter>Actions</CardFooter>
+</Card>
+```
+
+### Dialog
+```tsx
+<Dialog>
+  <DialogTrigger asChild><Button>Open</Button></DialogTrigger>
+  <DialogContent>
+    <DialogHeader><DialogTitle>Title</DialogTitle><DialogDescription>Desc</DialogDescription></DialogHeader>
+    Body
+    <DialogFooter><Button>Confirm</Button></DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+### Input
+```tsx
+<Input type="email" placeholder="Enter email" disabled={false} />
+```
+
+### Select
+```tsx
+<Select value={val} onValueChange={setVal}>
+  <SelectTrigger><SelectValue placeholder="Pick one" /></SelectTrigger>
+  <SelectContent>
+    <SelectItem value="a">Option A</SelectItem>
+    <SelectItem value="b">Option B</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+### Tabs
+```tsx
+<Tabs defaultValue="tab1">
+  <TabsList>
+    <TabsTrigger value="tab1">Tab 1</TabsTrigger>
+    <TabsTrigger value="tab2">Tab 2</TabsTrigger>
+  </TabsList>
+  <TabsContent value="tab1">Content 1</TabsContent>
+  <TabsContent value="tab2">Content 2</TabsContent>
+</Tabs>
+```
+
+### Badge
+```tsx
+<Badge variant="default|secondary|destructive|outline">Label</Badge>
+```
+
+### Alert
+```tsx
+<Alert variant="default|destructive">
+  <AlertTitle>Heading</AlertTitle>
+  <AlertDescription>Message</AlertDescription>
+</Alert>
+```
+
+### Form (react-hook-form integration)
+```tsx
+import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from '@thesage/ui/forms'
+
+<Form {...form}>
+  <FormField control={form.control} name="email" render={({ field }) => (
+    <FormItem>
+      <FormLabel>Email</FormLabel>
+      <FormControl><Input {...field} /></FormControl>
+      <FormMessage />
+    </FormItem>
+  )} />
+</Form>
+```
+
+## Bundle Size (minified + brotli)
+
+| Entrypoint | Size | Peer Deps Required |
+|------------|------|--------------------|
+| `@thesage/ui` (core) | 146 KB | None |
+| `@thesage/ui/dates` | 29 KB | date-fns, react-day-picker |
+| `@thesage/ui/tokens` | 11 KB | None |
+| `@thesage/ui/utils` | 10 KB | None |
+| `@thesage/ui/forms` | 9 KB | react-hook-form, zod |
+| `@thesage/ui/tables` | 8 KB | @tanstack/react-table |
+| `@thesage/ui/dnd` | 8 KB | @dnd-kit/* |
+| `@thesage/ui/providers` | 8 KB | None |
+| `@thesage/ui/hooks` | 6 KB | None |
+| `@thesage/ui/webgl` | 1 KB | framer-motion |
+
+`sideEffects: false` enables tree-shaking. Heavy features isolated behind subpath exports.
+
+## Third-Party Pairings
+
+For gaps SDE doesn't cover, these libraries integrate well:
+
+| Need | Library | Install |
+|------|---------|---------|
+| Rich Text Editor | Tiptap | `@tiptap/react @tiptap/starter-kit` |
+| File Upload | react-dropzone | `react-dropzone` |
+| Charts | Recharts | `recharts` |
+| Color Picker | react-colorful | `react-colorful` |
+| Markdown | react-markdown | `react-markdown remark-gfm` |
+| Virtualized Lists | @tanstack/react-virtual | `@tanstack/react-virtual` |
+| State Machines | XState | `xstate @xstate/react` |
+
+**Already integrated as optional peer deps:** @tanstack/react-table (`/tables`), react-hook-form + zod (`/forms`), date-fns + react-day-picker (`/dates`), @dnd-kit (`/dnd`), framer-motion, lucide-react.
+
+**Integration pattern:** Wrap in SDE Card/Dialog, use `cn()` for class merging, pull colors from CSS variables (`var(--color-primary)`) to stay theme-aware.
+
+## Eject (Full Customization)
+
+```bash
+npx @thesage/ui eject Button              # copies to src/components/ui/Button.tsx
+npx @thesage/ui eject Dialog --dir my/dir  # custom target
+npx @thesage/ui eject --list               # list all components
+```
+
+Imports are automatically rewritten:
+- `../../lib/utils` → `./utils` (auto-scaffolded)
+- `../../hooks/*` → `@thesage/ui/hooks`
+- `../category/*` → `@thesage/ui`
+
+Ejected components keep working with SDE themes and CSS variables. Also available via MCP tool `eject_component` and web UI at thesage.dev.
+
+## Full API Reference
+
+For complete props, variants, and examples for all 100 components:
+- Web: https://thesage.dev/llms-full.txt
+- MCP Server: `npx @thesage/mcp` (tools: list_components, search_components, get_component)
+
+## Resources
+
+- Docs: https://thesage.dev/docs
+- GitHub: https://github.com/shalomormsby/sage-design-engine
+- NPM: https://www.npmjs.com/package/@thesage/ui

package/README.md

@@ -0,0 +1,161 @@
+# Sage Design Engine (@thesage/ui)
+
+<div align="center">
+
+[![npm version](https://img.shields.io/npm/v/@thesage/ui?color=indigo&style=flat-square)](https://www.npmjs.com/package/@thesage/ui)
+[![License](https://img.shields.io/npm/l/@thesage/ui?color=blue&style=flat-square)](https://github.com/shalomormsby/sage-design-engine/blob/main/LICENSE)
+[![Downloads](https://img.shields.io/npm/dt/@thesage/ui?color=teal&style=flat-square)](https://www.npmjs.com/package/@thesage/ui)
+
+**Sage — Make it Lovable.**
+
+Components that feel alive. Themes with real personality. Motion your users control. Designed for humans. Fluent with AI.
+
+[Documentation](https://thesage.dev) | [Components](https://thesage.dev/components) | [GitHub](https://github.com/shalomormsby/sage-design-engine)
+
+</div>
+
+---
+
+**Sage Design Engine** is a component library and design system built on **Radix UI** primitives and **Tailwind CSS**. 100 accessible components across 11 functional categories, three distinct themes with runtime switching, and a user-controlled motion system — all wired through a 4-layer design token architecture.
+
+## Features
+
+- **Accessible by default** — Built on WAI-ARIA standards via Radix UI. Keyboard navigable, screen reader compatible, WCAG AA contrast.
+- **Three themes, real personality** — Studio (professional), Terra (organic), Volt (electric). Runtime switching via CSS variables, light and dark modes each.
+- **User-controlled motion** — A 0–10 intensity scale that respects `prefers-reduced-motion`. Intensity 0 works perfectly — no degraded experience.
+- **Modular imports** — Core stays lean. Heavy features (forms, dates, tables, drag-and-drop, WebGL) ship as optional subpath exports — install only what you use.
+- **Type safe** — Written in TypeScript with full type inference. React 19 ref-as-prop pattern throughout.
+- **Design token system** — Colors, typography, spacing, motion, and syntax tokens. Change one primary color, everything updates.
+
+## Installation
+
+```bash
+pnpm add @thesage/ui
+```
+
+Sage requires **Tailwind CSS** as a styling engine:
+
+```bash
+pnpm add -D tailwindcss@^3.4 postcss autoprefixer
+```
+
+### Optional subpath exports
+
+Install peer dependencies only for the features you need:
+
+```bash
+# Forms (react-hook-form + zod validation)
+pnpm add react-hook-form @hookform/resolvers zod
+
+# Date picker
+pnpm add react-day-picker date-fns
+
+# Data tables
+pnpm add @tanstack/react-table
+
+# Drag and drop
+pnpm add @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities
+```
+
+### Configure Tailwind
+
+```js
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: [
+    "./src/**/*.{ts,tsx}",
+    "./node_modules/@thesage/ui/dist/**/*.{js,ts,jsx,tsx}"
+  ],
+}
+```
+
+### Import styles
+
+```tsx
+import '@thesage/ui/globals.css';
+```
+
+## Usage
+
+```tsx
+import { Button, Card, ThemeProvider } from '@thesage/ui';
+
+export default function App() {
+  return (
+    <ThemeProvider theme="studio" defaultMode="system">
+      <Card className="max-w-md p-6">
+        <h3 className="mb-2 text-lg font-semibold">Welcome to Sage</h3>
+        <p className="mb-4 text-muted-foreground">
+          Build beautifully with components that feel premium out of the box.
+        </p>
+        <div className="flex gap-2">
+          <Button>Get Started</Button>
+          <Button variant="ghost">Documentation</Button>
+        </div>
+      </Card>
+    </ThemeProvider>
+  );
+}
+```
+
+### Subpath imports
+
+```tsx
+import { useMotionPreference, useTheme } from '@thesage/ui/hooks'
+import { ThemeProvider } from '@thesage/ui/providers'
+import { cn } from '@thesage/ui/utils'
+
+// Optional feature imports
+import { Form, FormField } from '@thesage/ui/forms'
+import { DatePicker } from '@thesage/ui/dates'
+import { DataTable } from '@thesage/ui/tables'
+import { SortableList } from '@thesage/ui/dnd'
+```
+
+## Component categories
+
+| Category | Examples |
+|----------|----------|
+| **Actions** | Button, Toggle, ToggleGroup |
+| **Forms** | Input, Select, Checkbox, Switch, Slider, SearchBar |
+| **Navigation** | Tabs, Menubar, Breadcrumb, Pagination, NavigationMenu |
+| **Overlays** | Dialog, Sheet, Popover, Tooltip, ContextMenu, HoverCard |
+| **Data Display** | Card, Avatar, Badge, Table, ScrollArea, Carousel |
+| **Feedback** | Alert, Progress, Skeleton, Toast (Sonner) |
+| **Layout** | Accordion, Separator, ResizablePanels, Collapsible |
+| **Features** | Customizer, ThemeSwitcher |
+
+## Eject — full customization
+
+Need to deeply customize a component? Eject it into your project for full ownership:
+
+```bash
+npx @thesage/ui eject Button
+npx @thesage/ui eject Dialog --dir components/sage
+npx @thesage/ui eject --list  # see all available components
+```
+
+This copies the component source into your project with imports automatically rewritten. The ejected component still works with Sage themes and CSS variables — you just own the code now.
+
+You can also eject from [thesage.dev](https://thesage.dev) — every component page has an **Eject** button that lets you copy or download the source directly.
+
+## Bundle size
+
+Core and optional entry points are independently tracked via [size-limit](https://github.com/ai/size-limit):
+
+| Entry point | Brotli size |
+|-------------|-------------|
+| Core | ~146 KB |
+| Hooks | ~40 KB |
+| Providers | ~60 KB |
+| Tokens | ~70 KB |
+| Utils | ~25 KB |
+| Forms | ~9.4 KB |
+| Dates | ~29 KB |
+| Tables | ~8.3 KB |
+| DnD | ~8.3 KB |
+| WebGL | ~1.1 KB |
+
+## License
+
+MIT &copy; [Shalom Ormsby](https://github.com/shalomormsby)

package/dist/cli.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync } from "fs";
+import { join, dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+var __filename_ = typeof __filename !== "undefined" ? __filename : fileURLToPath(import.meta.url);
+var PKG_ROOT = resolve(dirname(__filename_), "..");
+function transformImports(source) {
+  return source.replace(/from\s+['"]\.\.\/\.\.\/lib\/utils['"]/g, `from './utils'`).replace(/from\s+['"]\.\.\/\.\.\/lib\/[^'"]+['"]/g, `from '@opencosmos/ui/utils'`).replace(/from\s+['"]\.\.\/\.\.\/hooks\/[^'"]+['"]/g, `from '@opencosmos/ui/hooks'`).replace(/from\s+['"]\.\.\/[^.][^'"]*['"]/g, `from '@opencosmos/ui'`);
+}
+var CN_UTILS_SOURCE = `import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+`;
+function findComponent(name) {
+  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;
+}
+function listComponents() {
+  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 \u2014 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();
+  }
+}
+function ejectComponent(name, targetDir) {
+  const found = findComponent(name);
+  if (!found) {
+    console.error(`
+  Error: Component "${name}" not found.
+`);
+    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);
+  const resolvedDir = resolve(process.cwd(), targetDir);
+  mkdirSync(resolvedDir, { recursive: true });
+  const fileName = found.filePath.split("/").pop();
+  const destPath = join(resolvedDir, fileName);
+  writeFileSync(destPath, transformed, "utf-8");
+  const utilsPath = join(resolvedDir, "utils.ts");
+  if (!existsSync(utilsPath)) {
+    writeFileSync(utilsPath, CN_UTILS_SOURCE, "utf-8");
+  }
+  const deps = /* @__PURE__ */ new Set();
+  const importRegex = /from\s+['"](@[^/'"]+\/[^'"]+|[^.@/'"][^'"]*)['"]/g;
+  let match;
+  while ((match = importRegex.exec(source)) !== null) {
+    const pkg = match[1];
+    if (pkg.startsWith("@opencosmos/") || pkg === "react") continue;
+    const pkgName = pkg.startsWith("@") ? pkg.split("/").slice(0, 2).join("/") : pkg.split("/")[0];
+    deps.add(pkgName);
+  }
+  console.log(`
+  Ejected ${name} successfully!
+`);
+  console.log(`  ${destPath}`);
+  if (!existsSync(join(resolvedDir, "utils.ts"))) {
+  }
+  console.log(`  ${utilsPath} (cn utility)
+`);
+  if (deps.size > 0) {
+    console.log("  Required dependencies:");
+    console.log(`  pnpm add ${[...deps].sort().join(" ")}
+`);
+  }
+  console.log("  Update your imports:");
+  console.log(`  import { ${name} } from './${targetDir}/${name}'
+`);
+  console.log("  The ejected component still works with @opencosmos/ui themes and CSS variables.");
+  console.log("  You now own it \u2014 modify freely.\n");
+}
+function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+    console.log(`
+  @opencosmos/ui eject \u2014 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;
+  }
+  const command = args[0];
+  if (command !== "eject") {
+    console.error(`
+  Unknown command: ${command}
+  Run with --help for usage.
+`);
+    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();
+export {
+  transformImports
+};

package/dist/dates.d.mts

@@ -0,0 +1,20 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React from 'react';
+import { DayPicker } from 'react-day-picker';
+
+type CalendarProps = React.ComponentProps<typeof DayPicker>;
+declare function Calendar({ className, classNames, showOutsideDays, ...props }: CalendarProps): react_jsx_runtime.JSX.Element;
+declare namespace Calendar {
+    var displayName: string;
+}
+
+interface DatePickerProps {
+    date?: Date;
+    onDateChange?: (date: Date | undefined) => void;
+    placeholder?: string;
+    className?: string;
+    disabled?: boolean;
+}
+declare function DatePicker({ date, onDateChange, placeholder, className, disabled, }: DatePickerProps): react_jsx_runtime.JSX.Element;
+
+export { Calendar, type CalendarProps, DatePicker, type DatePickerProps };

package/dist/dates.d.ts

@@ -0,0 +1,20 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React from 'react';
+import { DayPicker } from 'react-day-picker';
+
+type CalendarProps = React.ComponentProps<typeof DayPicker>;
+declare function Calendar({ className, classNames, showOutsideDays, ...props }: CalendarProps): react_jsx_runtime.JSX.Element;
+declare namespace Calendar {
+    var displayName: string;
+}
+
+interface DatePickerProps {
+    date?: Date;
+    onDateChange?: (date: Date | undefined) => void;
+    placeholder?: string;
+    className?: string;
+    disabled?: boolean;
+}
+declare function DatePicker({ date, onDateChange, placeholder, className, disabled, }: DatePickerProps): react_jsx_runtime.JSX.Element;
+
+export { Calendar, type CalendarProps, DatePicker, type DatePickerProps };