zabi-components 2.0.3 → 2.1.1

package/README.md

@@ -9,10 +9,12 @@ A clean, minimal Svelte component library built with TypeScript and Tailwind CSS
 ## Features
 
 - 🎯 **TypeScript First** - Full TypeScript support with comprehensive type definitions
-- 🎨 **Tailwind CSS Integration** - Built with Tailwind CSS for consistent styling
+- 🎨 **Semantic Color System** - Built-in semantic colors with automatic dark mode support
+- 🌙 **Dark Mode Ready** - Automatic dark mode switching with CSS custom properties
 - ♿ **Accessibility First** - ARIA compliant components with keyboard navigation support
 - 📱 **Responsive Design** - Mobile-first approach with responsive utilities
 - 🧩 **Clean API** - Simple, intuitive component APIs with minimal props
+- 🔧 **Utility Functions** - Reusable variant utilities for consistent styling
 - 📦 **Tree Shakeable** - Import only what you need
 - ✅ **Production Ready** - Fully tested and optimized for production use
 - 🚀 **Modern CSS** - CSS-only positioning, animations, and interactions
@@ -59,19 +61,22 @@ import type { ButtonEvents, InputEvents } from 'zabi-components/types';
 ```svelte
 <script lang="ts">
   // Clean Components - Less is More
-  import { Card, Form, Layout, Navigation, Button, Input } from 'zabi-components';
+  import { Card, Form, Layout, Navigation, Button, Input, Textarea } from 'zabi-components';
   
   let formData = {
     name: '',
     email: '',
+    message: '',
   };
   
-  function handleFormSubmit(event: CustomEvent) {
-    console.log('Form submitted:', event.detail.data);
+  function handleFormSubmit(event: SubmitEvent) {
+    const formData = new FormData(event.target as HTMLFormElement);
+    const data = Object.fromEntries(formData.entries());
+    console.log('Form submitted:', data);
   }
   
-  function handleCardClick(event: CustomEvent) {
-    console.log('Card clicked:', event.detail);
+  function handleCardClick(event: MouseEvent) {
+    console.log('Card clicked:', event);
   }
   
   const navItems = [
@@ -88,17 +93,61 @@ import type { ButtonEvents, InputEvents } from 'zabi-components/types';
   </div>
 
   <main class="container mx-auto p-6">
-    <Card title="Welcome" description="Clean components that just work" interactive on:click={handleCardClick} />
+    <!-- Semantic Color Variants -->
+    <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4 mb-8">
+      <Card title="Default Card" variant="default" on:click={handleCardClick}>
+        This is a default card with semantic colors.
+      </Card>
+      <Card title="Success Card" variant="success" on:click={handleCardClick}>
+        This card indicates a successful action.
+      </Card>
+      <Card title="Warning Card" variant="warning" on:click={handleCardClick}>
+        This card shows a warning state.
+      </Card>
+      <Card title="Error Card" variant="error" on:click={handleCardClick}>
+        This card indicates an error state.
+      </Card>
+      <Card title="Info Card" variant="info" on:click={handleCardClick}>
+        This card provides informational content.
+      </Card>
+    </div>
     
     <Form on:submit={handleFormSubmit}>
       <div class="form-field">
-        <label for="name" class="form-label">Name</label>
-        <Input id="name" name="name" bind:value={formData.name} placeholder="Enter your name" />
+        <Input 
+          id="name" 
+          name="name" 
+          value={formData.name}
+          on:input={(e) => formData.name = e.target.value}
+          label="Name"
+          placeholder="Enter your name" 
+          variant="default"
+        />
       </div>
       
       <div class="form-field">
-        <label for="email" class="form-label">Email</label>
-        <Input id="email" name="email" type="email" bind:value={formData.email} placeholder="Enter your email" />
+        <Input 
+          id="email" 
+          name="email" 
+          type="email" 
+          value={formData.email}
+          on:input={(e) => formData.email = e.target.value}
+          label="Email"
+          placeholder="Enter your email" 
+          variant="success"
+        />
+      </div>
+
+      <div class="form-field">
+        <Textarea 
+          id="message" 
+          name="message" 
+          value={formData.message}
+          on:input={(e) => formData.message = e.target.value}
+          label="Message"
+          placeholder="Enter your message" 
+          variant="default"
+        />
       </div>
       
       <div class="form-actions">
@@ -145,6 +194,75 @@ import type { ButtonEvents, InputEvents } from 'zabi-components/types';
 | **ColorPicker** | Atom | Color selection | Simple color grid |
 | **SlideUp** | Molecule | Slide-up panel | CSS-only animations |
 
+## Semantic Color System
+
+Zabi Components includes a comprehensive semantic color system that automatically supports dark mode and provides consistent styling across all components.
+
+### Available Variants
+
+All components support these semantic color variants:
+
+- **`default`** - Standard appearance with primary colors
+- **`success`** - Green colors for positive states
+- **`warning`** - Yellow/amber colors for caution states  
+- **`error`** - Red colors for error states
+- **`info`** - Blue colors for informational states
+
+### Usage Examples
+
+```svelte
+<!-- Input variants -->
+<Input variant="default" label="Default Input" />
+<Input variant="success" label="Success Input" />
+<Input variant="warning" label="Warning Input" />
+<Input variant="error" label="Error Input" />
+
+<!-- Textarea variants -->
+<Textarea variant="default" label="Default Textarea" />
+<Textarea variant="success" label="Success Textarea" />
+
+<!-- Card variants -->
+<Card variant="default" title="Default Card" />
+<Card variant="success" title="Success Card" />
+<Card variant="warning" title="Warning Card" />
+<Card variant="error" title="Error Card" />
+<Card variant="info" title="Info Card" />
+```
+
+### Utility Functions
+
+For custom components or advanced usage, you can use the built-in utility functions:
+
+```typescript
+import { 
+  getInputVariantClasses, 
+  getCardVariantClasses, 
+  getVariantClasses 
+} from 'zabi-components';
+
+// For input components (Input, Textarea)
+const inputClass = getInputVariantClasses('success'); // Returns "input-variant-success"
+
+// For card components
+const cardClass = getCardVariantClasses('error'); // Returns "card-variant-error"
+
+// For custom components
+const borderClass = getVariantClasses('warning', 'border'); // Returns "variant-border-warning"
+const textClass = getVariantClasses('success', 'text'); // Returns "variant-text-success"
+const bgClass = getVariantClasses('info', 'bg'); // Returns "variant-bg-info"
+```
+
+### Dark Mode Support
+
+The semantic color system automatically adapts to dark mode through CSS custom properties. Simply add the `.dark` class to your document:
+
+```javascript
+// Toggle dark mode
+document.documentElement.classList.toggle('dark');
+```
+
+All components will automatically switch to their dark mode variants without any additional configuration.
+
 ## Component API
 
 ### Card Component
@@ -152,11 +270,10 @@ import type { ButtonEvents, InputEvents } from 'zabi-components/types';
 ```svelte
 <Card
   title={string}
-  subtitle={string}
-  description={string}
   image={string}
-  variant="default" | "elevated"
   interactive={boolean}
+  variant="default" | "success" | "warning" | "error" | "info"
+  size="sm" | "md" | "lg"
   className={string}
   on:click={(e) => console.log(e.detail.event)}
 >
@@ -166,11 +283,10 @@ import type { ButtonEvents, InputEvents } from 'zabi-components/types';
 
 **Props:**
 - `title`: Card title
-- `subtitle`: Card subtitle  
-- `description`: Card description
 - `image`: Card image URL
-- `variant`: Card style variant (default: "default")
 - `interactive`: Make card clickable (default: false)
+- `variant`: Card variant with semantic colors (default: "default")
+- `size`: Card size (default: "md")
 - `className`: Additional CSS classes
 
 **Events:**
@@ -183,7 +299,7 @@ import type { ButtonEvents, InputEvents } from 'zabi-components/types';
   method="get" | "post"
   action={string}
   className={string}
-  on:submit={(e) => console.log(e.detail.data, e.detail.formData)}
+  on:submit={(e) => console.log('Form submitted')}
 >
   <div class="form-field">
     <label for="field" class="form-label">Label</label>
@@ -201,7 +317,7 @@ import type { ButtonEvents, InputEvents } from 'zabi-components/types';
 - `className`: Additional CSS classes
 
 **Events:**
-- `submit`: Fired on form submission - `{ detail: { data: Record<string, FormDataEntryValue>, formData: FormData } }`
+- `submit`: Native form submit event - use `FormData` to get form data
 
 **CSS Classes:**
 - `.form-field`: Field container
@@ -239,7 +355,7 @@ import type { ButtonEvents, InputEvents } from 'zabi-components/types';
   items={Array<{label: string, href: string, icon?: any}>}
   currentPath={string}
   className={string}
-  on:navigate={(e) => console.log(e.detail.item, e.detail.href)}
+  on:click={(e) => console.log('Navigation clicked')}
 />
 ```
 
@@ -250,7 +366,7 @@ import type { ButtonEvents, InputEvents } from 'zabi-components/types';
 - `className`: Additional CSS classes
 
 **Events:**
-- `navigate`: Fired when navigation item is clicked - `{ detail: { item: NavigationItem, href: string } }`
+- `click`: Native click event on navigation items
 
 ### Button Component
 
@@ -262,7 +378,7 @@ import type { ButtonEvents, InputEvents } from 'zabi-components/types';
   loading={boolean}
   type="button" | "submit" | "reset"
   className={string}
-  on:click={(e) => console.log(e.detail.value, e.detail.event)}
+  on:click={(e) => console.log('Button clicked')}
 >
   Button Content
 </Button>
@@ -277,48 +393,69 @@ import type { ButtonEvents, InputEvents } from 'zabi-components/types';
 - `className`: Additional CSS classes
 
 **Events:**
-- `click`: Fired when button is clicked - `{ detail: { value: true, event: MouseEvent } }`
+- `click`: Native click event - `MouseEvent`
 
 ### Input Component
 
 ```svelte
 <Input
-  bind:value={string}
+  value={string}
   type={string}
   label={string}
   placeholder={string}
-  required={boolean}
   disabled={boolean}
   size="sm" | "md" | "lg"
-  variant="default" | "error" | "success"
-  error={string}
-  success={string}
-  helpText={string}
+  variant="default" | "success" | "warning" | "error"
   className={string}
-  id={string}
-  on:input={(e) => console.log(e.detail.value, e.detail.event)}
-  on:change={(e) => console.log(e.detail.value, e.detail.event)}
+  on:input={(e) => console.log('Input changed:', e.target.value)}
+  on:change={(e) => console.log('Input changed:', e.target.value)}
 />
 ```
 
 **Props:**
-- `value`: Input value (bindable)
+- `value`: Input value (controlled)
 - `type`: Input type (default: "text")
 - `label`: Input label
 - `placeholder`: Input placeholder
-- `required`: Mark as required (default: false)
 - `disabled`: Disable the input (default: false)
 - `size`: Input size (default: "md")
-- `variant`: Input variant (default: "default")
-- `error`: Error message
-- `success`: Success message
-- `helpText`: Helper text
+- `variant`: Input variant with semantic colors (default: "default")
 - `className`: Additional CSS classes
-- `id`: Input ID
 
 **Events:**
-- `input`: Fired on input - `{ detail: { value: string, event: InputEvent } }`
-- `change`: Fired on change - `{ detail: { value: string, event: Event } }`
+- `input`: Native input event - `InputEvent`
+- `change`: Native change event - `Event`
+
+### Textarea Component
+
+```svelte
+<Textarea
+  value={string}
+  label={string}
+  placeholder={string}
+  disabled={boolean}
+  rows={number}
+  size="sm" | "md" | "lg"
+  variant="default" | "success" | "warning" | "error"
+  className={string}
+  on:input={(e) => console.log('Textarea changed:', e.target.value)}
+  on:change={(e) => console.log('Textarea changed:', e.target.value)}
+/>
+```
+
+**Props:**
+- `value`: Textarea value (controlled)
+- `label`: Textarea label
+- `placeholder`: Textarea placeholder
+- `disabled`: Disable the textarea (default: false)
+- `rows`: Number of visible text lines (default: 4)
+- `size`: Textarea size (default: "md")
+- `variant`: Textarea variant with semantic colors (default: "default")
+- `className`: Additional CSS classes
+
+**Events:**
+- `input`: Native input event - `InputEvent`
+- `change`: Native change event - `Event`
 
 ### Card Component
 
@@ -489,127 +626,125 @@ Dark mode is automatically supported through CSS custom properties:
 }
 ```
 
-## Event Structure
-
-All components follow a consistent event structure:
+## Event Handling
 
-```typescript
-interface BaseEventDetail<T = any> {
-  value: T;
-  event?: Event;
-}
-```
+Zabi Components now use **native DOM events** with **event forwarding** for maximum compatibility across frameworks.
 
-**Examples:**
-- Button click: `{ detail: { value: true, event: MouseEvent } }`
-- Input change: `{ detail: { value: string, event: Event } }`
-- Checkbox change: `{ detail: { value: boolean, event: Event } }`
+### Event Forwarding
 
-## TypeScript Support
+All components use `{...$$restProps}` to forward native DOM events, making them compatible with React, Vue, Svelte, and vanilla JavaScript.
 
-Full TypeScript definitions are included with comprehensive type safety:
+```svelte
+<!-- All these work the same way -->
+<Button on:click={handleClick}>Click me</Button>
+<Input on:input={handleInput} on:change={handleChange} />
+<Modal on:click={handleClose} on:keydown={handleKeydown} />
+```
 
-### Event Types
-```typescript
-import type { 
-  ButtonEvents, 
-  InputEvents, 
-  CardEvents, 
-  FormEvents,
-  NavigationEvents,
-  KeyValueFormEvents 
-} from 'zabi-components';
+### Form Components
 
-// Properly typed event handlers
-function handleButtonClick(event: CustomEvent<{ value: boolean; event?: MouseEvent }>) {
-  console.log('Button clicked:', event.detail.value);
-}
+Form components use **controlled components** pattern instead of two-way binding:
 
-function handleFormSubmit(event: CustomEvent<{ 
-  data: Record<string, FormDataEntryValue>; 
-  formData: FormData 
-}>) {
-  console.log('Form data:', event.detail.data);
-}
+```svelte
+<script lang="ts">
+  let inputValue = '';
+  let checkboxValue = false;
+  
+  function handleInput(event: Event) {
+    inputValue = (event.target as HTMLInputElement).value;
+  }
+  
+  function handleCheckbox(event: Event) {
+    checkboxValue = (event.target as HTMLInputElement).checked;
+  }
+</script>
 
-function handleNavigation(event: CustomEvent<{ 
-  item: NavigationItem; 
-  href: string 
-}>) {
-  console.log('Navigate to:', event.detail.href);
-}
+<Input 
+  value={inputValue} 
+  on:input={handleInput} 
+  label="Name" 
+/>
+<Checkbox 
+  checked={checkboxValue} 
+  on:change={handleCheckbox} 
+  label="Subscribe" 
+/>
 ```
 
-### Component Props
-```typescript
-// All components have proper prop typing
-interface CardProps {
-  title?: string;
-  subtitle?: string;
-  description?: string;
-  image?: string;
-  variant?: "default" | "elevated";
-  interactive?: boolean;
-  className?: string;
-}
+### Migration from Previous Versions
 
-interface FormProps {
-  method?: "get" | "post";
-  action?: string;
-  className?: string;
-}
+**Before (v2.0.x):**
+```svelte
+<Input bind:value={inputValue} />
+<Button on:click={handleClick}>Click</Button>
+<Modal bind:isOpen on:close={handleClose} />
 ```
 
-### Event Dispatchers
-```typescript
-// Components use typed event dispatchers
-const dispatch = createEventDispatcher<{
-  click: { event: MouseEvent };
-  submit: { data: Record<string, FormDataEntryValue>; formData: FormData };
-  navigate: { item: NavigationItem; href: string };
-}>();
+**After (v2.1.x):**
+```svelte
+<Input value={inputValue} on:input={(e) => inputValue = e.target.value} />
+<Button on:click={handleClick}>Click</Button>
+<Modal bind:isOpen on:click={handleClose} />
 ```
 
+### Benefits
+
+- ✅ **SSR Safe**: No more hydration errors in production
+- ✅ **Cross-Framework**: Works in React, Vue, Svelte, vanilla JS
+- ✅ **Standards Compliant**: Uses native DOM events
+- ✅ **Better Performance**: Reduced JavaScript overhead
+
+## TypeScript Support
+
+Full TypeScript definitions are included with comprehensive type safety:
+
 ### Event Types
 
-All components use standardized event types:
+All components now use native DOM events with proper TypeScript typing:
 
 ```typescript
-// Base event structure
-interface BaseEventDetail<T = any> {
-  value: T;
-  event?: Event;
+// Native event handlers with proper typing
+function handleButtonClick(event: MouseEvent) {
+  console.log('Button clicked:', event);
 }
 
-// Specific event types
-interface ClickEventDetail extends BaseEventDetail<boolean> {
-  event?: MouseEvent | KeyboardEvent;
+function handleInputChange(event: Event) {
+  const target = event.target as HTMLInputElement;
+  console.log('Input value:', target.value);
 }
 
-interface InputEventDetail extends BaseEventDetail<string> {
-  event?: InputEvent;
-}
-
-interface ChangeEventDetail extends BaseEventDetail<string> {
-  event?: Event;
+function handleFormSubmit(event: SubmitEvent) {
+  const formData = new FormData(event.target as HTMLFormElement);
+  const data = Object.fromEntries(formData.entries());
+  console.log('Form data:', data);
 }
 ```
 
-### Component Event Interfaces
+### Component Props
+
+All components have proper prop typing with event forwarding:
 
 ```typescript
-interface ButtonEvents {
-  click: ClickEventDetail;
+// All components support event forwarding
+interface ButtonProps {
+  variant?: "primary" | "secondary" | "danger";
+  size?: "sm" | "md" | "lg";
+  disabled?: boolean;
+  type?: "button" | "submit" | "reset";
+  className?: string;
+  // All native button events are forwarded via {...$$restProps}
 }
 
-interface InputEvents {
-  input: InputEventDetail;
-  change: ChangeEventDetail;
-  focus: { event: FocusEvent };
-  blur: { event: FocusEvent };
-  keydown: { event: KeyboardEvent };
-  keyup: { event: KeyboardEvent };
-  clear: { event: Event };
+interface InputProps {
+  value?: string;
+  type?: string;
+  label?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  size?: "sm" | "md" | "lg";
+  variant?: "default" | "success" | "warning" | "error";
+  className?: string;
+  // All native input events are forwarded via {...$$restProps}
 }
 ```
 
@@ -622,7 +757,7 @@ interface InputEvents {
   variant="primary" 
   size="lg" 
   className="w-full shadow-lg hover:shadow-xl"
-  on:click={(e) => console.log('Clicked!', e.detail.value)}
+  on:click={(e) => console.log('Clicked!', e)}
 >
   Custom Button
 </Button>
@@ -662,7 +797,7 @@ interface InputEvents {
     return Object.keys(errors).length === 0;
   }
   
-  function handleSubmit(event: CustomEvent) {
+  function handleSubmit(event: SubmitEvent) {
     if (validateForm()) {
       showSuccess = true;
       // Submit form
@@ -678,27 +813,27 @@ interface InputEvents {
   
   <form on:submit|preventDefault={handleSubmit}>
     <Input
-      bind:value={formData.name}
+      value={formData.name}
+      on:input={(e) => formData.name = e.target.value}
       label="Name"
       placeholder="Enter your name"
       required
-      error={errors.name}
     />
     
     <Input
-      bind:value={formData.email}
+      value={formData.email}
       type="email"
+      on:input={(e) => formData.email = e.target.value}
       label="Email"
       placeholder="Enter your email"
       required
-      error={errors.email}
     />
     
     <Input
-      bind:value={formData.message}
+      value={formData.message}
+      on:input={(e) => formData.message = e.target.value}
       label="Message"
       placeholder="Enter your message"
-      helpText="Tell us what you think"
     />
     
     <Button type="submit" variant="primary">
@@ -707,9 +842,11 @@ interface InputEvents {
   </form>
   
   <div slot="footer">
-    <Alert variant="success" closable bind:show={showSuccess}>
-      Message sent successfully!
-    </Alert>
+    {#if showSuccess}
+      <Alert variant="success" closable>
+        Message sent successfully!
+      </Alert>
+    {/if}
   </div>
 </Card>
 ```
@@ -728,50 +865,32 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ## Changelog
 
-### v1.1.1 (Latest) - "Enhanced Type Safety" Edition
-
-#### 🔧 TypeScript Improvements
-- **Enhanced Type Definitions**: Updated generated TypeScript definitions for better type safety
-- **Improved Package Structure**: Enhanced package structure with improved type exports
-- **Build Consistency**: Fixed build consistency and versioning across all generated files
-- **Better Type Exports**: Improved TypeScript declaration file generation
-
-#### 🎯 Philosophy Change
-- **Clean & Simple**: Adopted "less is more" philosophy - removed unnecessary complexity
-- **Focused Components**: Streamlined to essential components that just work
-- **Clean Naming**: Removed "Simple" prefixes - it's just Card, Form, Layout, Navigation
-
-#### ✨ New Clean Components
-- **Card**: Clean, semantic card container with interactive support
-- **Form**: Simple form wrapper with FormData handling and validation
-- **Layout**: Page layout system with header, main, footer slots
-- **Navigation**: Clean navigation with header/sidebar variants
-
-#### 🐛 Bug Fixes
-- **Fixed TypeScript Errors**: Resolved all event handler type mismatches
-- **Fixed Import Paths**: Corrected .js extensions in lib exports
-- **Fixed CSS Issues**: Resolved `:global()` selector placement errors
-- **Fixed Variant Types**: Corrected component variant type mismatches
-- **Fixed Accessibility**: Resolved tabindex warnings for non-interactive elements
-
-#### 🚀 Modern CSS Features
-- **Container Queries**: Added support for container-based responsive design
-- **CSS Grid & Subgrid**: Implemented modern grid layouts
-- **CSS Logical Properties**: Added RTL support with logical properties
-- **CSS Cascade Layers**: Organized styles with cascade layers
-- **CSS Containment**: Added performance optimizations
-
-#### 📦 TypeScript Improvements
-- **Event Type Safety**: All components now have proper event typing
-- **Component Props**: Comprehensive prop type definitions
-- **Event Dispatchers**: Typed event dispatchers for all components
-- **Type Generation**: Proper TypeScript declaration generation
-
-#### 🎨 Design System
-- **Semantic HTML**: All components use proper semantic elements
-- **Accessibility**: ARIA compliant with keyboard navigation
-- **Dark Mode**: Built-in dark mode support with CSS custom properties
-- **Responsive**: Mobile-first responsive design
+### v2.1.0 (Latest) - "Cross-Framework Compatible" Edition
+
+#### 🚀 **MAJOR BREAKING CHANGES** - Event Handling Overhaul
+
+This is a **major breaking change** that affects how all components handle events. The refactoring eliminates SSR/production errors and makes components compatible with React, Vue, and vanilla JavaScript applications.
+
+#### ✅ **What's Fixed**
+- **SSR/Production Errors**: Eliminated all `createEventDispatcher` hydration errors
+- **Cross-Framework Compatibility**: Components now work in React, Vue, Svelte, and vanilla JS
+- **Event Forwarding**: All components use `{...$$restProps}` for native DOM events
+- **Standards Compliance**: Uses web standards instead of framework-specific events
+
+#### 🔄 **Migration Required**
+- **Form Components**: Replace `bind:value` with `value` prop + event handlers
+- **Event Names**: Some custom events replaced with native DOM events
+- **Event Structure**: Simplified event structures across all components
+
+#### 📋 **Breaking Changes**
+1. **Form Components**: Must use `value` prop + event handlers instead of `bind:value`
+2. **Event Names**: Some custom events replaced with native DOM events
+3. **Event Structure**: Simplified event structures across all components
+4. **SSR Compatibility**: Components now work correctly in SSR environments
+
+See the [Migration Guide](#migration-from-previous-versions) above for detailed examples.
+
+### v2.0.2 - "Less is More" Edition
 
 ## Development Setup