@thesage/ui 0.1.0 → 1.0.1

package/.claude/CLAUDE.md

@@ -0,0 +1,224 @@
+# @thesage/ui — AI Context
+
+> 92 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.
+
+## Full API Reference
+
+For complete props, variants, and examples for all 92 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/ecosystem
+- NPM: https://www.npmjs.com/package/@thesage/ui

package/README.md

@@ -6,36 +6,58 @@
 [![License](https://img.shields.io/npm/l/@thesage/ui?color=blue&style=flat-square)](https://github.com/shalomormsby/ecosystem/blob/main/LICENSE)
 [![Downloads](https://img.shields.io/npm/dt/@thesage/ui?color=teal&style=flat-square)](https://www.npmjs.com/package/@thesage/ui)
 
-**The Design Engine for the Solopreneur.**
+**Sage — Make it Lovable.**
 
-[Documentation](https://thesage.dev) • [Components](https://thesage.dev/components) • [GitHub](https://github.com/shalomormsby/ecosystem)
+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/ecosystem)
 
 </div>
 
 ---
 
-**Sage Design Engine** is not just a component library—it's a systematic design engine built for speed, consistency, and beauty. Built on top of **Radix UI** for headless accessibility and **Tailwind CSS** for styling, it provides a comprehensive suite of 45+ polished components that work together seamlessly.
+**Sage Design Engine** is a component library and design system built on **Radix UI** primitives and **Tailwind CSS**. 48+ accessible components, three distinct themes with runtime switching, and a user-controlled motion system — all wired through a 4-layer design token architecture.
+
+## Features
 
-## ✨ 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.
 
-- **🎨 Systematic Design**: Powered by a robust design token system (colors, typography, spacing).
-- **♿ Fully Accessible**: Built on WAI-ARIA standards via Radix UI primitives.
-- **🌗 Mode Aware**: First-class support for light and dark modes with automatic color harmonization.
-- **🧩 Composable**: Components designed to fit together like LEGO blocks.
-- **🛠️ Type Safe**: Written in TypeScript with full type inference.
+## Installation
 
-## 🚀 Installation
+```bash
+pnpm add @thesage/ui
+```
 
-### 1. Install Dependencies
-Sage Design Engine is built on Tailwind CSS. You need to install the package and its peer dependencies.
+Sage requires **Tailwind CSS** as a styling engine:
 
 ```bash
-pnpm add @thesage/ui @thesage/tokens @thesage/hooks lucide-react clsx tailwind-merge
 pnpm add -D tailwindcss@^3.4 postcss autoprefixer
 ```
 
-### 2. Configure Tailwind
-Update your `tailwind.config.js` contents to use the preset and scan the component definitions.
+### 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} */
@@ -45,69 +67,82 @@ module.exports = {
     "./src/**/*.{ts,tsx}",
     "./node_modules/@thesage/ui/dist/**/*.{js,ts,jsx,tsx}"
   ],
-  theme: {
-    extend: {},
-  },
-  plugins: [],
 }
 ```
 
-### 3. Import Styles
-Import the global CSS file (which contains the theme variables) in your root entry file (e.g., `main.tsx` or `App.tsx`).
+### Import styles
 
 ```tsx
 import '@thesage/ui/globals.css';
 ```
 
-## 💻 Usage
-
-Sage Design Engine components are designed to be dropped into any React application.
+## Usage
 
 ```tsx
-import { Button, Card, Text, Heading } from '@thesage/ui';
+import { Button, Card, ThemeProvider } from '@thesage/ui';
 
-export default function WelcomeCard() {
+export default function App() {
   return (
-    <Card className="max-w-md p-6">
-      <Heading level={3} className="mb-2">Welcome to Sage</Heading>
-      <Text variant="muted" className="mb-4">
-        Build faster with components that look premium out of the box.
-      </Text>
-      <div className="flex gap-2">
-        <Button variant="primary">Get Started</Button>
-        <Button variant="ghost">Documentation</Button>
-      </div>
-    </Card>
+    <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>
   );
 }
 ```
 
-## 🖌️ Theming
-
-Sage Design Engine uses a 4-layer token system. Changing a single primary color automatically updates buttons, focus rings, and chart colors across your entire application.
+### Subpath imports
 
 ```tsx
-// Example: Customizing the theme
-import { ThemeProvider } from '@thesage/ui';
-
-export default function App({ children }) {
-  return (
-    <ThemeProvider theme="sage" defaultMode="system">
-      {children}
-    </ThemeProvider>
-  );
-}
+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
-
-- **Actions**: Button, Toggle, ToggleGroup
-- **Forms**: Input, Select, Checkbox, Switch, Slider, Form
-- **Navigation**: Tabs, Menubar, Breadcrumb, Pagination
-- **Overlays**: Dialog, Sheet, Popover, Tooltip, Toast
-- **Data Display**: Card, Avatar, Badge, Table, ScrollArea
-- **Feedback**: Alert, Progress, Skeleton, Sonner
-
-## 📄 License
-
-MIT © [Shalom Ormsby](https://github.com/shalomormsby)
+## 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 |
+
+## 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/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 };