@mhmo91/schmancy 0.8.6 → 0.9.2

package/dist/ai/animation.md

@@ -0,0 +1,64 @@
+# Blackbird Animation System
+
+> Spring physics animation presets for the Web Animations API and CSS transitions.
+
+## Spring Presets
+
+| Preset | Duration | Character | Best For |
+|--------|----------|-----------|----------|
+| `SPRING_SMOOTH` | 500ms | Apple-style, subtle overshoot | Accordions, content reveals |
+| `SPRING_SNAPPY` | 300ms | Quick, minimal overshoot | Buttons, toggles |
+| `SPRING_BOUNCY` | 600ms | Playful, noticeable overshoot | Notifications, celebrations |
+| `SPRING_GENTLE` | 700ms | Slow, no overshoot | Page transitions, modals |
+
+## Usage with Web Animations API
+```typescript
+import { createAnimation, SPRING_SMOOTH } from '@mhmo91/schmancy'
+
+const anim = createAnimation(SPRING_SMOOTH, {
+  from: { opacity: 0, transform: 'translateY(-16px)' },
+  to: { opacity: 1, transform: 'translateY(0)' }
+})
+
+element.animate(anim.keyframes, anim.options)
+```
+
+## Helper Functions
+```typescript
+import {
+  createRevealAnimation,   // Fade in + slide up
+  createDismissAnimation,  // Fade out + slide up
+  createScaleAnimation,    // Pop in/out
+  getEasing,               // Auto-detect linear() support
+  prefersReducedMotion     // Check reduced motion preference
+} from '@mhmo91/schmancy'
+
+// Reveal animation
+const reveal = createRevealAnimation(SPRING_SMOOTH, 16) // 16px distance
+element.animate(reveal.keyframes, reveal.options)
+
+// Scale animation
+const scale = createScaleAnimation(SPRING_SNAPPY, 0.9, 1)
+element.animate(scale.keyframes, scale.options)
+```
+
+## CSS Custom Properties
+```css
+/* Available after injecting ANIMATION_CSS_VARS */
+.element {
+  transition: transform var(--blackbird-duration-smooth) var(--blackbird-easing-smooth);
+}
+```
+
+## Tailwind Integration
+```typescript
+import { tailwindAnimations } from '@mhmo91/schmancy'
+// Use in tailwind.config.js extend block
+
+// Available classes:
+// ease-spring-smooth, ease-spring-snappy, ease-spring-bouncy, ease-spring-gentle
+// duration-spring-smooth, duration-spring-snappy, etc.
+// animate-blackbird-reveal, animate-blackbird-dismiss, etc.
+```
+
+All animations respect `prefers-reduced-motion: reduce` (instant transitions, no animation).

package/dist/ai/area.md

@@ -1,282 +1,61 @@
-# Schmancy Area - Routing System
+# schmancy-area / schmancy-route
 
-Reactive routing system for web components using RxJS. Supports multiple outlets, guards, lazy loading, and nested routing.
-
-## Quick Start
+> Client-side router with named areas, lazy loading, route guards, and browser history integration.
 
+## Usage
 ```html
-<!-- Define routes declaratively -->
 <schmancy-area name="main" default="home-page">
-  <schmancy-route when="products" component="product-list"></schmancy-route>
-  <schmancy-route when="about" component="about-page"></schmancy-route>
-  <schmancy-route
-    when="admin"
-    component="admin-panel"
-    .guard=${authState$.asObservable()}
-    @redirect=${() => area.push({ component: 'login', area: 'main' })}>
-  </schmancy-route>
+  <schmancy-route when="home-page" .component=${lazy(() => import('./home'))}></schmancy-route>
+  <schmancy-route when="settings-page" .component=${lazy(() => import('./settings'))}></schmancy-route>
 </schmancy-area>
 ```
 
-```typescript
-// Navigate programmatically
-import { area } from '@schmancy/area';
-
-area.push({
-  component: 'product-detail',
-  area: 'main',
-  params: { productId: '123' },
-  state: { fromCart: true }
-});
-```
-
-## Core Components
-
-### `<schmancy-area>` - Router Outlet
-| Property | Type | Required | Description |
-|----------|------|----------|-------------|
-| `name` | `string` | ✓ | Unique outlet identifier |
-| `default` | `ComponentType` | | Fallback when no route matches |
-
-### `<schmancy-route>` - Route Definition
-| Property | Type | Required | Description |
-|----------|------|----------|-------------|
-| `when` | `string` | ✓ | URL segment or component tag to match |
-| `component` | `RouteComponent` | ✓ | Component to render |
-| `guard` | `Observable<boolean>` | | Navigation guard |
-| `exact` | `boolean` | | Currently unused |
-
-## URL Matching
-
-Routes match in DOM order. First match wins.
-
-```html
-<!-- Matches URL segments -->
-<schmancy-route when="products" component="product-list"></schmancy-route>
-<!-- URL: /store/products → segments: ['store', 'products'] → MATCHES -->
-
-<!-- Matches component tag for programmatic nav -->
-<schmancy-route when="user-profile" component="user-profile"></schmancy-route>
-<!-- area.push({ component: 'user-profile', area: 'main' }) → MATCHES -->
-```
-
-## Navigation Guards
+## Properties (schmancy-area)
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| name | string | required | Unique area name |
+| default | RouteComponent | - | Default route component |
 
-Guards are `Observable<boolean>` that emit true to allow, false to block navigation.
+## Properties (schmancy-route)
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| when | string | required | Route identifier (must match `@customElement` tag) |
+| component | RouteComponent | required | Component to render (class, tag name, or lazy) |
+| exact | boolean | `false` | Exact path matching |
+| guard | Observable<boolean> | - | Route guard observable |
 
+## Programmatic Navigation (area service)
 ```typescript
-// Simple guard
-const authState$ = new BehaviorSubject(false);
-
-<schmancy-route
-  when="protected"
-  component="protected-page"
-  .guard=${authState$.asObservable()}
-  @redirect=${(e) => {
-    // e.detail contains: blockedRoute, area, params, state
-    $notify.error('Access denied');
-    area.push({ component: 'login', area: 'main' });
-  }}>
-</schmancy-route>
+import { area } from '@mhmo91/schmancy'
 
-// Complex guard with multiple conditions
-const canAccess$ = combineLatest([authState$, roleState$]).pipe(
-  map(([auth, role]) => auth && role === 'admin')
-);
-```
-
-**Important**: Guards return `Observable<boolean>` only. No strings, objects, or redirect paths.
-Handle redirects via `@redirect` event.
-
-## Service API
-
-```typescript
-import { area } from '@schmancy/area';
-
-// Navigation
-area.push({
-  component: string | Constructor | HTMLElement | LazyComponent,
-  area: string,                          // Required
-  state?: any,                          // Stored in history
-  params?: any,                         // Applied to component
-  props?: any,                          // Alias for params
-  historyStrategy?: 'push' | 'replace' | 'silent',
-  clearQueryParams?: string[] | boolean
-});
-
-// Clear area
-area.pop('sidebar');
+// Navigate
+area.push({ area: 'main', component: 'settings-page', params: { id: '123' } })
 
-// Subscriptions (return Observables)
-area.on(areaName)                      // Subscribe to route changes
-area.getState<T>(areaName)            // Get typed state
-area.params<T>(areaName)              // Get typed params
+// Subscribe to area changes
+area.on('main').pipe(takeUntil(this.disconnecting)).subscribe(route => { ... })
 
-// Configuration
-area.prettyURL = false                 // JSON-encoded URLs (default)
-area.enableHistoryMode = true          // Browser history (default)
+// Get params
+area.params<{id: string}>('main').pipe(takeUntil(this.disconnecting)).subscribe(params => { ... })
 ```
 
 ## Lazy Loading
-
 ```typescript
-import { lazy } from '@schmancy/area';
-
-// Define lazy components
-const LazyDashboard = lazy(() => import('./dashboard'));
-
-// Use in routes
-<schmancy-route
-  when="dashboard"
-  .component=${LazyDashboard}>
-</schmancy-route>
+import { lazy } from '@mhmo91/schmancy'
+const LazyPage = lazy(() => import('./my-page'))
 
 // Preload on hover
-button.addEventListener('mouseenter', () => {
-  LazyDashboard.preload();
-});
-
-// Navigate
-area.push({ component: LazyDashboard, area: 'main' });
+element.addEventListener('mouseenter', () => LazyPage.preload())
 ```
 
-## Nested Routing
-
+## Examples
 ```html
-<schmancy-area name="main">
-  <schmancy-route when="app" component="app-layout">
-    <!-- Inside app-layout component -->
-    <schmancy-area name="app-content">
-      <schmancy-route when="users" component="user-list"></schmancy-route>
-      <schmancy-route when="settings" component="settings"></schmancy-route>
-    </schmancy-area>
+<!-- With route guard -->
+<schmancy-area name="admin" default="admin-dashboard">
+  <schmancy-route when="admin-dashboard"
+    .component=${lazy(() => import('./dashboard'))}
+    .guard=${isAdmin$}>
   </schmancy-route>
 </schmancy-area>
 ```
 
-## Common Patterns
-
-### Protected Routes with Authentication
-
-```typescript
-@customElement('app-shell')
-export class AppShell extends $LitElement() {
-  private authState$ = new BehaviorSubject(false);
-
-  render() {
-    return html`
-      <schmancy-area name="main">
-        <schmancy-route when="home" component="home-page"></schmancy-route>
-
-        <schmancy-route
-          when="dashboard"
-          component="dashboard"
-          .guard=${this.authState$.asObservable()}
-          @redirect=${() => {
-            area.push({ component: 'login', area: 'main' });
-          }}>
-        </schmancy-route>
-      </schmancy-area>
-    `;
-  }
-}
-```
-
-### Multi-Area Application
-
-```html
-<!-- Multiple independent outlets -->
-<div class="layout">
-  <schmancy-area name="sidebar" default="nav-menu"></schmancy-area>
-  <schmancy-area name="main" default="home"></schmancy-area>
-  <schmancy-area name="modal"></schmancy-area>
-</div>
-```
-
-```typescript
-// Navigate different areas independently
-area.push({ component: 'user-list', area: 'main' });
-area.push({ component: 'quick-stats', area: 'sidebar' });
-area.push({ component: 'edit-dialog', area: 'modal' });
-
-// Clear modal
-area.pop('modal');
-```
-
-## Type Definitions
-
-```typescript
-// Navigation request
-interface RouteAction {
-  component: ComponentType;
-  area: string;
-  state?: Record<string, any>;
-  params?: Record<string, any>;
-  props?: Record<string, any>;  // Alias for params
-  historyStrategy?: 'push' | 'replace' | 'silent';
-  clearQueryParams?: string[] | boolean;
-}
-
-// Guard type
-type ObservableGuardResult = Observable<boolean>;
-
-// Component types
-type RouteComponent =
-  | string                                           // Tag name
-  | CustomElementConstructor                        // Class
-  | HTMLElement                                     // Instance
-  | (() => Promise<{ default: Constructor }>)      // Lazy
-
-// Redirect event detail
-interface RedirectEventDetail {
-  blockedRoute: string;
-  area: string;
-  params: Record<string, any>;
-  state: Record<string, any>;
-}
-```
-
-## Internal Behavior
-
-### Route Resolution Pipeline
-1. Receives navigation request (programmatic, URL, or browser)
-2. Resolves lazy components to constructors
-3. Deduplicates identical routes
-4. Evaluates guard Observable
-5. Creates element and applies properties
-6. Swaps components with 150ms fade animation
-
-### Route Evaluation Order
-- Routes evaluated in DOM order
-- First matching route wins
-- Empty `when=""` acts as catch-all
-
-### History Management
-- JSON-encoded URLs by default: `/%7B%22main%22%3A%7B%22component%22%3A%22home%22%7D%7D`
-- Pretty URLs optional: `/products?id=123`
-- State stored in `history.state.schmancyAreas`
-
-## Troubleshooting
-
-**Routes not matching**
-- Check route order (specific before general)
-- Verify `when` matches URL segment or component tag
-
-**Guards not working**
-- Must be `Observable<boolean>`, not functions
-- Use `.asObservable()` on BehaviorSubjects
-- Handle redirects in `@redirect` event
-
-**Nested routes failing**
-- Each area needs unique name
-- Parent must render child `<schmancy-area>`
-
-**area.pop() not clearing**
-- Verify area name is correct
-- Check no immediate re-navigation
-
-## Related Components
-
-- **[Store](./store.md)** - State management
-- **[Sheet](./sheet.md)** - Modal overlays
-- **[Layout](./layout.md)** - Responsive layouts
+**Critical:** `when="tag-name"` MUST exactly match `@customElement('tag-name')` on the component class.

package/dist/ai/autocomplete.md

@@ -1,171 +1,53 @@
-# Schmancy Autocomplete - AI Reference
+# schmancy-autocomplete
 
-## Overview
-A searchable dropdown component with fuzzy search, keyboard navigation, and multi-select support. Uses similarity scoring for intelligent option filtering.
+> Searchable input with fuzzy filtering, single/multi-select, and inline chip display.
 
-```js
-// Basic Autocomplete (Single-Select)
-<schmancy-autocomplete
-  label="Select an option"
-  placeholder="Type to search..."
-  value="selected-value"
-  size="sm|md|lg"
-  required?
-  maxHeight="300px"
-  @change=${handleChange}>
-  
-  <schmancy-option value="option1">Option 1</schmancy-option>
-  <schmancy-option value="option2">Option 2</schmancy-option>
-  <schmancy-option value="option3">Option 3</schmancy-option>
-</schmancy-autocomplete>
-
-// Multi-Select Autocomplete
-<schmancy-autocomplete
-  label="Select multiple options"
-  placeholder="Type to search..."
-  multi
-  .values=${['option1', 'option3']} // Array of selected values (preferred for multi-select)
-  @change=${handleMultiChange}>
-  
-  <schmancy-option value="option1">Option 1</schmancy-option>
-  <schmancy-option value="option2">Option 2</schmancy-option>
-  <schmancy-option value="option3">Option 3</schmancy-option>
-</schmancy-autocomplete>
-
-// Autocomplete with Custom Trigger
-<schmancy-autocomplete>
-  <button slot="trigger">Open Options</button>
-  
-  <schmancy-option value="option1" label="Option 1"></schmancy-option>
-  <schmancy-option value="option2" label="Option 2"></schmancy-option>
-</schmancy-autocomplete>
-
-// Autocomplete Properties
-value: string              // Selected value for single-select, comma-separated string for multi-select (legacy API)
-values: string[]           // Array of selected values for multi-select (preferred API for multi-select)
-multi: boolean             // Enable multi-select mode
-label: string              // Input label
-placeholder: string        // Input placeholder
-required: boolean          // Mark as required for validation
-size: string               // Input size: "sm", "md", "lg"
-maxHeight: string          // Maximum height of dropdown (default: "300px")
-debounceMs: number         // Debounce delay in milliseconds for filtering (default: 200)
-similarityThreshold: number // Minimum similarity score to show option (0-1, default: 0.3)
-autocomplete: string       // Value for input's autocomplete attribute
-description: string        // Description for screen readers
-name: string               // Form field name for form submission
-
-// Autocomplete Events
-@change   // Fires when selection changes with { detail: { value, values? } }
-
-// Autocomplete Methods
-checkValidity() -> boolean    // Check if the input is valid
-reportValidity() -> boolean   // Show validation state and return validity
-
-// Examples
-// Basic usage
-<schmancy-autocomplete
-  label="Country"
-  placeholder="Select country"
-  @change=${(e) => selectedCountry = e.detail.value}>
-  
-  <schmancy-option value="us">United States</schmancy-option>
-  <schmancy-option value="ca">Canada</schmancy-option>
-  <schmancy-option value="mx">Mexico</schmancy-option>
-  <schmancy-option value="fr">France</schmancy-option>
-  <schmancy-option value="de">Germany</schmancy-option>
+## Usage
+```html
+<schmancy-autocomplete label="Assignee" placeholder="Search...">
+  <schmancy-option value="alice" label="Alice"></schmancy-option>
+  <schmancy-option value="bob" label="Bob"></schmancy-option>
 </schmancy-autocomplete>
+```
 
-// Multi-select with preferred API
-<schmancy-autocomplete
-  label="Programming Languages"
-  placeholder="Select languages"
-  multi
-  .values=${selectedLanguages}
-  @change=${(e) => {
-    selectedLanguages = e.detail.values; // Use the new values array property
-  }}>
-  
-  <schmancy-option value="js">JavaScript</schmancy-option>
-  <schmancy-option value="ts">TypeScript</schmancy-option>
-  <schmancy-option value="py">Python</schmancy-option>
-  <schmancy-option value="java">Java</schmancy-option>
-  <schmancy-option value="go">Go</schmancy-option>
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| value | string | `''` | Selected value (single) or comma-separated (multi) |
+| values | string[] | `[]` | Selected values (multi-select) |
+| label | string | `''` | Label text |
+| placeholder | string | `''` | Placeholder text |
+| name | string | `''` | Form submission name |
+| required | boolean | `false` | Whether selection is required |
+| multi | boolean | `false` | Enable multi-select with inline chips |
+| size | `'xs'\|'sm'\|'md'\|'lg'` | `'md'` | Input height |
+| maxHeight | string | `'300px'` | Max dropdown height |
+| debounceMs | number | `200` | Search debounce in ms |
+| similarityThreshold | number | `0.3` | Minimum fuzzy match score (0-1) |
+| error | boolean | `false` | Error state |
+| validationMessage | string | `''` | Validation message |
+| description | string | `''` | Screen reader description |
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| change | `{ value: string \| string[], values?: string[] }` | When selection changes |
+
+## Examples
+```html
+<!-- Multi-select with chips -->
+<schmancy-autocomplete label="Skills" multi placeholder="Type to search...">
+  <schmancy-option value="ts" label="TypeScript"></schmancy-option>
+  <schmancy-option value="lit" label="Lit"></schmancy-option>
+  <schmancy-option value="rxjs" label="RxJS"></schmancy-option>
 </schmancy-autocomplete>
 
-// Handling the change event
-handleChange(e) {
-  if (e.target.multi) {
-    const selectedValues = e.detail.values; // Array of values (preferred)
-    const legacyValue = e.detail.value;     // Comma-separated string (legacy)
-    console.log('Selected:', selectedValues);
-  } else {
-    const selectedValue = e.detail.value;   // Single value
-    console.log('Selected:', selectedValue);
-  }
-}
-
-// Dynamic options from data
-<schmancy-autocomplete
-  label="Select Item"
-  .value=${selectedItem}>
-  
-  ${items.map(item => html`
-    <schmancy-option value=${item.id}>
-      ${item.name}
-    </schmancy-option>
-  `)}
+<!-- Single select, auto-selects best match on blur -->
+<schmancy-autocomplete label="City" placeholder="Search city..."
+  @change=${(e) => console.log(e.detail.value)}>
+  <schmancy-option value="berlin" label="Berlin"></schmancy-option>
+  <schmancy-option value="munich" label="Munich"></schmancy-option>
 </schmancy-autocomplete>
-
-// In a form
-<schmancy-form @submit=${handleSubmit}>
-  <schmancy-input
-    name="name"
-    label="Name"
-    required>
-  </schmancy-input>
-  
-  <schmancy-autocomplete
-    name="department"
-    label="Department"
-    required>
-    <schmancy-option value="hr">Human Resources</schmancy-option>
-    <schmancy-option value="eng">Engineering</schmancy-option>
-    <schmancy-option value="fin">Finance</schmancy-option>
-  </schmancy-autocomplete>
-  
-  <schmancy-button type="submit">Submit</schmancy-button>
-</schmancy-form>
 ```
 
-## Key Features
-
-### Fuzzy Search
-- Uses similarity scoring algorithm to find best matches
-- Searches both option labels and values
-- Configurable similarity threshold (0-1)
-- Options are sorted by relevance score
-
-### Keyboard Navigation
-- `ArrowDown/ArrowUp` - Navigate through options
-- `Enter/Space` - Select focused option
-- `Escape` - Close dropdown
-- `Tab` - Move to next field and close dropdown
-- `Home/End` - Jump to first/last option
-
-### Auto-Select on Blur
-- In single-select mode, automatically selects the best matching option when input loses focus
-- Only triggers if there's a search term and a good match
-- Helps with quick data entry
-
-### Accessibility
-- Full ARIA support with proper roles and attributes
-- Screen reader announcements for option counts and selections
-- Keyboard-only navigation support
-- Focus management
-
-### Performance
-- Debounced search input (configurable delay)
-- Efficient RxJS-based state management
-- Virtual scrolling for large option lists
-- Options are only filtered when dropdown is open
+Children must be `<schmancy-option>` elements. In multi mode, selected items appear as removable chips.