@diyet24/design-system 0.1.0

package/README.md

@@ -0,0 +1,592 @@
+# Diyet24 Design System
+
+A production-ready React component library built with TypeScript, Tailwind CSS v4, and Radix UI primitives. Designed for Next.js App Router with full RSC support, comprehensive Storybook documentation, and advanced animation system
+
+## ✨ Features
+
+- 🎨 **50+ Production-Ready Components** - Complete UI toolkit with shadcn/ui integration
+- 🚀 **Next.js 15 App Router Ready** - Full RSC support with "use client" directives
+- 📚 **Comprehensive Storybook** - Interactive documentation with accessibility testing
+- 🎯 **TypeScript First** - Full type safety, strict mode, and IntelliSense
+- 🎨 **Tailwind CSS v4** - CSS-first architecture with design tokens
+- ♿ **Accessibility** - WCAG 2.1 AA compliant with ARIA support
+- 🌙 **Dark Mode** - Built-in theme system with CSS variables
+- 📦 **Tree Shakable** - Optimized bundle size with ESM/CJS support
+- 🔧 **Radix UI Powered** - Accessible, unstyled primitives
+- ⚡ **Advanced Animations** - Smooth transitions with Radix transform-origin support
+- 🎭 **CVA Integration** - Type-safe component variants with class-variance-authority
+- 🔄 **Dynamic Interactions** - Ripple effects, scroll overlays, and micro-animations
+
+## 📦 Installation
+
+```bash
+npm install @diyet24/design-system
+# or
+pnpm add @diyet24/design-system
+# or
+yarn add @diyet24/design-system
+```
+
+### Peer Dependencies
+```bash
+npm install react@^18.0.0 react-dom@^18.0.0 lucide-react
+```
+
+## 🚀 Quick Start
+
+### 1. Setup Tailwind CSS v4
+
+**Install Tailwind CSS v4:**
+```bash
+npm install tailwindcss@next @tailwindcss/postcss@next
+```
+
+**Configure your CSS file (e.g., `app/globals.css`):**
+```css
+@import "tailwindcss";
+@import "@diyet24/design-system/styles.css";
+
+/* Your custom CSS */
+```
+
+**⚠️ Important:** The order matters! Import `tailwindcss` first, then the design system styles.
+
+### 2. Configure Tailwind (Optional - for theme customization)
+
+If you want to extend or customize the theme:
+
+```typescript
+// tailwind.config.ts
+import type { Config } from 'tailwindcss';
+import { colors, spacing, shadows } from '@diyet24/design-system/tailwind';
+
+const config: Config = {
+  content: [
+    './src/**/*.{js,ts,jsx,tsx,mdx}',
+    './node_modules/@diyet24/design-system/dist/**/*.{js,mjs}',
+  ],
+  theme: {
+    extend: {
+      colors,      // Design system color palette
+      spacing,     // Consistent spacing scale
+      boxShadow: shadows, // Elevation system
+    },
+  },
+};
+
+export default config;
+```
+
+### 3. Use Components
+
+```tsx
+import { Button, Card, CardContent, CardHeader, CardTitle } from '@diyet24/design-system';
+
+export default function MyPage() {
+  return (
+    <Card className="w-96">
+      <CardHeader>
+        <CardTitle>Welcome to Diyet24</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <Button variant="contained" color="primary">
+          Get Started
+        </Button>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+## 🎨 Component Categories
+
+### Form & Input (15 components)
+- **Button** - 5 variants (contained, outline, ghost, tonal, link) × 6 colors with ripple effects
+- **Input** - Text input with validation states
+- **Textarea** - Multi-line text input
+- **Checkbox** - Accessible checkbox with indeterminate state
+- **Radio Group** - Radio button groups
+- **Select** - Native-like dropdown with search
+- **Combobox** - Searchable select with autocomplete
+- **Switch** - Toggle switch component
+- **Slider** - Range input slider
+- **Calendar** - Date picker calendar
+- **Date Picker** - Date selection with calendar popup
+- **Input OTP** - One-time password input
+- **Label** - Form field labels
+- **Toggle** - Binary toggle button
+- **Toggle Group** - Grouped toggle buttons
+
+### Layout & Navigation (12 components)
+- **Card** - Container with header, content, and footer
+- **Tabs** - Tabbed navigation
+- **Accordion** - Collapsible content sections
+- **Navigation Menu** - Complex navigation with dropdowns (with Portal support)
+- **Breadcrumb** - Breadcrumb navigation trail
+- **Pagination** - Page navigation component
+- **Separator** - Visual divider
+- **Aspect Ratio** - Aspect ratio container
+- **Scroll Area** - Custom scrollable area with gradient overlays
+- **Resizable** - Resizable panel layouts
+- **Flex** - Flexbox utility component
+- **Grid** - Grid utility component
+
+### Overlay & Modal (10 components)
+- **Dialog** - Modal dialog with animations
+- **Alert Dialog** - Confirmation dialog
+- **Sheet** - Slide-in panel (4 directions with smooth slide animations)
+- **Drawer** - Bottom drawer with drag gesture
+- **Popover** - Floating content container (with transform-origin positioning)
+- **Dropdown Menu** - Contextual menu (with transform-origin positioning)
+- **Context Menu** - Right-click menu (with transform-origin positioning)
+- **Hover Card** - Hover-triggered card (with transform-origin positioning)
+- **Tooltip** - Informational tooltip
+- **Command** - Command palette / Quick search
+
+### Feedback & Display (8 components)
+- **Toast** - Notification system (with Sonner)
+- **Alert** - Inline alert messages
+- **Badge** - Status badges and labels
+- **Avatar** - User avatar with fallback
+- **Progress** - Progress bar indicator
+- **Skeleton** - Loading placeholder
+- **Spinner** - Loading spinner
+- **Typography** - Text styling utilities
+
+### Data & Table (3 components)
+- **Table** - Semantic HTML table
+- **Data Table** - Advanced table with sorting, filtering, pagination (@tanstack/react-table)
+- **Collapsible** - Collapsible content container
+
+### Advanced Components (4 components)
+- **Carousel** - Image/content carousel (Embla)
+- **Menubar** - Application menu bar
+- **Dashboard** - Dashboard layout container
+- **Section** - Semantic section wrapper
+- **KBD** - Keyboard key display
+
+## 🎯 Advanced Features
+
+### Button Variants & Colors
+
+The Button component uses a matrix system with CVA:
+
+```tsx
+// 5 Variants × 6 Colors = 30 Combinations
+<Button variant="contained" color="primary">Contained Primary</Button>
+<Button variant="outline" color="danger">Outline Danger</Button>
+<Button variant="ghost" color="success">Ghost Success</Button>
+<Button variant="tonal" color="warning">Tonal Warning</Button>
+<Button variant="link" color="info">Link Info</Button>
+
+// Sizes
+<Button size="sm">Small</Button>
+<Button size="default">Default</Button>
+<Button size="lg">Large</Button>
+<Button size="xl">Extra Large</Button>
+<Button size="icon-sm">Icon</Button>
+
+// Ripple Effect (automatic)
+// - White ripple on contained variants
+// - Colored ripple (20% opacity) on outline/ghost/tonal/link
+```
+
+### Animation System
+
+All portal-based components use Radix UI's transform-origin CSS variables for smooth, position-accurate animations:
+
+```css
+/* Automatic transform-origin positioning */
+.PopoverContent {
+  transform-origin: var(--radix-popover-content-transform-origin);
+}
+
+.DropdownMenuContent {
+  transform-origin: var(--radix-dropdown-menu-content-transform-origin);
+}
+
+.SelectContent {
+  transform-origin: var(--radix-select-content-transform-origin);
+}
+
+/* And more... */
+```
+
+**Components with optimized animations:**
+- Popover
+- Dropdown Menu
+- Context Menu
+- Hover Card
+- Select
+- Menubar
+- Navigation Menu
+- Sheet (slide animations from 4 directions)
+
+### Scroll Area Enhancements
+
+ScrollArea includes automatic gradient overlays that show/hide based on scroll position:
+
+```tsx
+<ScrollArea className="h-72">
+  {/* Top gradient appears when scrolled down */}
+  {/* Bottom gradient appears when more content below */}
+  <YourContent />
+</ScrollArea>
+```
+
+### Data Table Features
+
+The DataTable component is production-ready with:
+
+```tsx
+import { DataTable } from '@diyet24/design-system';
+import { ColumnDef } from '@tanstack/react-table';
+
+const columns: ColumnDef<User>[] = [
+  {
+    accessorKey: 'name',
+    header: 'Name',
+    enableSorting: true,
+  },
+  // ... more columns
+];
+
+<DataTable 
+  columns={columns}
+  data={users}
+  searchable
+  searchPlaceholder="Search users..."
+  pageSize={10}
+/>
+```
+
+**Features:**
+- Column sorting
+- Global search with debounce
+- Pagination with page size options
+- Row selection
+- Custom cell renderers
+- Loading states
+- Empty states
+
+## 🎨 Theme Configuration
+
+### Color System
+
+The design system uses a comprehensive color palette with CSS variables:
+
+```typescript
+import { colors } from '@diyet24/design-system/tailwind';
+
+// Available colors:
+colors.primary     // #7367F0 (with shades 100-900)
+colors.secondary   // #808390
+colors.success     // #28C76F
+colors.warning     // #FF9F43
+colors.danger      // #FF4C51
+colors.info        // #00BAD1
+```
+
+### Dark Mode
+
+Dark mode is handled automatically via CSS variables:
+
+```tsx
+import { ThemeProvider } from 'next-themes';
+
+function App({ children }) {
+  return (
+    <ThemeProvider attribute="class" defaultTheme="system">
+      {children}
+    </ThemeProvider>
+  );
+}
+```
+
+### Customizing Theme
+
+Override CSS variables in your global CSS:
+
+```css
+:root {
+  --primary: #your-color;
+  --radius: 8px;
+}
+
+.dark {
+  --primary: #your-dark-color;
+}
+```
+
+## 📖 Storybook
+
+Explore all components interactively:
+
+```bash
+cd design-system
+npm run dev
+# Opens http://localhost:6006
+```
+
+**Storybook features:**
+- 📝 Interactive component playground
+- 🎨 All variants and states documented
+- ♿ Accessibility testing (a11y addon)
+- 📱 Responsive preview
+- 🌙 Dark mode toggle
+- 📋 Code snippets for each example
+
+## 🏗️ Development
+
+### Project Structure
+
+```
+design-system/
+├── src/
+│   ├── components/
+│   │   └── ui/
+│   │       ├── button/
+│   │       │   ├── button.tsx
+│   │       │   └── button.stories.tsx
+│   │       ├── card/
+│   │       └── ... (50+ components)
+│   ├── styles/
+│   │   └── index.css          # Theme, animations, CSS variables
+│   ├── tailwind/
+│   │   └── index.ts           # Exportable Tailwind config
+│   └── index.ts               # Main export file
+├── dist/
+│   ├── index.js               # ESM bundle
+│   ├── index.cjs              # CommonJS bundle
+│   ├── index.d.ts             # TypeScript definitions
+│   └── styles.css             # Compiled CSS
+├── package.json
+├── tsconfig.json
+├── tsup.config.ts             # Build configuration
+└── README.md
+```
+
+### Build System
+
+The library uses **tsup** for bundling:
+
+```json
+{
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./tailwind": {
+      "types": "./dist/tailwind/index.d.ts",
+      "import": "./dist/tailwind/index.js",
+      "require": "./dist/tailwind/index.cjs"
+    },
+    "./styles.css": "./dist/styles.css",
+    "./styles": "./dist/styles.css"
+  }
+}
+```
+
+**Features:**
+- ✅ Dual format (ESM + CJS)
+- ✅ TypeScript declarations (.d.ts)
+- ✅ Source maps
+- ✅ Tree shaking support
+- ✅ "use client" directive for all components
+- ✅ External React/React-DOM (peer dependencies)
+
+### Scripts
+
+```bash
+# Development
+npm run dev              # Start Storybook
+npm run build           # Build library
+npm run build:storybook # Build Storybook static site
+
+# Quality
+npm run lint            # ESLint
+npm run format          # Prettier
+npm run typecheck       # TypeScript check
+
+# Publishing
+npm run prepublishOnly  # Runs build before publish
+```
+
+### Adding New Components
+
+1. **Create component directory:**
+```bash
+mkdir src/components/ui/my-component
+```
+
+2. **Create component file:**
+```tsx
+// src/components/ui/my-component/my-component.tsx
+import * as React from "react";
+import { cn } from "@/lib/utils";
+
+export interface MyComponentProps extends React.HTMLAttributes<HTMLDivElement> {
+  variant?: "default" | "custom";
+}
+
+export const MyComponent = React.forwardRef<HTMLDivElement, MyComponentProps>(
+  ({ className, variant = "default", ...props }, ref) => {
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          "base-styles",
+          variant === "custom" && "custom-styles",
+          className
+        )}
+        {...props}
+      />
+    );
+  }
+);
+
+MyComponent.displayName = "MyComponent";
+```
+
+3. **Create Storybook story:**
+```tsx
+// src/components/ui/my-component/my-component.stories.tsx
+import type { Meta, StoryObj } from '@storybook/react';
+import { MyComponent } from './my-component';
+
+const meta: Meta<typeof MyComponent> = {
+  title: 'Components/MyComponent',
+  component: MyComponent,
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof MyComponent>;
+
+export const Default: Story = {
+  args: {
+    variant: 'default',
+  },
+};
+```
+
+4. **Export from index:**
+```tsx
+// src/components/ui/index.ts
+export * from './my-component/my-component';
+```
+
+## 🔧 Technical Details
+
+### TypeScript Configuration
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "jsx": "react-jsx",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}
+```
+
+### CSS Architecture
+
+**Tailwind v4 CSS-first approach:**
+```css
+@import "tailwindcss";           /* Tailwind base */
+@custom-variant dark (&:is(.dark *));
+@source "../";                    /* Auto-scan components */
+
+:root {
+  /* CSS Variables */
+  --primary: #7367F0;
+  /* ... */
+}
+
+.dark {
+  /* Dark mode overrides */
+  --primary: #7367F0;
+  /* ... */
+}
+```
+
+**Custom Animations:**
+- Radix transform-origin integration
+- Scale-based animations (zoom-in/out)
+- Slide animations (4 directions)
+- Fade transitions
+- Accordion slide down/up
+- Ripple effects
+
+### Bundle Size
+
+**Optimizations:**
+- Tree-shakable exports
+- External React/React-DOM
+- No runtime CSS-in-JS
+- Minification disabled (consumer handles)
+- Source maps for debugging
+
+**Typical imports:**
+```tsx
+// Only imports Button code
+import { Button } from '@diyet24/design-system';
+// ~15KB (gzipped)
+
+// Only imports Table components
+import { Table, TableBody, TableCell } from '@diyet24/design-system';
+// ~8KB (gzipped)
+```
+
+## 🤝 Contributing
+
+1. Clone the repository
+2. Install dependencies: `pnpm install`
+3. Start Storybook: `pnpm dev`
+4. Make changes and test in Storybook
+5. Build: `pnpm build`
+6. Create pull request
+
+### Code Style
+
+- Use TypeScript strict mode
+- Follow React best practices
+- Use forwardRef for components
+- Include displayName
+- Document with JSDoc comments
+- Create Storybook stories
+- Test accessibility
+
+## 📝 License
+
+MIT © Diyet24
+
+## 🔗 Links
+
+- [Storybook](http://localhost:6006) (local development)
+- [Repository](https://github.com/diyet24/design-system)
+- [NPM Package](https://www.npmjs.com/package/@diyet24/design-system)
+
+## 🙏 Acknowledgments
+
+Built with:
+- [Radix UI](https://www.radix-ui.com/) - Accessible primitives
+- [Tailwind CSS](https://tailwindcss.com/) - Utility-first CSS
+- [shadcn/ui](https://ui.shadcn.com/) - Component patterns
+- [TanStack Table](https://tanstack.com/table) - Table functionality
+- [Lucide Icons](https://lucide.dev/) - Icon system
+- [Class Variance Authority](https://cva.style/) - Variant management
+
+---
+
+**Built with ❤️ by Diyet24 Team**