zabi-components 1.0.7 → 1.0.9

package/README.md

@@ -1,18 +1,22 @@
 # Zabi Components
 
-A comprehensive Svelte component library built with TypeScript and Tailwind CSS, designed for easy integration across multiple Svelte projects.
+A clean, minimal Svelte component library built with TypeScript and Tailwind CSS. **Less is more** - focused on essential components that just work.
+
+## Philosophy
+
+**Clean & Simple**: No unnecessary complexity, just clean components that focus on what matters most. Every component is designed to be intuitive, accessible, and performant.
 
 ## Features
 
-- 🎨 **Consistent Design System** - Standardized props, events, and styling across all components
 - 🎯 **TypeScript First** - Full TypeScript support with comprehensive type definitions
-- 🎨 **Tailwind CSS Integration** - Built with Tailwind CSS and CSS custom properties for easy theming
+- 🎨 **Tailwind CSS Integration** - Built with Tailwind CSS for consistent styling
 - ♿ **Accessibility First** - ARIA compliant components with keyboard navigation support
 - 📱 **Responsive Design** - Mobile-first approach with responsive utilities
 - 🎭 **Dark Mode Support** - Built-in dark mode support with CSS custom properties
-- 🧩 **Slot Support** - Flexible slot system for custom content
+- 🧩 **Clean API** - Simple, intuitive component APIs
 - 📦 **Tree Shakeable** - Import only what you need
 - ✅ **Production Ready** - Fully tested and optimized for production use
+- 🚀 **Modern CSS** - Uses modern CSS features like Container Queries and CSS Grid
 
 ## Installation
 
@@ -53,53 +57,191 @@ import type { ButtonEvents, InputEvents } from 'zabi-components/types';
 
 ```svelte
 <script lang="ts">
-  import { Button, Input, Card, Alert } from 'zabi-components';
+  // Clean Components - Less is More
+  import { Card, Form, Layout, Navigation, Button, Input } from 'zabi-components';
   
-  let name = '';
-  let showAlert = false;
+  let formData = {
+    name: '',
+    email: '',
+  };
   
-  function handleSubmit(event: CustomEvent) {
-    console.log('Form submitted!', event.detail.value);
-    showAlert = true;
+  function handleFormSubmit(event: CustomEvent) {
+    console.log('Form submitted:', event.detail.data);
   }
   
-  function handleInput(event: CustomEvent) {
-    console.log('Input changed:', event.detail.value);
+  function handleCardClick(event: CustomEvent) {
+    console.log('Card clicked:', event.detail);
   }
   
-  function handleClose() {
-    showAlert = false;
-  }
+  const navItems = [
+    { label: "Home", href: "/" },
+    { label: "About", href: "/about" },
+    { label: "Contact", href: "/contact" },
+  ];
 </script>
 
-<Card>
-  <div slot="header">
-    <h2>User Form</h2>
+<Layout variant="main" className="min-h-screen bg-gray-50">
+  <div slot="header" class="flex items-center justify-between p-4 bg-white border-b">
+    <h1 class="text-xl font-bold">My App</h1>
+    <Navigation variant="header" items={navItems} />
   </div>
-  
-  <Input 
-    bind:value={name} 
-    label="Name" 
-    placeholder="Enter your name"
-    on:input={handleInput}
-  />
-  
-  <Button on:click={handleSubmit}>
-    Submit
-  </Button>
-  
-  <div slot="footer">
-    {#if showAlert}
-      <Alert variant="success" closable on:close={handleClose}>
-        Form submitted successfully!
-      </Alert>
-    {/if}
-  </div>
-</Card>
+
+  <main class="container mx-auto p-6">
+    <Card title="Welcome" description="Clean components that just work" interactive on:click={handleCardClick} />
+    
+    <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" />
+      </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" />
+      </div>
+      
+      <div class="form-actions">
+        <Button type="submit" variant="primary" className="flex-1">Submit</Button>
+      </div>
+    </Form>
+  </main>
+</Layout>
 ```
 
+## Component Overview
+
+### Core Components (Clean & Simple)
+
+| Component | Category | Description | Key Features |
+|-----------|----------|-------------|--------------|
+| **Card** | Atom | Clean card container | Interactive, elevated variants, semantic HTML |
+| **Form** | Molecule | Simple form wrapper | FormData handling, validation support |
+| **Layout** | Molecule | Page layout system | Header, main, footer slots, responsive |
+| **Navigation** | Organism | Clean navigation | Header/sidebar variants, keyboard nav |
+| **Button** | Atom | Action button | Multiple variants, loading states |
+| **Input** | Atom | Form input | Validation, error states, accessibility |
+| **Badge** | Atom | Status indicator | Color variants, closable |
+| **Alert** | Molecule | Notification | Dismissible, multiple variants |
+| **Modal** | Molecule | Overlay dialog | Focus trap, keyboard navigation |
+| **Tabs** | Molecule | Tab navigation | Keyboard navigation, ARIA compliant |
+
+### Advanced Components
+
+| Component | Category | Description | Key Features |
+|-----------|----------|-------------|--------------|
+| **KeyValueForm** | Molecule | Dynamic form builder | Field types, validation, TypeScript |
+| **ImageUpload** | Molecule | File upload | Drag & drop, preview, validation |
+| **Dropdown** | Molecule | Select dropdown | Search, keyboard navigation |
+| **ToastManager** | Organism | Toast notifications | Queue management, positioning |
+| **Navbar** | Organism | Navigation bar | Mobile menu, responsive |
+
 ## Component API
 
+### Card Component
+
+```svelte
+<Card
+  title={string}
+  subtitle={string}
+  description={string}
+  image={string}
+  variant="default" | "elevated"
+  interactive={boolean}
+  className={string}
+  on:click={(e) => console.log(e.detail.event)}
+>
+  Custom Content
+</Card>
+```
+
+**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)
+- `className`: Additional CSS classes
+
+**Events:**
+- `click`: Fired when interactive card is clicked - `{ detail: { event: MouseEvent } }`
+
+### Form Component
+
+```svelte
+<Form
+  method="get" | "post"
+  action={string}
+  className={string}
+  on:submit={(e) => console.log(e.detail.data, e.detail.formData)}
+>
+  <div class="form-field">
+    <label for="field" class="form-label">Label</label>
+    <Input id="field" name="field" class="form-input" />
+  </div>
+  <div class="form-actions">
+    <Button type="submit">Submit</Button>
+  </div>
+</Form>
+```
+
+**Props:**
+- `method`: Form method (default: "post")
+- `action`: Form action URL
+- `className`: Additional CSS classes
+
+**Events:**
+- `submit`: Fired on form submission - `{ detail: { data: Record<string, FormDataEntryValue>, formData: FormData } }`
+
+**CSS Classes:**
+- `.form-field`: Field container
+- `.form-label`: Field label
+- `.form-input`: Field input
+- `.form-actions`: Action buttons container
+
+### Layout Component
+
+```svelte
+<Layout
+  variant="main" | "sidebar" | "grid"
+  className={string}
+>
+  <div slot="header">Header Content</div>
+  Main Content
+  <div slot="footer">Footer Content</div>
+</Layout>
+```
+
+**Props:**
+- `variant`: Layout type (default: "main")
+- `className`: Additional CSS classes
+
+**Slots:**
+- `header`: Header content
+- `default`: Main content
+- `footer`: Footer content
+
+### Navigation Component
+
+```svelte
+<Navigation
+  variant="header" | "sidebar"
+  items={Array<{label: string, href: string, icon?: any}>}
+  currentPath={string}
+  className={string}
+  on:navigate={(e) => console.log(e.detail.item, e.detail.href)}
+/>
+```
+
+**Props:**
+- `variant`: Navigation type (default: "header")
+- `items`: Navigation items array
+- `currentPath`: Current active path
+- `className`: Additional CSS classes
+
+**Events:**
+- `navigate`: Fired when navigation item is clicked - `{ detail: { item: NavigationItem, href: string } }`
+
 ### Button Component
 
 ```svelte
@@ -228,9 +370,56 @@ import type { ButtonEvents, InputEvents } from 'zabi-components/types';
 **Events:**
 - `close`: Fired when alert is closed - `{ detail: { value: true, event: Event } }`
 
+## Modern CSS Features
+
+Zabi Components leverages modern CSS features for better performance and developer experience:
+
+### Container Queries
+```css
+.card {
+  container-type: inline-size;
+}
+
+@container (min-width: 300px) {
+  .card-content {
+    display: flex;
+    flex-direction: row;
+  }
+}
+```
+
+### CSS Grid & Subgrid
+```css
+.layout-grid {
+  display: grid;
+  grid-template-columns: subgrid;
+  gap: 1rem;
+}
+```
+
+### CSS Logical Properties
+```css
+.component {
+  margin-inline-start: 1rem;
+  padding-block: 0.5rem;
+  border-inline-end: 1px solid;
+}
+```
+
+### CSS Cascade Layers
+```css
+@layer base, components, utilities;
+
+@layer components {
+  .card {
+    /* Component styles */
+  }
+}
+```
+
 ## Theming
 
-Zabi Components uses CSS custom properties for easy theming. You can customize the appearance by overriding these variables:
+Zabi Components uses CSS custom properties and Tailwind CSS for easy theming. You can customize the appearance by overriding these variables:
 
 ```css
 :root {
@@ -308,21 +497,69 @@ interface BaseEventDetail<T = any> {
 
 ## TypeScript Support
 
-Full TypeScript definitions are included with proper event typing:
+Full TypeScript definitions are included with comprehensive type safety:
 
+### Event Types
 ```typescript
-import type { ButtonEvents, InputEvents, CardEvents, AlertEvents } from 'zabi-components';
-
-// Event handlers with proper typing
+import type { 
+  ButtonEvents, 
+  InputEvents, 
+  CardEvents, 
+  FormEvents,
+  NavigationEvents,
+  KeyValueFormEvents 
+} from 'zabi-components';
+
+// Properly typed event handlers
 function handleButtonClick(event: CustomEvent<{ value: boolean; event?: MouseEvent }>) {
   console.log('Button clicked:', event.detail.value);
 }
 
-function handleInputChange(event: CustomEvent<{ value: string; event?: InputEvent }>) {
-  console.log('Input changed:', event.detail.value);
+function handleFormSubmit(event: CustomEvent<{ 
+  data: Record<string, FormDataEntryValue>; 
+  formData: FormData 
+}>) {
+  console.log('Form data:', event.detail.data);
+}
+
+function handleNavigation(event: CustomEvent<{ 
+  item: NavigationItem; 
+  href: string 
+}>) {
+  console.log('Navigate to:', event.detail.href);
+}
+```
+
+### 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;
+}
+
+interface FormProps {
+  method?: "get" | "post";
+  action?: string;
+  className?: string;
 }
 ```
 
+### 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 };
+}>();
+```
+
 ### Event Types
 
 All components use standardized event types:
@@ -481,66 +718,209 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ## Changelog
 
-### v1.0.5 (Latest)
+### v1.0.7 (Latest) - "Less is More" Edition
+
+#### 🎯 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 Package Exports**: Resolved "Package subpath './atoms' is not defined" errors
-- **Fixed Runtime Errors**: Eliminated null reference errors that caused application crashes
-- **Fixed TypeScript Types**: Properly typed event handlers and component props
-- **Fixed Slot Definitions**: Ensured slots work correctly with proper typing
-- **Fixed Main Export**: Ensured zabi-components main import works correctly
-
-#### ✨ Improvements
-- Enhanced TypeScript support with comprehensive event type definitions
-- Improved build configuration for better tree shaking
-- Added proper type generation for all component categories
-- Standardized event structure across all components
-
-#### 📦 Package Structure
-- Added support for subpath imports (`zabi-components/atoms`, `zabi-components/molecules`, etc.)
-- Improved type definitions with proper event interfaces
-- Enhanced build output with proper ES module exports
+- **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
+
+## Development Setup
+
+### Prerequisites
+- Node.js 18+ 
+- npm or yarn
+- Svelte 4+ or SvelteKit 2+
+
+### Local Development
+```bash
+# Clone the repository
+git clone https://github.com/your-username/zabi-components.git
+cd zabi-components
 
-## Troubleshooting
+# Install dependencies
+npm install
 
-### Common Issues
+# Start development server
+npm run dev
 
-#### Import Errors
-If you encounter import errors like "Package subpath './atoms' is not defined", make sure you're using the latest version:
+# Build library
+npm run build
 
-```bash
-npm install zabi-components@latest
+# Run type checking
+npm run check
+
+# Run tests
+npm run test
 ```
 
-#### TypeScript Event Handler Errors
-If you see TypeScript errors with event handlers, make sure to use proper typing:
+### Project Structure
+```
+src/
+├── components/
+│   ├── atoms/          # Basic UI components
+│   ├── molecules/      # Composite components
+│   └── organisms/      # Complex components
+├── types/              # TypeScript definitions
+├── styles/             # CSS and styling
+└── lib/                # Library exports
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### TypeScript Errors
+If you see TypeScript errors with event handlers, ensure proper typing:
 
 ```typescript
-// ✅ Correct
+// ✅ Correct - properly typed event handlers
+function handleClick(event: CustomEvent<{ event: MouseEvent }>) {
+  console.log('Clicked:', event.detail.event);
+}
+
+function handleFormSubmit(event: CustomEvent<{ 
+  data: Record<string, FormDataEntryValue>; 
+  formData: FormData 
+}>) {
+  console.log('Form data:', event.detail.data);
+}
+
+// ❌ Incorrect - missing proper typing
 function handleClick(event: CustomEvent) {
-  console.log(event.detail.value);
+  console.log(event.detail.value); // May cause type errors
 }
+```
+
+#### CSS @apply Warnings
+If you see "Unknown at rule @apply" warnings in your IDE:
 
-// ❌ Incorrect - missing event parameter
-function handleClick() {
-  console.log('clicked');
+1. Install Tailwind CSS IntelliSense extension
+2. Add to your VS Code settings:
+```json
+{
+  "css.customData": [".vscode/tailwind.json"],
+  "tailwindCSS.includeLanguages": {
+    "svelte": "html"
+  }
 }
 ```
 
+#### Import Errors
+If you encounter import errors, ensure you're using the latest version:
+
+```bash
+npm install zabi-components@latest
+```
+
 #### Runtime Errors
 If you encounter runtime errors, ensure you have the correct peer dependencies:
 
 ```bash
-npm install svelte@^5.0.0 @sveltejs/kit@^2.0.0
+npm install svelte@^4.0.0 || ^5.0.0 @sveltejs/kit@^2.0.0
 ```
 
 ### Migration from Previous Versions
 
 If you're upgrading from a previous version, note these changes:
 
-1. **Event Structure**: All events now follow the standardized `{ detail: { value, event? } }` structure
-2. **Import Paths**: Subpath imports are now fully supported (`zabi-components/atoms`, etc.)
+1. **Clean Components**: New Card, Form, Layout, Navigation components
+2. **Event Structure**: All events follow standardized structure
 3. **TypeScript**: Enhanced type definitions with proper event typing
+4. **Modern CSS**: Uses Container Queries, CSS Grid, and logical properties
+
+## Performance & Best Practices
+
+### Performance Optimizations
+- **Tree Shaking**: Import only what you need
+- **CSS Containment**: Components use CSS containment for better performance
+- **Efficient Animations**: Uses `will-change` and `transform` for smooth animations
+- **Lazy Loading**: Components support lazy loading when needed
+
+### Best Practices
+
+#### Component Usage
+```svelte
+<!-- ✅ Good - Use semantic HTML -->
+<Card title="User Profile" interactive on:click={handleClick}>
+  <p>User information</p>
+</Card>
+
+<!-- ❌ Avoid - Unnecessary complexity -->
+<div class="custom-card" on:click={handleClick}>
+  <h3>User Profile</h3>
+  <p>User information</p>
+</div>
+```
+
+#### Event Handling
+```typescript
+// ✅ Good - Proper event typing
+function handleFormSubmit(event: CustomEvent<{ 
+  data: Record<string, FormDataEntryValue>; 
+  formData: FormData 
+}>) {
+  // Handle form submission
+  console.log('Form data:', event.detail.data);
+}
+
+// ❌ Avoid - Untyped events
+function handleFormSubmit(event: any) {
+  console.log(event.detail); // No type safety
+}
+```
+
+#### Styling
+```svelte
+<!-- ✅ Good - Use component props and Tailwind -->
+<Button variant="primary" size="lg" className="w-full">
+  Submit
+</Button>
+
+<!-- ❌ Avoid - Inline styles -->
+<button style="background: blue; width: 100%;">
+  Submit
+</button>
+```
+
+### Accessibility Guidelines
+- Always provide proper labels and ARIA attributes
+- Ensure keyboard navigation works correctly
+- Use semantic HTML elements
+- Test with screen readers
+- Maintain proper color contrast ratios
 
 ## Support
 
@@ -548,4 +928,5 @@ For support, please open an issue on GitHub or contact the maintainers.
 
 ---
 
-Built with ❤️ using Svelte, TypeScript, and Tailwind CSS.
+Built with ❤️ using Svelte, TypeScript, and Tailwind CSS.  
+**Less is more** - Clean components that just work.