@mhmo91/schmancy 0.5.18 → 0.5.19

package/ai/navigation-bar-item.md

@@ -0,0 +1,247 @@
+# Navigation Bar Item Component
+
+## Overview
+The `<schmancy-navigation-bar-item>` component represents an individual navigation destination within a navigation bar. It follows Material Design 3 specifications with proper touch targets, ripple effects, and state management using RxJS observables.
+
+## Usage
+
+### Basic Example
+```html
+<schmancy-navigation-bar-item
+  icon="home"
+  label="Home"
+  active
+></schmancy-navigation-bar-item>
+```
+
+### With Badge
+```html
+<schmancy-navigation-bar-item
+  icon="notifications"
+  label="Alerts"
+  badge="5"
+></schmancy-navigation-bar-item>
+```
+
+### Custom Icon Slot
+```html
+<schmancy-navigation-bar-item label="Custom">
+  <span slot="icon">🏠</span>
+</schmancy-navigation-bar-item>
+```
+
+### With Custom Content
+```html
+<schmancy-navigation-bar-item>
+  <schmancy-icon slot="icon" size="24">favorite</schmancy-icon>
+  Custom Content
+</schmancy-navigation-bar-item>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `icon` | `string` | `''` | Material Symbols Outlined icon name |
+| `label` | `string` | `''` | Label text for the navigation item |
+| `badge` | `string` | `''` | Badge content (number or short text) |
+| `active` | `boolean` | `false` | Whether this item is currently active/selected |
+| `disabled` | `boolean` | `false` | Whether this item is disabled |
+| `hideLabels` | `boolean` | `false` | Hide labels (controlled by parent navigation bar) |
+
+## Events
+
+### bar-item-click
+Fired when the item is clicked (with 300ms debounce to prevent accidental double-clicks).
+
+```javascript
+item.addEventListener('bar-item-click', (event) => {
+  console.log('Icon:', event.detail.icon);
+  console.log('Label:', event.detail.label);
+  console.log('Active:', event.detail.active);
+});
+```
+
+### focus / blur
+Standard focus and blur events for accessibility.
+
+## Features
+
+### RxJS-Powered Interactions
+- **Click handling**: Uses RxJS observables with 300ms debounce for navigation events
+- **Ripple effects**: Immediate visual feedback without debounce
+- **Keyboard support**: Enter and Space keys properly handled with same debounce
+- **State management**: BehaviorSubject for reactive active state updates
+
+### Full Clickable Area
+The entire navigation item is clickable, not just the icon area:
+- Better touch targets on mobile devices
+- Improved accessibility
+- More intuitive user experience
+- 48x48dp minimum touch target as per Material Design
+
+### Badge System
+Intelligent badge handling:
+- Numbers > 99 display as "99+"
+- Text badges limited to 3 characters
+- Zero values hide the badge
+- Proper ARIA labels for screen readers
+
+### Ripple Animation
+Material Design ripple effect:
+- Originates from click position
+- 600ms animation duration
+- GPU-accelerated CSS animations
+- Multiple concurrent ripples supported
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `icon` | Custom icon content to replace the default icon |
+| default | Custom content for the item |
+
+## Styling
+
+### State-based Styling
+The component automatically applies different styles based on state:
+
+```css
+/* Active state */
+schmancy-navigation-bar-item[active] {
+  /* Icon indicator background: secondary-container */
+  /* Text color: secondary-onContainer */
+}
+
+/* Inactive state */
+schmancy-navigation-bar-item:not([active]) {
+  /* Text color: surface-onVariant */
+  /* Hover background: surface-container-highest */
+}
+
+/* Disabled state */
+schmancy-navigation-bar-item[disabled] {
+  /* Opacity: 0.38 */
+  /* Pointer events disabled */
+}
+```
+
+### CSS Parts
+```css
+/* Style the button element */
+schmancy-navigation-bar-item::part(button) {
+  /* Custom button styles */
+}
+```
+
+## Methods
+
+### setActive(isActive: boolean)
+Programmatically set the active state of the item.
+
+```javascript
+const item = document.querySelector('schmancy-navigation-bar-item');
+item.setActive(true); // Activate the item
+```
+
+## Integration Example
+
+### Complete Navigation Setup
+```typescript
+@customElement('app-navigation')
+class AppNavigation extends LitElement {
+  @state() activeIndex = 0;
+
+  private navigationItems = [
+    { icon: 'home', label: 'Home', route: 'home' },
+    { icon: 'search', label: 'Search', route: 'search' },
+    { icon: 'favorite', label: 'Favorites', route: 'favorites', badge: '3' },
+    { icon: 'person', label: 'Profile', route: 'profile' }
+  ];
+
+  private handleItemClick = (e: CustomEvent, index: number) => {
+    this.activeIndex = index;
+    const route = this.navigationItems[index].route;
+
+    // Navigate to route
+    area.push({
+      component: route,
+      area: 'main'
+    });
+  }
+
+  render() {
+    return html`
+      ${this.navigationItems.map((item, index) => html`
+        <schmancy-navigation-bar-item
+          icon=${item.icon}
+          label=${item.label}
+          ?active=${this.activeIndex === index}
+          badge=${item.badge || ''}
+          @bar-item-click=${(e: CustomEvent) => this.handleItemClick(e, index)}
+        ></schmancy-navigation-bar-item>
+      `)}
+    `;
+  }
+}
+```
+
+## Accessibility
+
+### Keyboard Support
+- `Enter` / `Space` - Activate the item (with 300ms debounce)
+- Full focus management with visual indicators
+- `aria-pressed` attribute reflects active state
+- `aria-label` for badge notifications
+
+### Screen Reader Support
+- Proper ARIA attributes
+- Semantic HTML structure
+- Badge announcements ("3 notifications")
+
+## Performance Optimization
+
+### RxJS Observables
+- Efficient event handling with proper cleanup
+- Debounced navigation events (300ms) prevent double-clicks
+- Immediate ripple feedback for better UX
+- Memory-safe with `takeUntil(this.disconnecting)`
+
+### Rendering Optimization
+- Conditional rendering based on props
+- Efficient class mapping with TailwindElement
+- Shadow DOM for style encapsulation
+
+## Best Practices
+
+1. **Icons**: Always use Material Symbols Outlined for consistency
+2. **Labels**: Keep labels concise (1-2 words maximum)
+3. **Badges**: Use for important notifications only
+4. **Active State**: Let parent navigation bar manage active states
+5. **Disabled State**: Use sparingly, consider hiding instead
+6. **Custom Icons**: Use the icon slot for custom SVGs or emojis
+
+## Common Patterns
+
+### Dynamic Badges
+```javascript
+// Update badge based on notification count
+const updateBadge = (count) => {
+  const item = document.querySelector('#notifications-item');
+  item.badge = count > 0 ? String(count) : '';
+};
+```
+
+### Conditional Rendering
+```javascript
+// Show/hide items based on user role
+const items = user.isAdmin
+  ? ['dashboard', 'users', 'settings']
+  : ['dashboard', 'settings'];
+```
+
+### Icon Switching
+```javascript
+// Change icon based on state
+const icon = isPlaying ? 'pause' : 'play_arrow';
+```

package/ai/navigation-bar.md

@@ -0,0 +1,163 @@
+# Navigation Bar Component
+
+## 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.
+
+## Usage
+
+### Basic Example
+```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>
+```
+
+## Properties
+
+| 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 |
+
+## Events
+
+### 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
+
+### 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 Styling
+```css
+schmancy-navigation-bar {
+  /* Custom z-index if needed */
+  --navigation-bar-z-index: 20;
+}
+```
+
+## 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
+
+- Uses RxJS for efficient event handling
+- Scroll events are throttled at 100ms intervals
+- CSS transforms for smooth GPU-accelerated animations
+- Debounced navigation events (300ms) prevent accidental double-clicks
+- Lazy subscription setup for scroll listeners

package/dist/ai/navigation-bar-item.md

@@ -0,0 +1,247 @@
+# Navigation Bar Item Component
+
+## Overview
+The `<schmancy-navigation-bar-item>` component represents an individual navigation destination within a navigation bar. It follows Material Design 3 specifications with proper touch targets, ripple effects, and state management using RxJS observables.
+
+## Usage
+
+### Basic Example
+```html
+<schmancy-navigation-bar-item
+  icon="home"
+  label="Home"
+  active
+></schmancy-navigation-bar-item>
+```
+
+### With Badge
+```html
+<schmancy-navigation-bar-item
+  icon="notifications"
+  label="Alerts"
+  badge="5"
+></schmancy-navigation-bar-item>
+```
+
+### Custom Icon Slot
+```html
+<schmancy-navigation-bar-item label="Custom">
+  <span slot="icon">🏠</span>
+</schmancy-navigation-bar-item>
+```
+
+### With Custom Content
+```html
+<schmancy-navigation-bar-item>
+  <schmancy-icon slot="icon" size="24">favorite</schmancy-icon>
+  Custom Content
+</schmancy-navigation-bar-item>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `icon` | `string` | `''` | Material Symbols Outlined icon name |
+| `label` | `string` | `''` | Label text for the navigation item |
+| `badge` | `string` | `''` | Badge content (number or short text) |
+| `active` | `boolean` | `false` | Whether this item is currently active/selected |
+| `disabled` | `boolean` | `false` | Whether this item is disabled |
+| `hideLabels` | `boolean` | `false` | Hide labels (controlled by parent navigation bar) |
+
+## Events
+
+### bar-item-click
+Fired when the item is clicked (with 300ms debounce to prevent accidental double-clicks).
+
+```javascript
+item.addEventListener('bar-item-click', (event) => {
+  console.log('Icon:', event.detail.icon);
+  console.log('Label:', event.detail.label);
+  console.log('Active:', event.detail.active);
+});
+```
+
+### focus / blur
+Standard focus and blur events for accessibility.
+
+## Features
+
+### RxJS-Powered Interactions
+- **Click handling**: Uses RxJS observables with 300ms debounce for navigation events
+- **Ripple effects**: Immediate visual feedback without debounce
+- **Keyboard support**: Enter and Space keys properly handled with same debounce
+- **State management**: BehaviorSubject for reactive active state updates
+
+### Full Clickable Area
+The entire navigation item is clickable, not just the icon area:
+- Better touch targets on mobile devices
+- Improved accessibility
+- More intuitive user experience
+- 48x48dp minimum touch target as per Material Design
+
+### Badge System
+Intelligent badge handling:
+- Numbers > 99 display as "99+"
+- Text badges limited to 3 characters
+- Zero values hide the badge
+- Proper ARIA labels for screen readers
+
+### Ripple Animation
+Material Design ripple effect:
+- Originates from click position
+- 600ms animation duration
+- GPU-accelerated CSS animations
+- Multiple concurrent ripples supported
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `icon` | Custom icon content to replace the default icon |
+| default | Custom content for the item |
+
+## Styling
+
+### State-based Styling
+The component automatically applies different styles based on state:
+
+```css
+/* Active state */
+schmancy-navigation-bar-item[active] {
+  /* Icon indicator background: secondary-container */
+  /* Text color: secondary-onContainer */
+}
+
+/* Inactive state */
+schmancy-navigation-bar-item:not([active]) {
+  /* Text color: surface-onVariant */
+  /* Hover background: surface-container-highest */
+}
+
+/* Disabled state */
+schmancy-navigation-bar-item[disabled] {
+  /* Opacity: 0.38 */
+  /* Pointer events disabled */
+}
+```
+
+### CSS Parts
+```css
+/* Style the button element */
+schmancy-navigation-bar-item::part(button) {
+  /* Custom button styles */
+}
+```
+
+## Methods
+
+### setActive(isActive: boolean)
+Programmatically set the active state of the item.
+
+```javascript
+const item = document.querySelector('schmancy-navigation-bar-item');
+item.setActive(true); // Activate the item
+```
+
+## Integration Example
+
+### Complete Navigation Setup
+```typescript
+@customElement('app-navigation')
+class AppNavigation extends LitElement {
+  @state() activeIndex = 0;
+
+  private navigationItems = [
+    { icon: 'home', label: 'Home', route: 'home' },
+    { icon: 'search', label: 'Search', route: 'search' },
+    { icon: 'favorite', label: 'Favorites', route: 'favorites', badge: '3' },
+    { icon: 'person', label: 'Profile', route: 'profile' }
+  ];
+
+  private handleItemClick = (e: CustomEvent, index: number) => {
+    this.activeIndex = index;
+    const route = this.navigationItems[index].route;
+
+    // Navigate to route
+    area.push({
+      component: route,
+      area: 'main'
+    });
+  }
+
+  render() {
+    return html`
+      ${this.navigationItems.map((item, index) => html`
+        <schmancy-navigation-bar-item
+          icon=${item.icon}
+          label=${item.label}
+          ?active=${this.activeIndex === index}
+          badge=${item.badge || ''}
+          @bar-item-click=${(e: CustomEvent) => this.handleItemClick(e, index)}
+        ></schmancy-navigation-bar-item>
+      `)}
+    `;
+  }
+}
+```
+
+## Accessibility
+
+### Keyboard Support
+- `Enter` / `Space` - Activate the item (with 300ms debounce)
+- Full focus management with visual indicators
+- `aria-pressed` attribute reflects active state
+- `aria-label` for badge notifications
+
+### Screen Reader Support
+- Proper ARIA attributes
+- Semantic HTML structure
+- Badge announcements ("3 notifications")
+
+## Performance Optimization
+
+### RxJS Observables
+- Efficient event handling with proper cleanup
+- Debounced navigation events (300ms) prevent double-clicks
+- Immediate ripple feedback for better UX
+- Memory-safe with `takeUntil(this.disconnecting)`
+
+### Rendering Optimization
+- Conditional rendering based on props
+- Efficient class mapping with TailwindElement
+- Shadow DOM for style encapsulation
+
+## Best Practices
+
+1. **Icons**: Always use Material Symbols Outlined for consistency
+2. **Labels**: Keep labels concise (1-2 words maximum)
+3. **Badges**: Use for important notifications only
+4. **Active State**: Let parent navigation bar manage active states
+5. **Disabled State**: Use sparingly, consider hiding instead
+6. **Custom Icons**: Use the icon slot for custom SVGs or emojis
+
+## Common Patterns
+
+### Dynamic Badges
+```javascript
+// Update badge based on notification count
+const updateBadge = (count) => {
+  const item = document.querySelector('#notifications-item');
+  item.badge = count > 0 ? String(count) : '';
+};
+```
+
+### Conditional Rendering
+```javascript
+// Show/hide items based on user role
+const items = user.isAdmin
+  ? ['dashboard', 'users', 'settings']
+  : ['dashboard', 'settings'];
+```
+
+### Icon Switching
+```javascript
+// Change icon based on state
+const icon = isPlaying ? 'pause' : 'play_arrow';
+```