zabi-components 5.0.22 → 6.0.0

package/README.md

@@ -1,12 +1,12 @@
 # Zabi Components
 
-A clean, minimal Svelte 5 component library built with TypeScript and Tailwind CSS. **Less is more** - focused on essential components that just work.
+Svelte 5 UI components with TypeScript and Tailwind. Same behavior in the browser and on the server.
 
-> **⚠️ Svelte 5 Required**: This library uses Svelte 5 runes syntax (`$props`, `$derived`, `$state`). Make sure you're using Svelte 5.43.8 or later.
+> **Svelte 5** — Uses runes (`$props`, `$derived`, `$state`). Requires **Svelte 5.43.8** or newer.
 
-## Philosophy
+## Approach
 
-**Clean & Simple**: No unnecessary complexity, just clean components that focus on what matters most. Every component is designed to be intuitive, accessible, and performant. We've simplified everything to use modern CSS and minimal JavaScript.
+Semantic HTML, sensible defaults, and props that stay predictable—especially when you use SSR.
 
 ## Features
 
@@ -46,30 +46,28 @@ Zabi Components includes a comprehensive theme system with Tailwind CSS v4. You
 
 ### Quick Setup
 
-**For projects with existing Tailwind CSS:**
+**Canonical (recommended for Tailwind v4 apps):**
 
 ```css
 /* app.css */
 @import "tailwindcss";
-@import 'zabi-components/theme-only';
-@import 'zabi-components/dist/zabi-components.css';
+@import "zabi-components/theme-only";
+@import "zabi-components/theme-dark-only";
 ```
 
-**For standalone projects (no Tailwind setup):**
+**Alternative (no Tailwind setup):**
 
 ```css
 /* app.css */
-@import 'zabi-components/theme';
-@import 'zabi-components/dist/zabi-components.css';
+@import "zabi-components/colors";
 ```
 
 ### With Dark Mode
 
 ```css
 @import "tailwindcss";
-@import 'zabi-components/theme-only';
-@import 'zabi-components/theme-dark-only'; /* Add dark mode support */
-@import 'zabi-components/dist/zabi-components.css';
+@import "zabi-components/theme-only";
+@import "zabi-components/theme-dark-only"; /* Add dark mode support */
 ```
 
 ### Extending the Theme
@@ -86,10 +84,11 @@ You can extend the theme with custom colors and fonts:
   --color-custom-primary: #ff0000;
 }
 
-@import 'zabi-components/dist/zabi-components.css';
+@import "zabi-components/theme-only";
 ```
 
-> 📖 **Complete Theme Guide**: See [THEME.md](./THEME.md) for comprehensive documentation on theme usage, customization, dark mode, and advanced patterns.
+> 📖 **Complete Theme Guide**: See [THEME.md](./THEME.md) for comprehensive documentation on theme usage, customization, dark mode, and advanced patterns.  
+> **Which CSS file to import** (`theme`, `theme-only`, `colors`, etc.): [docs/theme-imports.md](./docs/theme-imports.md)
 
 ## Import Methods
 
@@ -139,10 +138,7 @@ import {
   Section,
   Tabs
 } from 'zabi-components/molecules';
-import { 
-  Navbar, 
-  Navigation 
-} from 'zabi-components/organisms';
+import { Navbar, SidebarNavigation, SidebarPanel } from 'zabi-components/organisms';
 
 // Import types separately
 import type { ButtonEvents, InputEvents } from 'zabi-components/types';
@@ -162,14 +158,13 @@ import {
 
 ```svelte
 <script lang="ts">
-  // Clean Components - Less is More
   import { 
     Card, 
     CardHeader, 
     CardContent, 
     CardFooter,
     Form, 
-    Navigation, 
+    Navbar, 
     Button, 
     IconButton,
     Input, 
@@ -204,7 +199,7 @@ import {
 <div class="min-h-screen bg-gray-50">
   <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} />
+    <Navbar embedded ariaLabel="Primary" navVariant="header" items={navItems} />
   </header>
 
   <main class="container mx-auto p-6">
@@ -314,7 +309,7 @@ import {
 
 ## Component Overview
 
-### Core Components (Clean & Simple)
+### Core components
 
 | Component | Category | Description | Key Features |
 |-----------|----------|-------------|--------------|
@@ -323,7 +318,6 @@ import {
 | **CardContent** | Atom | Card content section | Compound component for card structure |
 | **CardFooter** | Atom | Card footer section | Compound component for card structure |
 | **Form** | Molecule | Simple form wrapper | FormData handling, clean API |
-| **Navigation** | Organism | Clean navigation | Header/sidebar variants, active state |
 | **Button** | Atom | Action button | 6 variants (primary, secondary, danger, ghost, outline, link) |
 | **IconButton** | Atom | Icon-only button | Icon-only, variants, sizes, accessible label |
 | **Input** | Atom | Form input | Essential props, accessibility, semantic variants |
@@ -332,7 +326,7 @@ import {
 | **Tabs** | Molecule | Tab navigation | Keyboard navigation, 2 variants |
 | **Dropdown** | Molecule | Dropdown menu | CSS-only positioning, keyboard navigation, ARIA support |
 | **ImageUpload** | Molecule | File upload | Direct selection, preview |
-| **Navbar** | Organism | Navigation bar | Mobile menu, responsive |
+| **Navbar** | Organism | Navigation bar | Built-in links or snippets, `embedded` link strip, mobile menu |
 | **NavigationMenu** | Molecule | Advanced navigation menu | Compound components, keyboard navigation |
 | **Section** | Molecule | Content section wrapper | Responsive layout, variant support |
 | **Sidebar** | Molecule | Sidebar navigation | Collapsible, responsive |
@@ -567,26 +561,30 @@ All components will automatically switch to their dark mode variants without any
 - `default`: Main content
 - `footer`: Footer content
 
-### Navigation Component
+### Navbar (built-in links)
+
+Use `items` for a typed link list, or pass a `nav` snippet for custom markup. Set `embedded` when you only need the link row inside your own header.
 
 ```svelte
-<Navigation
-  variant="header" | "sidebar"
-  items={Array<{label: string, href: string, icon?: any}>}
-  currentPath={string}
-  className={string}
-  on:click={(e) => console.log('Navigation clicked')}
+<Navbar
+  brand="My App"
+  brandHref="/"
+  items={navItems}
+  navVariant="header"
+  currentPath="/about"
+  onclick={(e) => console.log('Nav link', e)}
 />
-```
 
-**Props:**
-- `variant`: Navigation type (default: "header")
-- `items`: Navigation items array
-- `currentPath`: Current active path
-- `className`: Additional CSS classes
+<Navbar embedded ariaLabel="Primary" navVariant="header" items={navItems} />
+```
 
-**Events:**
-- `click`: Native click event on navigation items
+**Props (selected):**
+- `items`: `NavbarNavItem[]` — `label`, `href`, optional `icon` / `iconFilled`
+- `navVariant`: `"header"` | `"sidebar"` — layout for built-in links
+- `embedded`: render link list (or `nav` snippet) without full chrome
+- `currentPath`: active item for built-in links
+- `preventNavigation`: call `preventDefault` on link clicks
+- `onclick`: invoked when a built-in link is clicked
 
 ### NavigationMenu Component
 
@@ -1336,7 +1334,7 @@ This is a **major breaking change** that affects how all components handle event
 
 See the [Migration Guide](#migration-from-previous-versions) above for detailed examples.
 
-### v2.0.2 - "Less is More" Edition
+### v2.0.2 — streamlined components
 
 ## Development Setup
 
@@ -1575,9 +1573,8 @@ See [VARIANTS.md](./docs/VARIANTS.md) for complete variant documentation.
 
 ## Support
 
-For support, please open an issue on GitHub or contact the maintainers.
+Questions or bugs? [Open an issue on GitHub](https://github.com/sabnor/zabi-components/issues).
 
 ---
 
-Built with ❤️ using Svelte, TypeScript, and Tailwind CSS.  
-**Less is more** - Clean components that just work.
+MIT license · Svelte, TypeScript, and Tailwind CSS

package/THEME.md

@@ -0,0 +1,473 @@
+# Zabi Components Theme Guide
+
+Complete guide to using and customizing the Zabi Components theme system with Tailwind CSS v4.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Theme Files](#theme-files)
+- [Import Options](#import-options)
+- [Theme Extension](#theme-extension)
+- [Dark Mode](#dark-mode)
+- [Color System](#color-system)
+- [Customization Examples](#customization-examples)
+- [Common Pitfalls](#common-pitfalls)
+
+## Quick Start
+
+### Basic Setup (Standalone)
+
+If you don't have Tailwind CSS set up yet:
+
+```css
+/* app.css */
+@import 'zabi-components/theme';
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+### Setup with Existing Tailwind
+
+If you already have Tailwind CSS configured:
+
+```css
+/* app.css */
+@import "tailwindcss";
+@import 'zabi-components/theme-only';
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+### With Dark Mode
+
+```css
+/* app.css */
+@import "tailwindcss";
+@import 'zabi-components/theme-only';
+@import 'zabi-components/theme-dark-only';
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+## Theme Files
+
+Zabi Components provides multiple theme file variants:
+
+| File | Description | Use Case |
+|------|-------------|----------|
+| `zabi-components/theme` | Full theme with Tailwind import | Standalone projects |
+| `zabi-components/theme-only` | Theme without Tailwind import | Projects with existing Tailwind |
+| `zabi-components/theme-dark` | Dark mode with Tailwind import | Standalone + dark mode |
+| `zabi-components/theme-dark-only` | Dark mode without Tailwind import | Existing Tailwind + dark mode |
+
+### Direct Path Imports
+
+You can also import using direct paths:
+
+```css
+@import 'zabi-components/dist/zabi-components-theme.css';
+@import 'zabi-components/dist/zabi-components-theme-only.css';
+@import 'zabi-components/dist/zabi-components-theme-dark.css';
+@import 'zabi-components/dist/zabi-components-theme-dark-only.css';
+```
+
+## Import Options
+
+### Option 1: Standalone (No Existing Tailwind)
+
+Best for new projects or projects without Tailwind:
+
+```css
+@import 'zabi-components/theme';
+@import 'zabi-components/theme-dark'; /* Optional: for dark mode */
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+**Pros:**
+- Simple setup
+- No Tailwind configuration needed
+- Everything included
+
+**Cons:**
+- Less control over Tailwind configuration
+- Slightly larger bundle if you need custom Tailwind config
+
+### Option 2: With Existing Tailwind
+
+Best for projects already using Tailwind CSS:
+
+```css
+@import "tailwindcss";
+@import 'zabi-components/theme-only';
+@import 'zabi-components/theme-dark-only'; /* Optional: for dark mode */
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+**Pros:**
+- Full control over Tailwind configuration
+- Can customize Tailwind before importing theme
+- Smaller bundle (no duplicate Tailwind import)
+
+**Cons:**
+- Requires Tailwind setup
+- Must import Tailwind first
+
+## Theme Extension
+
+You can extend the Zabi theme with your own customizations using additional `@theme` blocks:
+
+```css
+@import "tailwindcss";
+@import 'zabi-components/theme-only';
+
+/* Your custom theme extensions */
+@theme {
+  /* Custom font families */
+  --font-family-title: 'Your Font', sans-serif;
+  --font-family-body: 'Another Font', sans-serif;
+  
+  /* Custom colors */
+  --color-custom-primary: #ff0000;
+  --color-custom-secondary: #00ff00;
+}
+
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+### Important: Import Order
+
+The import order is critical:
+
+1. **First:** `@import "tailwindcss"` (if using theme-only)
+2. **Second:** `@import 'zabi-components/theme-only'` (or theme)
+3. **Third:** Your custom `@theme` block (extends zabi theme)
+4. **Fourth:** `@import 'zabi-components/dist/zabi-components.css'` (uses the theme)
+
+This order ensures:
+- Tailwind is available for `theme()` function calls
+- Zabi theme is defined first
+- Your extensions override zabi defaults
+- Components can use all theme values
+
+## Dark Mode
+
+Zabi Components supports dark mode through CSS custom properties in the `.dark` class.
+
+### Automatic Dark Mode (System Preference)
+
+```css
+@import "tailwindcss";
+@import 'zabi-components/theme-only';
+@import 'zabi-components/theme-dark-only'; /* Supports system preference */
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+The dark theme file uses `@media (prefers-color-scheme: dark)` to automatically switch based on system preference.
+
+### Manual Dark Mode Toggle
+
+For manual dark mode toggling, add the `.dark` class to your HTML element:
+
+```javascript
+// Toggle dark mode
+document.documentElement.classList.toggle('dark');
+```
+
+The dark theme file also includes `.dark` class support, so both system preference and manual toggle work.
+
+### Custom Dark Mode Colors
+
+You can override dark mode colors in your custom theme:
+
+```css
+@import "tailwindcss";
+@import 'zabi-components/theme-only';
+@import 'zabi-components/theme-dark-only';
+
+@theme {
+  /* Your light mode customizations */
+  --color-custom: #ff0000;
+}
+
+/* Custom dark mode overrides */
+.dark {
+  --color-custom: #ff6666; /* Lighter red for dark mode */
+}
+
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+## Color System
+
+Zabi Components uses a semantic color system with the following color scales:
+
+### Color Scales
+
+- **Brand** - Primary brand colors (blue palette)
+- **Citron** - Energetic/yellow colors
+- **Pine** - Success/green colors
+- **Iris** - Info/purple colors
+
+Each scale includes shades from 50 (lightest) to 950 (darkest).
+
+### Semantic Colors
+
+Semantic colors map to specific use cases:
+
+- `--color-background` - Main background
+- `--color-headline` - Headings and titles
+- `--color-body` - Body text
+- `--color-description` - Secondary/description text
+- `--color-caption` - Captions and labels
+- `--color-border` - Borders and dividers
+- `--color-surface-elevated` - Elevated surfaces (cards, modals)
+- `--color-surface-level-0/1/2` - Surface hierarchy
+- `--color-primary` - Primary actions
+- `--color-secondary` - Secondary actions
+- `--color-success` - Success states
+- `--color-warning` - Warning states
+- `--color-error` - Error states
+
+### Using Colors
+
+#### In CSS
+
+```css
+.my-element {
+  background-color: var(--color-primary);
+  color: var(--color-headline);
+}
+```
+
+#### In Tailwind Classes
+
+Zabi Components provides utility classes:
+
+```html
+<div class="bg-primary text-headline">
+  Primary background with headline text
+</div>
+```
+
+#### In Tailwind theme() Function
+
+```css
+.custom-class {
+  color: theme(colors.brand.600);
+  background: theme(colors.surface.elevated);
+}
+```
+
+## Customization Examples
+
+### Example 1: Custom Brand Colors
+
+```css
+@import "tailwindcss";
+@import 'zabi-components/theme-only';
+
+
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+### Example 2: Custom Fonts
+
+```css
+@import "tailwindcss";
+@import 'zabi-components/theme-only';
+
+@theme {
+  --font-family-title: 'Inter', 'Helvetica', sans-serif;
+  --font-family-body: 'Inter', 'Helvetica', sans-serif;
+  --font-family-sans: 'Inter', ui-sans-serif, system-ui, sans-serif;
+}
+
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+### Example 3: Custom Semantic Colors
+
+```css
+@import "tailwindcss";
+@import 'zabi-components/theme-only';
+
+@theme {
+  /* Custom primary color */
+  --color-primary: theme(colors.purple.600);
+  --color-primary-weak: theme(colors.purple.700);
+  --color-primary-medium: theme(colors.purple.800);
+  --color-primary-strong: theme(colors.purple.900);
+}
+
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+### Example 4: Multiple Theme Variants
+
+```css
+@import "tailwindcss";
+@import 'zabi-components/theme-only';
+
+/* Default theme */
+@theme {
+  --color-primary: theme(colors.blue.600);
+}
+
+/* Custom variant */
+.variant-custom {
+  --color-primary: theme(colors.purple.600);
+  --color-secondary: theme(colors.pink.600);
+}
+
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+## Common Pitfalls
+
+### Pitfall 1: Wrong Import Order
+
+**Wrong:**
+```css
+@import 'zabi-components/dist/zabi-components.css';
+@import 'zabi-components/theme-only'; /* Too late! */
+```
+
+**Correct:**
+```css
+@import "tailwindcss";
+@import 'zabi-components/theme-only';
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+### Pitfall 2: Double Tailwind Import
+
+**Wrong:**
+```css
+@import "tailwindcss";
+@import 'zabi-components/theme'; /* This also imports Tailwind! */
+```
+
+**Correct:**
+```css
+@import "tailwindcss";
+@import 'zabi-components/theme-only'; /* Use theme-only */
+```
+
+### Pitfall 3: Theme Extension After Components
+
+**Wrong:**
+```css
+@import 'zabi-components/theme-only';
+@import 'zabi-components/dist/zabi-components.css';
+@theme { /* Too late! */ }
+```
+
+**Correct:**
+```css
+@import "tailwindcss";
+@import 'zabi-components/theme-only';
+@theme { /* Extend before components */ }
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+### Pitfall 4: Missing Dark Mode Import
+
+If you want dark mode support, you must import the dark theme file:
+
+```css
+@import "tailwindcss";
+@import 'zabi-components/theme-only';
+@import 'zabi-components/theme-dark-only'; /* Don't forget this! */
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+### Pitfall 5: Using theme() Before Theme is Defined
+
+**Wrong:**
+```css
+@theme {
+  --color-custom: theme(colors.brand.600); /* Works */
+  --color-other: theme(colors.custom.500); /* Fails - custom not defined yet */
+}
+```
+
+**Correct:**
+```css
+@theme {
+  --color-custom: theme(colors.brand.600);
+  /* Define custom colors first, then reference them */
+  --color-custom-500: #ff0000;
+  --color-other: var(--color-custom-500); /* Use var() for custom colors */
+}
+```
+
+## Troubleshooting
+
+### Theme Variables Not Working
+
+1. Check import order (theme must come before components CSS)
+2. Verify you're using the correct theme file variant
+3. Ensure Tailwind is imported if using `theme-only`
+4. Check browser console for CSS errors
+
+### Dark Mode Not Working
+
+1. Ensure dark theme file is imported
+2. Check that `.dark` class is applied to `<html>` or root element
+3. Verify system preference detection (if using automatic mode)
+4. Check that dark mode CSS custom properties are defined
+
+### Colors Not Updating
+
+1. Clear browser cache
+2. Restart dev server
+3. Check for CSS specificity issues
+4. Verify theme extension is after zabi theme import
+
+## Advanced Usage
+
+### Programmatic Theme Switching
+
+```javascript
+// Switch to dark mode
+document.documentElement.classList.add('dark');
+
+// Switch to light mode
+document.documentElement.classList.remove('dark');
+
+// Toggle
+document.documentElement.classList.toggle('dark');
+```
+
+### Theme with Svelte
+
+```svelte
+<script>
+  import { onMount } from 'svelte';
+  
+  let isDark = $state(false);
+  
+  onMount(() => {
+    // Check system preference
+    const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+    isDark = prefersDark;
+    updateTheme();
+  });
+  
+  function updateTheme() {
+    if (isDark) {
+      document.documentElement.classList.add('dark');
+    } else {
+      document.documentElement.classList.remove('dark');
+    }
+  }
+</script>
+
+<button on:click={() => { isDark = !isDark; updateTheme(); }}>
+  Toggle Theme
+</button>
+```
+
+## Additional Resources
+
+- [Tailwind CSS v4 Documentation](https://tailwindcss.com/docs)
+- [CSS Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)
+- [Zabi Components GitHub](https://github.com/zabi-components/zabi-components)
+