@mhmo91/schmancy 0.8.6 → 0.9.3

package/dist/ai/nav-drawer.md

@@ -1,206 +1,52 @@
-# Navigation Drawer Component
+# schmancy-nav-drawer
 
-A responsive navigation drawer system that adapts between overlay and push modes based on screen size, providing flexible app navigation patterns.
-
-## Quick Start
+> Responsive navigation drawer that switches between push (desktop) and overlay (mobile) modes.
 
+## Usage
 ```html
-<!-- Basic navigation drawer -->
-<schmancy-nav-drawer>
+<schmancy-nav-drawer breakpoint="md">
   <schmancy-nav-drawer-navbar>
-    <nav>
-      <schmancy-list>
-        <schmancy-list-item>Dashboard</schmancy-list-item>
-        <schmancy-list-item>Settings</schmancy-list-item>
-      </schmancy-list>
-    </nav>
+    <!-- Navigation rail or sidebar content -->
   </schmancy-nav-drawer-navbar>
-  
   <schmancy-nav-drawer-content>
-    <schmancy-nav-drawer-appbar>
-      <h1>My App</h1>
-    </schmancy-nav-drawer-appbar>
-    <main>
-      <!-- Page content -->
-    </main>
+    <!-- Main content area -->
   </schmancy-nav-drawer-content>
 </schmancy-nav-drawer>
 ```
 
-## Components
-
-### schmancy-nav-drawer
-The root container that manages drawer state and responsive behavior.
-
-**Properties:**
+## Properties (schmancy-nav-drawer)
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `fullscreen` | `boolean` | `false` | Hide drawer in fullscreen mode |
-| `breakpoint` | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Responsive breakpoint |
-| `open` | `'open' \| 'close'` | - | Drawer state |
-
-### schmancy-nav-drawer-navbar
-The navigation sidebar component.
-
-**Properties:**
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `width` | `string` | `'320px'` | Drawer width |
-
-### schmancy-nav-drawer-content
-Container for main content area.
-
-### schmancy-nav-drawer-appbar
-Optional app bar for the content area.
+| breakpoint | `'sm'\|'md'\|'lg'\|'xl'` | `'md'` | Responsive breakpoint for push/overlay switch |
+| open | `'open'\|'close'` | auto | Drawer state |
+| fullscreen | boolean | `false` | Fullscreen mode (hides sidebar) |
+
+## Child Components
+| Component | Description |
+|-----------|-------------|
+| `schmancy-nav-drawer-navbar` | Sidebar container (auto-hides in overlay mode) |
+| `schmancy-nav-drawer-content` | Main content area (fills remaining space) |
+
+## Behavior
+- Above breakpoint: push mode (sidebar pushes content)
+- Below breakpoint: overlay mode (sidebar overlays content)
+- Toggle via `SchmancyEvents.NavDrawer_toggle` event
+- Grid layout: `auto 1fr` columns
 
 ## Examples
-
-### Complete App Layout
 ```html
 <schmancy-nav-drawer breakpoint="lg">
-  <!-- Navigation Sidebar -->
-  <schmancy-nav-drawer-navbar width="280px">
-    <div class="p-4">
-      <h2 class="text-xl font-bold mb-4">My App</h2>
-    </div>
-    
-    <schmancy-list>
-      <schmancy-list-item @click="${() => navigate('/dashboard')}">
-        <schmancy-icon slot="start">dashboard</schmancy-icon>
-        Dashboard
-      </schmancy-list-item>
-      
-      <schmancy-list-item @click="${() => navigate('/users')}">
-        <schmancy-icon slot="start">people</schmancy-icon>
-        Users
-      </schmancy-list-item>
-      
-      <schmancy-divider class="my-2"></schmancy-divider>
-      
-      <schmancy-list-item @click="${() => navigate('/settings')}">
-        <schmancy-icon slot="start">settings</schmancy-icon>
-        Settings
-      </schmancy-list-item>
-    </schmancy-list>
-  </schmancy-nav-drawer-navbar>
-  
-  <!-- Main Content -->
-  <schmancy-nav-drawer-content>
-    <!-- App Bar -->
-    <schmancy-nav-drawer-appbar>
-      <schmancy-icon-button @click="${toggleDrawer}">
-        menu
-      </schmancy-icon-button>
-      <h1 class="text-xl">Dashboard</h1>
-    </schmancy-nav-drawer-appbar>
-    
-    <!-- Page Content -->
-    <main class="p-4">
-      <router-outlet></router-outlet>
-    </main>
-  </schmancy-nav-drawer-content>
-</schmancy-nav-drawer>
-```
-
-### With User Profile
-```html
-<schmancy-nav-drawer>
   <schmancy-nav-drawer-navbar>
-    <!-- User Profile Section -->
-    <div class="p-4 border-b">
-      <schmancy-avatar 
-        src="/user-avatar.jpg" 
-        name="John Doe"
-      ></schmancy-avatar>
-      <div class="mt-2">
-        <div class="font-medium">John Doe</div>
-        <div class="text-sm opacity-70">john@example.com</div>
-      </div>
-    </div>
-    
-    <!-- Navigation -->
-    <schmancy-list class="py-2">
-      <!-- Menu items -->
-    </schmancy-list>
+    <schmancy-navigation-rail activeIndex="0">
+      <schmancy-navigation-rail-item icon="home" label="Home">
+      </schmancy-navigation-rail-item>
+    </schmancy-navigation-rail>
   </schmancy-nav-drawer-navbar>
-  
   <schmancy-nav-drawer-content>
-    <!-- Content -->
+    <schmancy-area name="main" default="home-page">
+      <schmancy-route when="home-page" .component=${lazy(() => import('./home'))}>
+      </schmancy-route>
+    </schmancy-area>
   </schmancy-nav-drawer-content>
 </schmancy-nav-drawer>
 ```
-
-## Features
-
-### Responsive Modes
-- **Push Mode**: Drawer pushes content (desktop)
-- **Overlay Mode**: Drawer overlays content (mobile)
-- Automatic switching based on breakpoint
-
-### Breakpoint Values
-- `sm`: 640px
-- `md`: 768px (default)
-- `lg`: 1024px
-- `xl`: 1280px
-
-### Events
-Toggle drawer programmatically:
-```javascript
-window.dispatchEvent(
-  new CustomEvent('schmancy-nav-drawer-toggle', {
-    detail: { state: 'open' } // or 'close'
-  })
-);
-```
-
-### Animation
-Smooth transitions with customizable easing:
-- Overlay fade: 200ms open, 150ms close
-- Drawer slide: 200ms
-- Cubic bezier easing for natural motion
-
-## Styling
-
-```css
-/* Custom drawer styling */
-schmancy-nav-drawer-navbar {
-  --drawer-width: 320px;
-  --animation-duration: 200ms;
-}
-
-/* Overlay customization */
-schmancy-nav-drawer {
-  --overlay-opacity: 0.4;
-  --overlay-color: var(--schmancy-sys-color-scrim);
-}
-```
-
-## Context System
-
-The component uses Lit Context API for state management:
-- `SchmancyDrawerNavbarMode`: Current mode (push/overlay)
-- `SchmancyDrawerNavbarState`: Open/close state
-
-## Best Practices
-
-1. **Navigation Structure**: Keep navigation hierarchy shallow
-2. **Mobile First**: Design for overlay mode first
-3. **Breakpoints**: Choose breakpoints based on content
-4. **Performance**: Use `fullscreen` prop for immersive experiences
-5. **Accessibility**: Include proper ARIA labels
-
-## Related Components
-
-- [List](./list.md) - Navigation menu items
-- [Icon](./icons.md) - Menu icons
-- [Avatar](./avatar.md) - User profiles
-- [Surface](./surface.md) - Content containers
-- [Button](./button.md) - Navigation triggers
-
-## Use Cases
-
-1. **Admin Dashboards**: Multi-section navigation
-2. **Mobile Apps**: Responsive app shells
-3. **Documentation Sites**: Side navigation
-4. **E-commerce**: Category navigation
-5. **Social Apps**: User navigation with profiles

package/dist/ai/navigation-bar.md

@@ -1,205 +1,48 @@
-# Navigation Bar Component
+# schmancy-navigation-bar
 
-## Overview
-The `<schmancy-navigation-bar>` component is a Material Design 3 compliant horizontal navigation component that provides access to 3-7 primary destinations in your application. It's typically fixed at the bottom of the viewport and follows M3 specifications with proper elevation, touch targets, and responsive behavior.
-
-**Z-Index**: The component includes `z-10` by default (consistent with `schmancy-navigation-rail`), ensuring it layers correctly below overlay components like sheets and dialogs.
+> Horizontal bottom navigation bar for mobile with 3-7 destinations, auto-hide on scroll, and fullscreen support.
 
 ## Usage
-
-### Fixed at Bottom (Typical Usage)
 ```html
 <schmancy-navigation-bar activeIndex="0" class="fixed bottom-0 left-0 right-0">
   <schmancy-navigation-bar-item icon="home" label="Home"></schmancy-navigation-bar-item>
   <schmancy-navigation-bar-item icon="search" label="Search"></schmancy-navigation-bar-item>
-  <schmancy-navigation-bar-item icon="favorite" label="Favorites"></schmancy-navigation-bar-item>
-  <schmancy-navigation-bar-item icon="settings" label="Settings"></schmancy-navigation-bar-item>
-</schmancy-navigation-bar>
-```
-
-**Note**: The component includes `z-10` by default. You only need to add positioning classes like `fixed bottom-0 left-0 right-0`.
-
-### Within a Container
-```html
-<schmancy-navigation-bar activeIndex="0">
-  <schmancy-navigation-bar-item icon="home" label="Home"></schmancy-navigation-bar-item>
-  <schmancy-navigation-bar-item icon="search" label="Search"></schmancy-navigation-bar-item>
-  <schmancy-navigation-bar-item icon="favorite" label="Favorites"></schmancy-navigation-bar-item>
   <schmancy-navigation-bar-item icon="settings" label="Settings"></schmancy-navigation-bar-item>
 </schmancy-navigation-bar>
 ```
 
-### With Hide on Scroll
-```html
-<schmancy-navigation-bar activeIndex="0" hideOnScroll>
-  <schmancy-navigation-bar-item icon="dashboard" label="Dashboard"></schmancy-navigation-bar-item>
-  <schmancy-navigation-bar-item icon="shopping_cart" label="Orders"></schmancy-navigation-bar-item>
-  <schmancy-navigation-bar-item icon="inventory" label="Products"></schmancy-navigation-bar-item>
-</schmancy-navigation-bar>
-```
-
-### With Badges
-```html
-<schmancy-navigation-bar>
-  <schmancy-navigation-bar-item icon="home" label="Home"></schmancy-navigation-bar-item>
-  <schmancy-navigation-bar-item icon="notifications" label="Alerts" badge="3"></schmancy-navigation-bar-item>
-  <schmancy-navigation-bar-item icon="mail" label="Messages" badge="99+"></schmancy-navigation-bar-item>
-</schmancy-navigation-bar>
-```
-
-### Fullscreen Mode Support
-The navigation bar automatically hides in fullscreen mode when triggered via the theme service:
-
-```javascript
-import { schmancyTheme } from '@schmancy/theme';
-
-// Enter fullscreen mode (hides navigation bar)
-schmancyTheme.next({ fullscreen: true });
-
-// Exit fullscreen mode (shows navigation bar)
-schmancyTheme.next({ fullscreen: false });
-
-// Toggle fullscreen mode
-schmancyTheme.toggleFullscreen();
-```
-
-## Properties
-
+## Properties (schmancy-navigation-bar)
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `activeIndex` | `number` | `-1` | Currently active item index (zero-based) |
-| `hideLabels` | `boolean` | `false` | Hide labels and show only icons |
-| `elevation` | `number` | `2` | Elevation level for the navigation bar (0-5) |
-| `hideOnScroll` | `boolean` | `false` | Automatically hide bar when scrolling down, show when scrolling up |
+| activeIndex | number | `-1` | Currently active item index |
+| hideLabels | boolean | `false` | Hide labels, show only icons |
+| elevation | number (0-5) | `2` | Shadow elevation |
+| hideOnScroll | boolean | `false` | Auto-hide on scroll down |
 
+## Properties (schmancy-navigation-bar-item)
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| icon | string | `''` | Material Symbols icon name |
+| label | string | `''` | Item label text |
+| badge | string | `''` | Badge content (number or text) |
+| active | boolean | `false` | Whether this item is active |
+| disabled | boolean | `false` | Whether this item is disabled |
+| hideLabels | boolean | `false` | Whether to hide the label |
 
 ## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| navigation-change | `{ oldIndex, newIndex, item }` | When active item changes |
 
-### navigation-change
-Fired when an item is selected.
-
-```javascript
-navigationBar.addEventListener('navigation-change', (event) => {
-  console.log('Old index:', event.detail.oldIndex);
-  console.log('New index:', event.detail.newIndex);
-  console.log('Selected item:', event.detail.item);
-});
-```
-
-
-## Features
-
-### Reactive State Management
-The component uses RxJS BehaviorSubjects for reactive state management, ensuring smooth and predictable state updates across all navigation items.
-
-### Hide on Scroll Behavior
-When `hideOnScroll` is enabled:
-- Navigation bar hides when scrolling down to maximize content space
-- Shows automatically when scrolling up for quick access
-- Uses smooth CSS transforms for GPU-accelerated animations
-- Implements a 10px scroll threshold to prevent jittery behavior
-- Always visible when near the top of the page
-
-### Visibility Control
-The navigation bar provides comprehensive visibility control:
-- **Manual Control**: Use `hide()`, `show()`, or `toggleVisibility()` methods
-- **Fullscreen Support**: Hide the navigation bar for immersive experiences
-- **Event-driven**: Listen to `visibility-change` events to react to visibility changes
-- **Smooth Transitions**: All visibility changes use smooth animations (300ms cubic-bezier)
-- **ARIA Compliance**: Automatically updates `aria-hidden` attribute
-- **Independent Controls**: `hidden` property works independently of scroll-based hiding
-
-### Keyboard Navigation
-Full keyboard support for accessibility:
-- `ArrowLeft` / `ArrowRight` - Navigate between items
-- `Home` / `End` - Jump to first/last item
-- `Enter` / `Space` - Activate focused item
-- Proper focus management with `tabindex`
-
-### Material Design 3 Compliance
-- Fixed 80px height as per M3 specifications
-- 48x48dp minimum touch targets
-- Proper elevation and shadow system
-- Responsive item distribution (3-7 items)
-- Surface container background color
-
-## Styling
-
-### CSS Variables
-The component respects the Schmancy theme system:
-- Background: `SchmancyTheme.sys.color.surface.container`
-- Text: `SchmancyTheme.sys.color.surface.on`
-
-### Custom Z-Index
-The component includes `z-10` by default. If you need a different z-index value, you can override it:
+## Examples
 ```html
-<schmancy-navigation-bar class="!z-20">
-  <!-- items -->
+<!-- With badges and scroll-hide -->
+<schmancy-navigation-bar activeIndex="0" hideOnScroll>
+  <schmancy-navigation-bar-item icon="inbox" label="Inbox" badge="5">
+  </schmancy-navigation-bar-item>
+  <schmancy-navigation-bar-item icon="favorite" label="Favorites">
+  </schmancy-navigation-bar-item>
 </schmancy-navigation-bar>
 ```
 
-**Note**: The default `z-10` ensures the navigation bar appears below overlay components (sheets at `z-999`, dialogs, etc.) while remaining above regular content.
-
-## Integration with schmancy-area
-
-### Route-based Navigation
-```typescript
-@customElement('my-app')
-class MyApp extends LitElement {
-  private handleNavigation = (e: CustomEvent) => {
-    const routes = ['dashboard', 'orders', 'products', 'settings'];
-    const route = routes[e.detail.newIndex];
-
-    // Navigate using schmancy-area
-    area.push({
-      component: route,
-      area: 'main'
-    });
-  }
-
-  render() {
-    return html`
-      <schmancy-navigation-bar
-        @navigation-change=${this.handleNavigation}
-        activeIndex="0"
-      >
-        <schmancy-navigation-bar-item icon="dashboard" label="Dashboard"></schmancy-navigation-bar-item>
-        <schmancy-navigation-bar-item icon="shopping_cart" label="Orders"></schmancy-navigation-bar-item>
-        <schmancy-navigation-bar-item icon="inventory" label="Products"></schmancy-navigation-bar-item>
-        <schmancy-navigation-bar-item icon="settings" label="Settings"></schmancy-navigation-bar-item>
-      </schmancy-navigation-bar>
-
-      <schmancy-area name="main" default="dashboard">
-        <schmancy-route when="dashboard" component="app-dashboard"></schmancy-route>
-        <schmancy-route when="orders" component="app-orders"></schmancy-route>
-        <schmancy-route when="products" component="app-products"></schmancy-route>
-        <schmancy-route when="settings" component="app-settings"></schmancy-route>
-      </schmancy-area>
-    `;
-  }
-}
-```
-
-## Best Practices
-
-1. **Item Count**: Use between 3-7 items for optimal usability
-2. **Labels**: Keep labels short (1-2 words) for better readability
-3. **Icons**: Use Material Symbols Outlined icons for consistency
-4. **Active State**: Always maintain an active state for user orientation
-5. **Scroll Behavior**: Enable `hideOnScroll` for content-heavy pages
-6. **Badges**: Use sparingly for important notifications only
-
-## Accessibility
-
-- ARIA roles and labels properly set
-- Keyboard navigation fully supported
-- Focus indicators for keyboard users
-- `aria-pressed` attribute on active items
-- `aria-hidden` when navigation is hidden on scroll
-
-## Performance Notes
-
-- Efficient event handling with automatic cleanup
-- Scroll events are throttled at 100ms intervals to prevent performance issues
-- CSS transforms for smooth GPU-accelerated animations
-- Lazy subscription setup for scroll listeners only when needed
+Automatically hides in fullscreen mode. Consumer must position the bar (e.g., `class="fixed bottom-0 left-0 right-0"`).