@mhmo91/schmancy 0.8.4 → 0.9.2

package/ai/map.md

@@ -1,234 +0,0 @@
-# Schmancy Map Component
-
-The `schmancy-map` component provides an easy-to-use Google Maps integration with an intuitive API designed for both technical and non-technical users.
-
-## Installation
-
-```bash
-npm install @mhmo91/schmancy
-# or
-yarn add @mhmo91/schmancy
-```
-
-## Import
-
-```javascript
-import '@schmancy/index'  // For all Schmancy components
-// Or specific import: import '@schmancy/map'
-```
-
-## API Reference
-
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `address` | `string` | `''` | Simple address string that automatically geocodes to display the location. Takes precedence over latitude/longitude if both are provided. |
-| `latitude` | `number` | `undefined` | Latitude coordinate for precise location. Used when address is not provided. |
-| `longitude` | `number` | `undefined` | Longitude coordinate for precise location. Used when address is not provided. |
-| `zoom` | `number` | `15` | Map zoom level. Higher numbers show more detail (1-20). |
-| `height` | `string` | `"400px"` | Height of the map with CSS unit (e.g., "400px", "50vh"). |
-| `marker` | `boolean` | `true` | Whether to show a marker at the location. |
-| `markerTitle` | `string` | `''` | Tooltip text for the location marker. |
-| `type` | `'roadmap' \| 'satellite' \| 'hybrid' \| 'terrain'` | `'roadmap'` | Map display type. |
-| `interactive` | `boolean` | `true` | Whether users can interact with the map (pan, zoom, click). |
-| `controls` | `boolean` | `true` | Whether to show map controls (zoom buttons, fullscreen, etc.). |
-| `apiKey` | `string` | `''` | Google Maps API key. Falls back to GOOGLE_MAPS_API_KEY environment variable. |
-
-## Basic Usage
-
-### Simple Address
-The easiest way to display a map - just provide an address:
-
-```html
-<schmancy-map address="Times Square, New York"></schmancy-map>
-```
-
-### Coordinates
-For precise positioning, use latitude and longitude:
-
-```html
-<schmancy-map 
-  latitude="40.758" 
-  longitude="-73.985" 
-  zoom="17">
-</schmancy-map>
-```
-
-### Custom Height
-Adjust the map size:
-
-```html
-<schmancy-map 
-  address="Central Park, New York" 
-  height="600px">
-</schmancy-map>
-```
-
-## Map Types
-
-### Satellite View
-```html
-<schmancy-map 
-  address="Grand Canyon" 
-  type="satellite" 
-  height="500px">
-</schmancy-map>
-```
-
-### Hybrid View
-Combines satellite imagery with labels:
-
-```html
-<schmancy-map 
-  address="Mount Everest" 
-  type="hybrid">
-</schmancy-map>
-```
-
-### Terrain View
-Shows topographical features:
-
-```html
-<schmancy-map 
-  address="Yellowstone National Park" 
-  type="terrain">
-</schmancy-map>
-```
-
-## Static Maps
-
-For display-only maps without user interaction:
-
-```html
-<schmancy-map 
-  address="Eiffel Tower, Paris" 
-  interactive="false" 
-  controls="false">
-</schmancy-map>
-```
-
-## Customization
-
-### Custom Marker
-```html
-<schmancy-map 
-  address="Statue of Liberty" 
-  markerTitle="Welcome to Liberty Island">
-</schmancy-map>
-```
-
-### No Marker
-```html
-<schmancy-map 
-  address="Pacific Ocean" 
-  marker="false">
-</schmancy-map>
-```
-
-### Different Zoom Levels
-```html
-<!-- City view -->
-<schmancy-map address="Tokyo" zoom="10"></schmancy-map>
-
-<!-- Street view -->
-<schmancy-map address="Tokyo Tower" zoom="18"></schmancy-map>
-```
-
-## API Key Setup
-
-### Environment Variable (Recommended)
-Set `GOOGLE_MAPS_API_KEY` in your environment:
-
-```bash
-GOOGLE_MAPS_API_KEY=your_api_key_here
-```
-
-### Direct Property
-```html
-<schmancy-map 
-  address="Sydney Opera House" 
-  api-key="your_api_key_here">
-</schmancy-map>
-```
-
-## Features
-
-### Automatic Geocoding
-- Converts human-readable addresses to coordinates
-- Handles various address formats
-- Provides error feedback for invalid addresses
-
-### Responsive Design
-- Adapts to container width
-- Configurable height with CSS units
-- Maintains aspect ratio on mobile
-
-### Loading States
-- Shows spinner while loading
-- Displays error messages for failed loads
-- Graceful fallback when maps can't load
-
-### Performance
-- Lazy loads Google Maps API
-- Caches script loading across components
-- Minimal bundle size impact
-
-## Error Handling
-
-The component handles various error scenarios:
-
-- **Invalid Address**: Shows error message with geocoding failure
-- **Missing API Key**: Clear error message about required API key
-- **Network Issues**: Graceful fallback with retry capability
-- **Invalid Coordinates**: Validation of latitude/longitude ranges
-
-## Accessibility
-
-- Proper ARIA labels for screen readers
-- Keyboard navigation support (when interactive)
-- High contrast error states
-- Semantic HTML structure
-
-## Browser Support
-
-- Modern browsers with ES2015+ support
-- Google Maps API compatibility
-- Progressive enhancement for older browsers
-
-## Examples in Real Applications
-
-### Store Locator
-```html
-<schmancy-map 
-  address="Apple Store, 5th Avenue, New York" 
-  zoom="16" 
-  marker-title="Apple Store - 5th Avenue">
-</schmancy-map>
-```
-
-### Event Location
-```html
-<schmancy-map 
-  address="Madison Square Garden, New York" 
-  height="300px" 
-  interactive="false">
-</schmancy-map>
-```
-
-### Property Listing
-```html
-<schmancy-map 
-  latitude="40.7831" 
-  longitude="-73.9712" 
-  zoom="15" 
-  marker-title="Beautiful Apartment">
-</schmancy-map>
-```
-
-## Best Practices
-
-1. **Use addresses for user-friendly input**: Most users understand addresses better than coordinates
-2. **Set appropriate zoom levels**: 10-12 for cities, 15-17 for neighborhoods, 18+ for buildings
-3. **Consider mobile users**: Use responsive heights like "50vh" for mobile-friendly maps
-4. **Provide meaningful marker titles**: Help users understand what the marker represents
-5. **Use static maps for display-only**: Disable interaction when the map is purely informational

package/ai/navigation-bar-item.md

@@ -1,259 +0,0 @@
-# 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.
-
-```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 for instant navigation events
-- **Ripple effects**: Immediate visual feedback on interaction
-- **Keyboard support**: Enter and Space keys properly handled
-- **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
-// In Lit component - use property binding
-@state() isActive = true;
-
-render() {
-  return html`
-    <schmancy-navigation-bar-item ?active=${this.isActive}>
-    </schmancy-navigation-bar-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 instantly
-- 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
-- Instant navigation events for responsive interaction
-- 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
-// In Lit component - use declarative binding
-@state() notificationCount = 0;
-
-render() {
-  return html`
-    <schmancy-navigation-bar-item
-      badge=${this.notificationCount > 0 ? String(this.notificationCount) : ''}
-    ></schmancy-navigation-bar-item>
-  `;
-}
-```
-
-### 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/option.md

@@ -1,173 +0,0 @@
-# Option Component
-
-A versatile option element designed for use with select dropdowns and autocomplete components, providing accessible and interactive selection items.
-
-## Quick Start
-
-```html
-<!-- Basic option -->
-<schmancy-option value="1">Option One</schmancy-option>
-
-<!-- Option with custom label -->
-<schmancy-option value="us">United States</schmancy-option>
-
-<!-- Option with icon -->
-<schmancy-option value="email" icon="✉️">Email Notifications</schmancy-option>
-```
-
-## Properties
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `value` | `string` | `''` | The value when selected |
-| `label` | `string` | `''` | Display label (defaults to text content) |
-| `selected` | `boolean` | `false` | Whether option is selected |
-| `disabled` | `boolean` | `false` | Whether option is disabled |
-| `group` | `string` | `''` | Optional group name |
-| `icon` | `string` | `''` | Optional icon/emoji |
-
-## Events
-
-### option-select
-Fired when option is clicked or selected via keyboard.
-
-```typescript
-interface OptionSelectEvent {
-  detail: {
-    value: string;
-  }
-}
-```
-
-## Examples
-
-### In Select Component
-```html
-<schmancy-select placeholder="Choose country">
-  <schmancy-option value="us" icon="🇺🇸">United States</schmancy-option>
-  <schmancy-option value="uk" icon="🇬🇧">United Kingdom</schmancy-option>
-  <schmancy-option value="ca" icon="🇨🇦">Canada</schmancy-option>
-  <schmancy-option value="au" icon="🇦🇺">Australia</schmancy-option>
-</schmancy-select>
-```
-
-### Grouped Options
-```html
-<schmancy-select>
-  <!-- North America -->
-  <schmancy-option value="us" group="North America">United States</schmancy-option>
-  <schmancy-option value="ca" group="North America">Canada</schmancy-option>
-  <schmancy-option value="mx" group="North America">Mexico</schmancy-option>
-  
-  <!-- Europe -->
-  <schmancy-option value="uk" group="Europe">United Kingdom</schmancy-option>
-  <schmancy-option value="de" group="Europe">Germany</schmancy-option>
-  <schmancy-option value="fr" group="Europe">France</schmancy-option>
-</schmancy-select>
-```
-
-### With Status Indicators
-```html
-<schmancy-autocomplete>
-  <schmancy-option value="active" icon="🟢">Active</schmancy-option>
-  <schmancy-option value="pending" icon="🟡">Pending</schmancy-option>
-  <schmancy-option value="inactive" icon="🔴">Inactive</schmancy-option>
-  <schmancy-option value="archived" icon="📦" disabled>Archived</schmancy-option>
-</schmancy-autocomplete>
-```
-
-### Dynamic Options
-```html
-${users.map(user => html`
-  <schmancy-option 
-    value="${user.id}"
-    label="${user.name}"
-    ?disabled="${!user.active}"
-  >
-    <span class="flex items-center gap-2">
-      <schmancy-avatar size="xs" name="${user.name}"></schmancy-avatar>
-      <span>
-        <div>${user.name}</div>
-        <div class="text-xs opacity-70">${user.email}</div>
-      </span>
-    </span>
-  </schmancy-option>
-`)}
-```
-
-## Features
-
-### Automatic Value Assignment
-- If no value is provided, uses text content
-- If no label is provided, uses text content or value
-
-### Keyboard Navigation
-- `Space` or `Enter` to select
-- Full keyboard accessibility
-
-### Visual States
-- Hover highlighting
-- Selected state with checkmark
-- Disabled state with reduced opacity
-- Focus ring for keyboard navigation
-
-### Unique IDs
-Automatically generates unique IDs for accessibility if not provided.
-
-## Styling
-
-The component uses semantic design tokens:
-
-```css
-/* Default state */
-.hover:bg-surface-high
-
-/* Selected state */
-.bg-primary-container
-.text-primary-onContainer
-
-/* Custom styling */
-schmancy-option {
-  --option-padding-y: 0.5rem;
-  --option-padding-x: 0.75rem;
-  --option-border-radius: 0.25rem;
-}
-```
-
-## Accessibility
-
-- `role="option"` for semantic meaning
-- `aria-selected` state management
-- `aria-disabled` for disabled options
-- Keyboard event handling
-- Focus management
-
-## Integration
-
-Options are designed to work seamlessly with:
-- `schmancy-select` - Dropdown selection
-- `schmancy-autocomplete` - Filtered selection
-- Custom dropdown components
-
-## Best Practices
-
-1. **Clear Values**: Use meaningful, unique values
-2. **Icons**: Use icons to improve scannability
-3. **Groups**: Group related options together
-4. **Labels**: Provide clear, concise labels
-5. **Disabled State**: Clearly indicate why options are disabled
-
-## Related Components
-
-- [Select](./select.md) - Dropdown selector
-- [Autocomplete](./autocomplete.md) - Searchable selector
-- [List](./list.md) - Similar list item pattern
-- [Menu](./menu.md) - Menu items
-
-## Use Cases
-
-1. **Form Selects**: Country, state, category selection
-2. **Settings**: Preference options
-3. **Filters**: Data filtering options
-4. **Status Selection**: Workflow states
-5. **User Selection**: Team member pickers