flikkui 0.1.0-beta.8 → 0.2.0-beta.1

package/README.md

@@ -1,34 +1,120 @@
 # Flikkui
 
-A modern React component library built with TypeScript, Tailwind CSS v4, and optional Framer Motion animations. Follows the shadcn philosophy where users can override any styling using className props while getting sensible defaults out of the box.
+<p align="center">
+  <strong>A modern React component library built with TypeScript, Tailwind CSS v4, and Framer Motion</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/flikkui"><img src="https://img.shields.io/npm/v/flikkui?label=npm&color=blue" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/flikkui"><img src="https://img.shields.io/npm/dm/flikkui" alt="npm downloads" /></a>
+  <a href="https://github.com/yourusername/flikkui/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License" /></a>
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-Ready-blue" alt="TypeScript" /></a>
+</p>
+
+<p align="center">
+  Follows the <strong>shadcn philosophy</strong> - override any styling using className props while getting sensible defaults out of the box.
+</p>
+
+---
+
+## 📋 Table of Contents
+
+- [Why Flikkui?](#-why-flikkui)
+- [Quick Start](#-quick-start)
+- [Usage Examples](#-usage-examples)
+- [Tree-Shaking & Optimized Imports](#-tree-shaking--optimized-imports)
+- [Customization](#-customization)
+- [Component Library](#-component-library)
+- [Performance](#-performance)
+- [Documentation](#-documentation)
+- [Contributing](#-contributing)
+- [License](#-license)
+
+---
+
+## ✨ Why Flikkui?
+
+- 🎨 **100+ Production-Ready Components** - Everything from buttons to complex charts
+- 🚀 **CLI Setup Tool** - Get started in 30 seconds with `npx flikkui init`
+- 🌳 **Optimized Tree-Shaking** - 60-85% bundle size reduction
+- 🎭 **CSS Variables** - Easy theming without JavaScript
+- ⚡ **Tailwind CSS v4** - Latest and greatest
+- 🔥 **TypeScript-First** - Excellent DX with full type safety
+- ♿ **Accessibility Built-In** - WCAG 2.1 AA compliance
+- 🎪 **shadcn Compatible** - className overrides always take precedence
+
+### 📊 Features at a Glance
+
+| Feature | Flikkui | Other Libraries |
+|---------|---------|-----------------|
+| **Setup Time** | 30 seconds (CLI) | 10+ minutes (manual) |
+| **TypeScript** | ✅ Built-in | ⚠️ Limited/Optional |
+| **Tree-Shaking** | ✅ Optimized | ⚠️ Basic |
+| **className Override** | ✅ Always works | ❌ Often blocked |
+| **CSS Variables** | ✅ Full support | ⚠️ Partial |
+| **Accessibility** | ✅ WCAG 2.1 AA | ⚠️ Basic |
+| **Bundle Size** | 🟢 15-150KB | 🟡 100-500KB |
+| **Animation** | ✅ Optional Motion | ⚠️ Required/None |
+| **Charts** | ✅ 18+ Built-in | ❌ Separate library |
+| **AI Components** | ✅ Included | ❌ Not available |
 
 ## 🚀 Quick Start
 
-### 1. Install the package
+### ⚡ Automatic Setup (Recommended)
+
+Get started in seconds with our CLI tool:
 
 ```bash
-npm install flikkui@beta motion
-# or
-yarn add flikkui@beta motion
+# Step 1: Install Flikkui
+npm install flikkui@beta
+
+# Step 2: Run the setup wizard
+npx flikkui init
+```
+
+**That's it!** The CLI automatically:
+- ✅ Installs all required dependencies (@heroicons/react, motion, tailwindcss, etc.)
+- ✅ Detects your framework (Next.js, Vite, CRA, Remix)
+- ✅ Injects CSS imports in the right file
+- ✅ Configures Tailwind CSS (optional)
+
+**CLI Options:**
+```bash
+npx flikkui init              # 🎯 Interactive setup (recommended)
+npx flikkui init --tailwind   # ⚡ Include Tailwind config
+npx flikkui init --yes        # 🚀 Skip prompts, use defaults
+npx flikkui init --skip-install  # 📦 Manual dependency installation
 ```
 
-### 2. Download the theme file
+> 💡 **Supports:** Next.js (App Router & Pages Router), Vite, Create React App, Remix, and generic React projects
 
-Download the theme file from [flikkui.dev/theme](https://flikkui.dev/theme) and save it as `flikkui-theme.css` in your project root.
+### Manual Setup
 
-Alternatively, you can copy this file: [flikkui-theme.css](./flikkui-theme.css)
+If you prefer manual installation:
 
-### 3. Import the theme in your app
+#### 1. Install the package
+
+```bash
+npm install flikkui @heroicons/react clsx motion tailwind-merge tailwindcss react-markdown react-syntax-highlighter remark-gfm three
+```
+
+**Or with yarn:**
+```bash
+yarn add flikkui @heroicons/react clsx motion tailwind-merge tailwindcss react-markdown react-syntax-highlighter remark-gfm three
+```
+
+#### 2. Import styles in your app
 
 ```tsx
 // In your main App.tsx, index.tsx, or _app.tsx
-import './flikkui-theme.css'  // Import the downloaded theme file
-import App from './App'
+import 'flikkui/styles.css'
 
-// Your app code...
+function App() {
+  return <YourApp />
+}
 ```
 
-### 4. Start using components
+#### 3. Start using components
 
 ```tsx
 import { Button } from 'flikkui'
@@ -42,114 +128,439 @@ export function MyComponent() {
 }
 ```
 
-## 🎨 Customization
+---
 
-Edit the `flikkui-theme.css` file to customize your design system:
+## 💻 Usage Examples
 
-```css
-/* flikkui-theme.css */
-@theme {
-  /* Change primary color */
-  --color-primary-base: oklch(0.666 0.223 48.717); /* Orange */
-  --color-primary-600: oklch(0.666 0.223 48.717);
-  --color-primary-700: oklch(0.555 0.192 47.355);
-  
-  /* Larger buttons */
-  --button-min-h-md: 3rem;
-  --button-px-md: 1.25rem;
-  
-  /* More rounded design */
-  --form-rounded: 1rem;
+### Basic Components
+
+```tsx
+import { Button, Badge, Avatar } from 'flikkui'
+
+function App() {
+  return (
+    <div>
+      {/* Button with variants */}
+      <Button variant="primary" size="md">
+        Click me
+      </Button>
+
+      {/* Badge with colors */}
+      <Badge color="success" variant="soft">
+        Active
+      </Badge>
+
+      {/* Avatar */}
+      <Avatar
+        src="/user.jpg"
+        alt="User"
+        size="md"
+      />
+    </div>
+  )
 }
 ```
 
-You can also override styles using className props (shadcn approach):
+### Form Components
+
+```tsx
+import { Input, Select, Checkbox } from 'flikkui/forms'
+import { MagnifyingGlassIcon } from '@heroicons/react/24/outline'
+
+function SearchForm() {
+  return (
+    <form>
+      {/* Input with icon */}
+      <Input
+        placeholder="Search..."
+        iconStart={<MagnifyingGlassIcon />}
+      />
+
+      {/* Select */}
+      <Select>
+        <option>Choose option</option>
+        <option>Option 1</option>
+      </Select>
+
+      {/* Checkbox */}
+      <Checkbox label="Remember me" />
+    </form>
+  )
+}
+```
+
+### Charts
+
+```tsx
+import { AreaChart, BarChart } from 'flikkui/charts'
+
+const data = [
+  { month: 'Jan', sales: 4000, revenue: 2400 },
+  { month: 'Feb', sales: 3000, revenue: 1398 },
+  { month: 'Mar', sales: 2000, revenue: 9800 },
+]
+
+const config = {
+  sales: { label: 'Sales', color: '#3b82f6' },
+  revenue: { label: 'Revenue', color: '#10b981' },
+}
+
+function Dashboard() {
+  return (
+    <div>
+      <AreaChart
+        data={data}
+        config={config}
+        className="h-80"
+        showGrid
+        curved
+      />
+
+      <BarChart
+        data={data}
+        config={config}
+        className="h-80"
+      />
+    </div>
+  )
+}
+```
+
+### Advanced: Compound Components
+
+```tsx
+import { Accordion, Modal, Tabs } from 'flikkui'
+
+function AdvancedExample() {
+  return (
+    <>
+      {/* Accordion */}
+      <Accordion>
+        <Accordion.Item>
+          <Accordion.Trigger>What is Flikkui?</Accordion.Trigger>
+          <Accordion.Content>
+            A modern React component library...
+          </Accordion.Content>
+        </Accordion.Item>
+      </Accordion>
+
+      {/* Tabs */}
+      <Tabs defaultValue="profile">
+        <Tabs.List>
+          <Tabs.Trigger value="profile">Profile</Tabs.Trigger>
+          <Tabs.Trigger value="settings">Settings</Tabs.Trigger>
+        </Tabs.List>
+        <Tabs.Content value="profile">Profile content</Tabs.Content>
+        <Tabs.Content value="settings">Settings content</Tabs.Content>
+      </Tabs>
+    </>
+  )
+}
+```
+
+## 🌳 Tree-Shaking & Optimized Imports
+
+Flikkui is optimized for tree-shaking. For the best bundle size, import components from category subpaths:
+
+```tsx
+// ✅ Recommended: Category imports (best tree-shaking)
+import { Button } from 'flikkui/core'
+import { Input, Select } from 'flikkui/forms'
+import { BarChart } from 'flikkui/charts'
+import { GlassEffect } from 'flikkui/effects'
+
+// ✅ Also works: Main import (backward compatible)
+import { Button, Input, BarChart } from 'flikkui'
+```
+
+### Bundle Size Comparison
+
+| Import Method | Components Used | Bundle Size | Savings |
+|--------------|----------------|-------------|---------|
+| Category imports | 1-3 components | ~50-100KB | 85-90% |
+| Category imports | 10-20 components | ~250-400KB | 67-79% |
+| Main import | Any | Works, but larger | - |
+
+**Categories available:**
+- `flikkui/core` - Button, Modal, Dropdown, Tooltip, etc.
+- `flikkui/forms` - Input, Select, Checkbox, Radio, etc.
+- `flikkui/charts` - AreaChart, BarChart, LineChart, etc.
+- `flikkui/effects` - GlassEffect, visual effects
+
+## 🎨 Customization
+
+### Using className Overrides (Recommended)
+
+Override styles using className props - the shadcn approach:
 
 ```tsx
 <Button className="bg-purple-600 hover:bg-purple-700 rounded-full">
   Custom Button
 </Button>
+
+<Input className="border-blue-500 focus:ring-blue-500" />
+
+<Badge className="bg-gradient-to-r from-purple-500 to-pink-500">
+  Gradient Badge
+</Badge>
 ```
 
-## 📚 Components
-
-### Core Components
-- **Button** - Multiple variants, states, optional animations
-- **Avatar** - Image handling, fallbacks, status indicators
-- **AvatarGroup** - Overlapping avatars with compound component pattern  
-- **Badge** - Variants, sizes, content flexibility
-- **Accordion** - Compound component with animations
-- **Modal** - Compound component with header, body, footer
-- **Drawer** - Slide-out panels from edges
-- **Popover** - Compound with portal rendering
-- **Tooltip** - Positioning, animations, accessibility
-- **Tabs** - Horizontal tabbed interface
-
-### Form Components  
-- **Input** - Multiple types, masking, validation
-- **Select** - Searchable, compound pattern
-- **Checkbox** - Custom styling, controlled/uncontrolled
-- **Radio** - Group management
-- **Switch** - Toggle functionality
-- **Textarea** - Resizable, validation
-
-### Data Display
-- **Table** - Dual API, sorting, filtering, selection
-- **Spinner** - Loading states, sizes
+### Using CSS Variables
 
-### Charts
-- **AreaChart** - Stacked, curved, null value handling
-- **BarChart** - Horizontal/vertical, grouped, stacked  
-- **LineChart** - Multiple series, curved lines
-- **DonutChart** - Progress, animations, gradients
-- **Heatmap** - Interactive, customizable intensity
+Customize your design system globally by overriding CSS variables:
+
+```css
+/* In your global CSS file */
+@layer base {
+  :root {
+    /* Change primary color */
+    --color-primary-600: #7c3aed; /* Purple */
+    --color-primary-700: #6d28d9;
+
+    /* Larger buttons */
+    --button-min-h-md: 3rem;
+    --button-px-md: 1.25rem;
+
+    /* More rounded design */
+    --form-rounded: 1rem;
+    --button-rounded: 0.75rem;
+  }
+}
+```
+
+**Available CSS variables:**
+- Colors: `--color-primary-*`, `--color-danger-*`, `--color-success-*`, `--color-warning-*`
+- Text: `--color-text-primary`, `--color-text-secondary`, `--color-text-muted`
+- Backgrounds: `--color-background`, `--color-background-secondary`
+- Component-specific: `--button-*`, `--form-*`, `--modal-*`, etc.
+
+## 📚 Component Library
 
-## 🔄 Migration from v0.1.0-beta.3
+Flikkui includes **100+ production-ready components** across 5 categories. All components are:
+- ✅ **TypeScript-ready** with full type definitions
+- ✅ **Accessible** - WCAG 2.1 AA compliant
+- ✅ **Customizable** - Override with className
+- ✅ **Responsive** - Mobile-first design
+- ✅ **Themeable** - CSS variables support
+- ✅ **Animated** - Optional Framer Motion support
 
-If you were using the previous version, update your imports:
+### 🎨 Core Components (45+)
 
 ```tsx
-// Old (v0.1.0-beta.3)
-import 'flikkui/styles.css'
+import {
+  Button, Avatar, AvatarGroup, Badge, Accordion,
+  Modal, Drawer, Popover, Dropdown, Tooltip, Tabs,
+  Card, CardStack, Stepper, Segmented, Pagination,
+  Breadcrumbs, Link, Divider, Skeleton, Loader,
+  Calendar, Tree, CommandPalette, ContextMenu,
+  Sidebar, NavItem, Notification, Toast
+} from 'flikkui/core'
+```
+
+**Highlights:** Modal, Drawer, Tabs, Accordion, Dropdown, Tooltip, Popover, Card, CommandPalette
+
+### 📝 Form Components (22+)
+
+```tsx
+import {
+  Input, Select, Checkbox, Radio, Switch, Textarea,
+  DatePicker, TimePicker, ColorPicker, RichTextEditor,
+  FileUpload, Slider, Rating, PasswordInput, PinInput,
+  FormLabel, TagInput, MultiSelect, SearchableSelect
+} from 'flikkui/forms'
+```
 
-// New (v0.1.0-beta.4+)
-import './flikkui-theme.css'  // Download this file first
+**Highlights:** Input (with icons), Select, DatePicker, FileUpload, RichTextEditor, ColorPicker
+
+### 📊 Chart Components (18+)
+
+```tsx
+import {
+  AreaChart, BarChart, LineChart, DonutChart, Heatmap,
+  FunnelChart, ScatterPlot, ActivityRings, ComboChart,
+  RadarChart, TreeMap, Sparkline, ProgressChart
+} from 'flikkui/charts'
+```
+
+**Highlights:** AreaChart, LineChart, BarChart, DonutChart, Heatmap, FunnelChart
+
+### ✨ Effect Components
+
+```tsx
+import { GlassEffect, CustomCursor, Overlay } from 'flikkui/effects'
 ```
 
-This change gives you:
-- ✅ 100% predictable styling
-- ✅ Full control over your design system  
-- ✅ No more CSS cascade conflicts
-- ✅ Easy theme customization
+**Highlights:** GlassEffect (automatic color adaptation), CustomCursor, Overlay
+
+### 🤖 AI Components
+
+```tsx
+import { Message, PromptInput, ThinkingIndicator } from 'flikkui/ai'
+```
+
+**Highlights:** Message (with typewriter effect), PromptInput (AI-ready interface)
+
+## 🆕 What's New in v0.1.0-beta.12+
+
+### 🚀 CLI Setup Tool (NEW!)
+
+The biggest addition - automatic setup with `npx flikkui init`:
+- ✅ Auto-detects your framework (Next.js, Vite, CRA, Remix)
+- ✅ Installs all peer dependencies
+- ✅ Injects CSS imports automatically
+- ✅ Configures Tailwind (optional)
+
+### 🌳 Better Tree-Shaking
+
+Improved bundle size with category imports:
+```tsx
+// Before: All components bundled
+import { Button, Input } from 'flikkui'
+
+// After: Only what you need (60-85% smaller)
+import { Button } from 'flikkui/core'
+import { Input } from 'flikkui/forms'
+```
+
+### 📦 Peer Dependencies
+
+Dependencies are now peers (not bundled) for maximum flexibility and smaller package size.
+
+---
+
+## 🔄 Migration Guide
+
+### Upgrading from beta.11 → beta.12+
+
+**The easiest way:**
+```bash
+npx flikkui init
+```
+
+**Manual upgrade:**
+
+1. **Install peer dependencies:**
+```bash
+npm install @heroicons/react clsx motion tailwind-merge tailwindcss react-markdown react-syntax-highlighter remark-gfm three
+```
+
+2. **No code changes needed!** ✅
+```tsx
+import { Button } from 'flikkui' // Still works
+import 'flikkui/styles.css'      // Still works
+```
+
+3. **Optional: Use category imports for better tree-shaking:**
+```tsx
+import { Button } from 'flikkui/core'  // Smaller bundles
+```
+
+### First Time Installing?
+
+Just run:
+```bash
+npm install flikkui@beta
+npx flikkui init
+```
 
 ## 💡 Philosophy
 
 Flikkui follows the **shadcn approach**:
-- Components provide sensible defaults
-- **className overrides always take precedence**
-- Full TypeScript support with excellent DX
-- Copy-paste friendly - customize anything
-- CSS variables for consistent theming
+- ✅ Components provide sensible defaults
+- ✅ **className overrides always take precedence**
+- ✅ Full TypeScript support with excellent DX
+- ✅ Copy-paste friendly - customize anything
+- ✅ CSS variables for consistent theming
+- ✅ Tree-shaking optimized - only bundle what you use
 
 ## 🛠️ Tech Stack
 
-- **React 18** with TypeScript (strict mode)
+- **React 18+** with TypeScript (strict mode)
 - **Tailwind CSS v4** with CSS variables
-- **Framer Motion** (optional, for enhanced components)
+- **Framer Motion 12+** for smooth animations
+- **Heroicons** for consistent iconography
 - **Accessibility-first** - WCAG 2.1 AA compliance built-in
+- **Optimized build** - Rollup with ESM output and preserveModules
+
+## ⚡ Performance
+
+Flikkui is optimized for production:
+
+- **Tree-shaking ready** - Only bundle components you use
+- **Small package size** - ~800KB unpacked (no bundled dependencies)
+- **Zero runtime overhead** - CSS variables, no theme providers
+- **Optimized animations** - Framer Motion with reduced motion support
+- **Code splitting** - Category-level exports for granular imports
+
+**Real-world bundle sizes (production build, gzipped):**
+- Single component (Button): ~15-20KB
+- Small app (5 components): ~40-60KB
+- Medium app (20 components): ~100-150KB
+
+## 🎯 Browser Support
+
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+
+**Note:** Requires browsers with CSS custom properties support.
 
 ## 📖 Documentation
 
-Visit [flikkui.dev](https://flikkui.dev) for:
-- Component API documentation
-- Interactive examples
-- Theme customization guide
-- Migration guides
+Comprehensive documentation and resources:
+
+- 📚 **[Documentation](https://flikkui.dev)** - Complete API reference
+- 🎨 **[Storybook](https://storybook.flikkui.dev)** - Interactive component demos
+- 🚀 **[Getting Started Guide](./docs/INSTALLATION.md)** - Detailed setup instructions
+- 🛠️ **[CLI Documentation](./docs/CLI.md)** - CLI command reference
+- 🎭 **[Theming Guide](https://flikkui.dev/theming)** - Customization and CSS variables
+- 🔄 **[Migration Guides](https://flikkui.dev/migrations)** - Version upgrade guides
+
+## 🤝 Contributing
+
+We welcome contributions! Here's how you can help:
+
+- 🐛 **Report bugs** - [Create an issue](https://github.com/yourusername/flikkui/issues)
+- 💡 **Suggest features** - [Start a discussion](https://github.com/yourusername/flikkui/discussions)
+- 📝 **Improve docs** - Submit documentation PRs
+- 🎨 **Add components** - Contribute new components
+
+Please read our [Contributing Guidelines](./CONTRIBUTING.md) before submitting PRs.
 
 ## 📄 License
 
-MIT
+**MIT License** - Free to use in personal and commercial projects.
+
+See [LICENSE](./LICENSE) for full details.
 
 ---
 
-Made with ❤️ by [Espranza Innovations](https://espranza.net)
+## 🌟 Show Your Support
+
+If you find Flikkui helpful, please consider:
+
+- ⭐ **Star this repository** on GitHub
+- 🐦 **Share on Twitter** with #Flikkui
+- 📝 **Write a blog post** about your experience
+- 💬 **Join our community** discussions
+
+---
+
+## 🔗 Links
+
+- **NPM Package:** [npmjs.com/package/flikkui](https://www.npmjs.com/package/flikkui)
+- **Documentation:** [flikkui.dev](https://flikkui.dev)
+- **GitHub:** [github.com/yourusername/flikkui](https://github.com/yourusername/flikkui)
+- **Issues:** [github.com/yourusername/flikkui/issues](https://github.com/yourusername/flikkui/issues)
+- **Changelog:** [CHANGELOG.md](./CHANGELOG.md)
+
+---
+
+<p align="center">
+  Built with ❤️ by <a href="https://espranza.net">Espranza Innovations</a>
+</p>
+
+<p align="center">
+  <strong>Flikkui</strong> - Modern React Components for Modern Apps
+</p>

package/dist/cli/commands/init.d.ts

@@ -0,0 +1,7 @@
+interface InitOptions {
+    tailwind?: boolean;
+    yes?: boolean;
+    skipInstall?: boolean;
+}
+export declare function init(options: InitOptions): Promise<void>;
+export {};