@moontra/moonui 6.16.0 → 6.18.0

package/README.md

@@ -33,8 +33,8 @@ A premium React component library built for modern web applications. MoonUI prov
 
 - **TypeScript** - Full type safety and IntelliSense
 - **Tree Shaking** - Import only what you use
-- **Zero Config** - Works out of the box
-- **CLI Tool** - Easy installation with `moonui` CLI
+- **Tailwind Preset** - One line in your config wires up every design token
+- **CLI Tool** - Easy installation with the `@moontra/moonui-cli` CLI
 - **Storybook** - Interactive component documentation
 
 ### 📱 **Responsive & Performance**
@@ -52,70 +52,84 @@ A premium React component library built for modern web applications. MoonUI prov
 # Install the package
 npm install @moontra/moonui
 
-# Or use the CLI (recommended)
-npx @moontra/moonui-cli@latest init
+# Tailwind is a peer dependency; the components also use the animate plugin
+npm install -D tailwindcss tailwindcss-animate
 ```
 
-### CDN Usage (Browser/Artifacts)
-
-For quick prototyping or artifact environments:
-
-```html
-<!-- Dependencies -->
-<script
-    crossorigin
-    src="https://unpkg.com/react@18/umd/react.production.min.js"
-></script>
-<script
-    crossorigin
-    src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"
-></script>
-
-<!-- MoonUI -->
-<script src="https://cdn.jsdelivr.net/npm/@moontra/moonui@2.3.2/dist/index.global.js"></script>
-
-<script>
-    const { Button, Card } = window.MoonUI;
-
-    function App() {
-        return React.createElement(
-            Card,
-            null,
-            React.createElement(Button, { variant: "default" }, "Hello MoonUI!")
-        );
-    }
+Optionally scaffold the project files (`moonui.config.js`, `src/lib/utils.ts`,
+`src/components/ui/`) with the CLI. It does **not** edit your Tailwind config or
+global CSS — steps 1 and 2 below are still yours to add:
 
-    ReactDOM.render(React.createElement(App), document.getElementById("root"));
-</script>
+```bash
+npx @moontra/moonui-cli init
 ```
 
 ### Setup
 
-1. **Configure Tailwind CSS** (required)
+Steps 1 and 2 are both required. Skip either one and the components render
+unstyled — the utility classes they rely on are simply never generated.
+
+1. **Add the Tailwind preset** (required)
+
+The preset maps Tailwind's color, radius and animation scales onto MoonUI's CSS
+variables. Without it, classes such as `bg-primary`, `border-border` and
+`animate-accordion-down` are never produced. The `content` entry for
+`dist/**` matters just as much: Tailwind only generates classes it can *see*, and
+the component classes live inside the package bundle.
 
 ```javascript
-// tailwind.config.js
+// tailwind.config.js  (Tailwind v3 config format)
 module.exports = {
+    presets: [require("@moontra/moonui/tailwind-preset")],
     content: [
-        "./src/**/*.{js,ts,jsx,tsx}",
-        "./node_modules/@moontra/moonui/**/*.{js,mjs}",
+        "./src/**/*.{js,ts,jsx,tsx,mdx}",
+        "./node_modules/@moontra/moonui/dist/**/*.{js,mjs}",
     ],
-    theme: {
-        extend: {},
-    },
-    plugins: [],
+    // Radix-driven components use animate-in / fade-in-0 / slide-in-from-*
+    plugins: [require("tailwindcss-animate")],
 };
 ```
 
-2. **Import styles** (in your main CSS file)
+Everything the preset sets is still yours to override — add your own
+`theme.extend` block and it wins.
+
+2. **Import the design tokens** (required)
+
+The preset only *maps* the variables; this file *defines* them (light and dark).
 
 ```css
-@import "@moontra/moonui/styles";
+/* globals.css */
+@import "@moontra/moonui/src/styles/tokens.css";
+
 @tailwind base;
 @tailwind components;
 @tailwind utilities;
 ```
 
+> **Why the `src/styles/…` path and not `@moontra/moonui/tokens.css`?** Because the
+> two are resolved by different machinery. `postcss-import` — what handles CSS
+> `@import` in the usual Tailwind v3 + PostCSS setup — does not read a package's
+> `exports` map, so in CSS it needs the physical path (it ships in the tarball via
+> the package `files` field). Bundler/Node resolution is the mirror image: it *is*
+> `exports`-aware, so from JavaScript use the subpath instead:
+>
+> ```jsx
+> // app/layout.tsx
+> import "@moontra/moonui/tokens.css";
+> ```
+>
+> Either route loads the same file — pick one, not both.
+
+Recommended: also add the semantic layer. It defines extra tokens (elevation,
+duration, easing) and the handful of utilities that have no Tailwind equivalent —
+`shadow-xs`, `animate-fade-in`, `duration-fast`, `ease-bounce`. Every token the
+preset reads already lives in `tokens.css`, so components still render correctly
+without it; you only lose those extras (for example the `Skeleton` fade-in).
+
+```css
+@import "@moontra/moonui/src/styles/design-system.css";
+```
+
 3. **Start using components**
 
 ```jsx
@@ -127,7 +141,7 @@ function App() {
             <h1 className="text-2xl font-bold mb-4">Welcome to MoonUI</h1>
             <div className="space-y-4">
                 <Input placeholder="Enter your name" />
-                <Button variant="default" size="lg">
+                <Button variant="primary" size="lg">
                     Get Started
                 </Button>
             </div>
@@ -138,104 +152,160 @@ function App() {
 
 ## 📚 Components
 
+A selection of what ships in the package — every name below is a real export of
+`@moontra/moonui`. The full, always-current list lives at
+**[moonui.dev/docs/components](https://moonui.dev/docs/components)**.
+
 ### Layout & Structure
 
 - **Card** - Flexible content containers
 - **Separator** - Visual content dividers
 - **AspectRatio** - Responsive aspect ratio containers
 - **ScrollArea** - Custom scrollable areas
+- **Collapsible** - Expandable content
 
 ### Navigation
 
 - **Breadcrumb** - Hierarchical navigation
 - **Pagination** - Page navigation controls
 - **Tabs** - Tabbed interfaces
-- **Navigation Menu** - Complex navigation structures
+- **DropdownMenu** - Context menus
+- **Command** - Command palette interface
 
 ### Form Controls
 
-- **Button** - Interactive buttons with variants
-- **Input** - Text input fields
-- **Textarea** - Multi-line text input
+- **Button**, **ButtonGroup** - Interactive buttons with variants
+- **Input**, **Textarea** - Text input fields
 - **Select** - Dropdown selections
-- **Checkbox** - Boolean selections
+- **Checkbox**, **CheckboxGroup** - Boolean selections
 - **RadioGroup** - Single choice selections
-- **Switch** - Toggle controls
+- **Switch**, **Toggle**, **ToggleGroup** - Toggle controls
 - **Slider** - Range inputs
 - **Label** - Form field labels
+- **InputOTP** - One-time-code input
+- **PhoneInput**, **TagsInput** - Specialized inputs
+- **CardNumberInput**, **CardExpiryInput**, **CardCVCInput**, **CardZipInput** - Payment fields
+- **Rating** - Star ratings
+- **FileUpload** - File upload interface
 
 ### Feedback & Overlays
 
-- **Dialog** - Modal dialogs
-- **AlertDialog** - Confirmation dialogs
-- **Toast** - Notification messages
+- **Dialog**, **DialogForm** - Modal dialogs
+- **Toast** / **Toaster** - Notification messages
 - **Alert** - Inline notifications
-- **Tooltip** - Contextual information
+- **Tooltip**, **SimpleTooltip** - Contextual information
 - **Popover** - Floating content panels
-- **HoverCard** - Hover-triggered content
+- **Spinner** - Inline loading indicator
 
 ### Data Display
 
-- **Avatar** - User profile images
+- **Avatar**, **AvatarGroup** - User profile images
 - **Badge** - Status indicators
+- **Kbd** - Keyboard shortcut hints
 - **Progress** - Loading indicators
-- **Skeleton** - Loading placeholders
+- **Skeleton** (+ **SkeletonText**, **SkeletonCard**, **SkeletonAvatar**) - Loading placeholders
 - **Table** - Structured data display
-- **DataTable** - Advanced data tables
+- **MoonUIDataTableBasic** - Basic TanStack-powered data table
 - **Accordion** - Collapsible content
+- **Carousel** - Slideshows
 
-### Media & Graphics
+### Dates & Color
 
-- **Calendar** - Date selection
-- **DatePicker** - Date input controls
-- **ColorPicker** - Color selection
-- **FileUpload** - File upload interface
+- **MoonUICalendar** - Date selection
+- **DatePicker**, **DateRangePicker**, **DateTimePicker**, **MonthPicker** - Date input controls
+- **ColorPicker**, **SimpleColorPicker**, **GradientPicker** - Color selection
 
-### Advanced
+### Interaction & Motion
 
-- **Command** - Command palette interface
-- **Collapsible** - Expandable content
-- **DropdownMenu** - Context menus
-- **Menubar** - Application menu bars
+- **DraggableList** - Sortable lists
+- **SwipeableCard** - Touch-friendly cards
+- **GestureDrawer** - Gesture-driven drawer
+- **ScrollReveal** (+ **ScrollRevealContainer**, **ScrollRevealItem**) - Scroll-driven reveals
+
+### Editors
+
+- **RichTextEditor** - WYSIWYG editor
+- **SimpleEditor** - Lightweight text editor
+
+> Components are also exported under a `MoonUI`-prefixed alias (for example
+> `MoonUIButton`, `MoonUICard`) if you need to avoid name collisions. Two of them
+> — `Calendar` and `DataTableBasic` — are available **only** under their prefixed
+> names: `MoonUICalendar` and `MoonUIDataTableBasic`.
 
 ## 🎨 Theming
 
 ### CSS Variables
 
-MoonUI uses CSS variables for easy theming:
+MoonUI uses CSS variables for theming. These are the values `tokens.css` ships
+with — components read them as `hsl(var(--primary))` and friends:
 
 ```css
 :root {
     --background: 0 0% 100%;
     --foreground: 222.2 84% 4.9%;
-    --primary: 222.2 47.4% 11.2%;
+    --primary: 217.2 91.2% 51%;
     --primary-foreground: 210 40% 98%;
+    --border: 214.3 31.8% 91.4%;
+    --ring: 217.2 91.2% 51%;
+    --radius: 0.5rem;
     /* ... more variables */
 }
 
 .dark {
-    --background: 222.2 84% 4.9%;
-    --foreground: 210 40% 98%;
+    --background: 224 71% 4%;
+    --foreground: 213 31% 91%;
+    --primary: 210 40% 98%;
+    --primary-foreground: 222.2 47.4% 1.2%;
     /* ... dark theme variables */
 }
 ```
 
+### Dark Mode
+
+Dark mode is **class-based**: `tokens.css` defines a `.dark` block and the preset
+sets `darkMode: "class"`. Put the `dark` class on your root element — yourself, or
+with a library such as `next-themes` — and every component follows:
+
+```jsx
+<html className="dark">
+    <body>{children}</body>
+</html>
+```
+
 ### Theme Provider
 
+`ThemeProvider` is **optional** and does something different from dark mode: it
+swaps whole colour *presets* at runtime. The default preset is the static
+`tokens.css`, so mounting the provider changes nothing until you pick another one.
+
 ```jsx
 import { ThemeProvider } from "@moontra/moonui/theme";
 
 function App() {
     return (
-        <ThemeProvider attribute="class" defaultTheme="system">
+        <ThemeProvider defaultPreset="ocean" persist>
             <YourApp />
         </ThemeProvider>
     );
 }
 ```
 
+| Prop            | Type                              | Default     | Description                              |
+| --------------- | --------------------------------- | ----------- | ---------------------------------------- |
+| `defaultPreset` | `ThemePresetName`                 | `"default"` | Preset used on first render              |
+| `preset`        | `ThemePresetName`                 | —           | Controlled preset (overrides internal state) |
+| `overrides`     | `Partial<ThemeTokens>`            | —           | Per-token overrides                      |
+| `persist`       | `boolean`                         | `false`     | Persist the selection to `localStorage`  |
+| `storageKey`    | `string`                          | —           | Key used when `persist` is on            |
+
+Available presets: `default`, `brand`, `corporate`, `creative`, `nature`,
+`minimal`, `ocean`. Read the active one with `useTheme()` (it must be called
+inside a `ThemeProvider`).
+
 ### Custom Colors
 
+Redeclare any token in your own `:root` block **after** the import and it wins:
+
 ```css
 :root {
     --primary: 142 76% 36%; /* Custom green */
@@ -249,16 +319,22 @@ The MoonUI CLI helps you add components easily:
 
 ```bash
 # Initialize MoonUI in your project
-npx @moontra/moonui-cli@latest init
+npx @moontra/moonui-cli init
 
 # Add specific components
-npx @moontra/moonui-cli@latest add button
-npx @moontra/moonui-cli@latest add card input
+npx @moontra/moonui-cli add button
+npx @moontra/moonui-cli add card input
 
 # Add multiple components
-npx @moontra/moonui-cli@latest add button card input dialog
+npx @moontra/moonui-cli add button card input dialog
+
+# Browse what is available
+npx @moontra/moonui-cli list
 ```
 
+Other commands: `theme`, `templates`, `license`, `login`, `logout`, `whoami`.
+Run `npx @moontra/moonui-cli --help` for the full list.
+
 ## 📖 Documentation
 
 - **🌐 Website**: [moonui.dev](https://moonui.dev)
@@ -271,17 +347,19 @@ npx @moontra/moonui-cli@latest add button card input dialog
 MoonUI includes MCP (Model Context Protocol) support for AI assistants:
 
 ```bash
-# Install MCP Server
 npm install -g @moontra/moonui-mcp-server
+```
+
+Then register it with your MCP client (Claude Desktop shown here):
 
-# Configure in Claude Desktop
+```json
 {
-  "mcpServers": {
-    "moonui": {
-      "command": "npx",
-      "args": ["@moontra/moonui-mcp-server"]
+    "mcpServers": {
+        "moonui": {
+            "command": "npx",
+            "args": ["@moontra/moonui-mcp-server"]
+        }
     }
-  }
 }
 ```
 
@@ -291,22 +369,21 @@ AI assistants can then help you:
 - 🔧 Generate component code automatically
 - 🐛 Fix import issues
 - 🎨 Configure theming and customization
-- 📱 Detect environment (CDN vs NPM) automatically
 
 ## 💼 Pro Version
 
 Upgrade to MoonUI Pro for advanced components:
 
-- **DataTable** - Advanced data grids with sorting, filtering, pagination
-- **Charts** - Beautiful data visualizations
+- **DataTable** - Advanced data grids with sorting, filtering, export, bulk actions
+- **AdvancedChart**, **ChartWidget** - Data visualization built on Recharts
 - **RichTextEditor** - WYSIWYG editor
-- **FormWizard** - Multi-step forms
-- **Calendar** - Advanced date/time pickers
-- **DragDropList** - Sortable lists
-- **TreeView** - Hierarchical data display
+- **FormWizard** - Multi-step forms with validation
+- **AdvancedCalendar** - Event calendars and advanced date/time pickers
+- **DraggableList** - Sortable lists
+- **FileTree** - Hierarchical data display
 - **Timeline** - Event timelines
-- **VideoPlayer** - Custom video controls
-- **CodeEditor** - Syntax-highlighted code input
+- **Kanban** - Drag-and-drop board layouts
+- **BentoGrid**, **Spotlight**, **VirtualList** - Layout, search and virtualization
 
 [Learn more about Pro →](https://moonui.dev/pricing)
 
@@ -314,16 +391,18 @@ Upgrade to MoonUI Pro for advanced components:
 
 ### Requirements
 
-- Node.js 18+
-- React 18+
-- TypeScript 5+
-- Tailwind CSS 3+
+Declared peer dependencies:
+
+- React 18 or 19 (`react`, `react-dom`)
+- Tailwind CSS 3 or 4
+
+Recommended for development: Node.js 18+ and TypeScript 5+.
 
 ### Local Development
 
 ```bash
-git clone https://github.com/moontra/moonui
-cd moonui/packages/moonui
+git clone https://github.com/oguzhanayyldz/moonuikit
+cd moonuikit/packages/moonui
 npm install
 npm run dev
 ```
@@ -339,7 +418,7 @@ npm run test       # Run tests
 
 ## 🤝 Contributing
 
-We welcome contributions! See our [Contributing Guide](CONTRIBUTING.md) for details.
+We welcome contributions! See our [Contributing Guide](https://github.com/oguzhanayyldz/moonuikit/blob/main/CONTRIBUTING.md) for details.
 
 ### Development Workflow
 
@@ -359,11 +438,13 @@ We welcome contributions! See our [Contributing Guide](CONTRIBUTING.md) for deta
 
 ## 📦 Package Details
 
-- **Bundle Size**: ~460KB (ESM), ~485KB (CJS)
-- **CDN Bundle**: ~742KB (includes all dependencies)
-- **Type Definitions**: Full TypeScript support
-- **Tree Shaking**: Import individual components
-- **Side Effects**: false (webpack optimization)
+- **Bundle Size** (v6.17.0, unminified): ~311 KB `dist/index.mjs`, ~335 KB `dist/index.js`
+- **Formats**: ESM + CJS, both marked `"use client"` for the Next.js App Router
+- **Type Definitions**: Full TypeScript support (`dist/index.d.ts`)
+- **Tree Shaking**: Enabled — `sideEffects` is limited to `**/*.css`, so unused
+  components are dropped by the bundler
+- **Subpath exports**: `.`, `./theme`, `./hooks`, `./tokens.css`,
+  `./design-system.css`, `./tailwind-preset`
 
 ## 🔗 Ecosystem
 
@@ -373,7 +454,7 @@ We welcome contributions! See our [Contributing Guide](CONTRIBUTING.md) for deta
 
 ## 📄 License
 
-Licensed under the [MIT License](LICENSE).
+Licensed under the [MIT License](https://github.com/oguzhanayyldz/moonuikit/blob/main/LICENSE).
 
 ## 🙏 Acknowledgments
 
@@ -389,7 +470,7 @@ Built with:
 
 <div align="center">
 
-**[Website](https://moonui.dev) • [Documentation](https://moonui.dev/docs) • [Components](https://moonui.dev/docs/components) • [GitHub](https://github.com/moontra/moonui)**
+**[Website](https://moonui.dev) • [Documentation](https://moonui.dev/docs) • [Components](https://moonui.dev/docs/components) • [GitHub](https://github.com/oguzhanayyldz/moonuikit)**
 
 Made with ❤️ by the MoonUI team