@mhmo91/schmancy 0.2.193 → 0.2.195

package/ai/area.md

@@ -0,0 +1,205 @@
+# Schmancy Area
+
+Schmancy Area is a lightweight, reactive routing and state management system for web components with RxJS integration.
+
+## Component Usage
+
+```html
+<!-- Basic router outlet -->
+<schmancy-area 
+  name="main"
+  default="home-component">
+</schmancy-area>
+```
+
+## Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | `string` | **Required**. Unique identifier for this router outlet. |
+| `default` | `string \| Promise<NodeModule> \| CustomElementConstructor \| TemplateResult` | Default component to display if none is specified. |
+
+## Service API
+
+```ts
+// Import the area service
+import { area } from '@schmancy/area';
+
+// Navigation methods
+area.push({
+  component: 'user-profile',      // Component constructor, string tag name, or element instance
+  area: 'main',                   // Target area name
+  state?: { view: 'profile' },    // Optional state object
+  params?: { id: '123' },         // Optional parameters
+  historyStrategy: 'push',        // 'push', 'replace', 'pop', 'silent'
+  clearQueryParams?: ['sort']     // Clear specific query params
+});
+
+area.pop('sidebar');              // Remove an area
+
+// Subscription methods (return RxJS Observables)
+area.on(areaName, skipCurrent?)   // Subscribe to an area
+area.all(skipCurrent?)            // Subscribe to all areas 
+area.getState<T>(areaName)        // Get typed state from an area
+area.params<T>(areaName)          // Get typed params from an area
+area.param<T>(areaName, key)      // Get a specific param value
+```
+
+## Examples
+
+### Basic Navigation
+
+```ts
+// Navigate to a component
+area.push({
+  component: 'home-page',
+  area: 'main'
+});
+
+// Navigate with parameters and state
+area.push({
+  component: ProductDetailComponent,
+  area: 'main',
+  params: { productId: '12345' },
+  state: { showReviews: true },
+  historyStrategy: 'push'
+});
+```
+
+### Multiple Independent Areas
+
+```ts
+// Update multiple areas independently
+area.push({ component: 'product-list', area: 'main' });
+area.push({ component: 'filter-panel', area: 'sidebar' });
+
+// Open a modal dialog
+area.push({ 
+  component: 'dialog-component', 
+  area: 'modal',
+  params: { id: '123' }
+});
+
+// Close a modal
+area.pop('modal');
+```
+
+### Reactive Subscriptions
+
+```ts
+// Subscribe to area changes
+area.on('main').subscribe(route => {
+  console.log(`Component: ${route.component}`);
+  console.log(`Params:`, route.params);
+});
+
+// Type-safe state and params
+interface UserState { name: string; role: string; }
+interface UserParams { id: string; tab?: string; }
+
+area.getState<UserState>('user').subscribe(state => {
+  updateUserInfo(state.name, state.role);
+});
+
+area.params<UserParams>('user').subscribe(params => {
+  fetchUser(params.id);
+  setActiveTab(params.tab || 'profile');
+});
+
+// Get a specific parameter
+area.param<string>('product', 'productId').subscribe(id => {
+  fetchProductDetails(id);
+});
+```
+
+### DOM Events
+
+Areas also dispatch DOM events for non-RxJS consumers:
+
+```js
+// Format: schmancy-area-${areaName}-changed
+window.addEventListener('schmancy-area-main-changed', event => {
+  const { component, params, state } = event.detail;
+  updateUI(component, params, state);
+});
+```
+
+## Advanced Usage
+
+### Lazy Loading Components
+
+```ts
+area.push({
+  component: import('./components/heavy-dashboard.js'),
+  area: 'main'
+});
+```
+
+### Navigation Guards
+
+```ts
+import { switchMap, EMPTY, of } from 'rxjs';
+
+area.on('protected-area').pipe(
+  switchMap(route => {
+    if (!isAuthenticated()) {
+      area.push({ component: 'login-page', area: 'main' });
+      return EMPTY;
+    }
+    return of(route);
+  })
+).subscribe(handleProtectedRoute);
+```
+
+### Component Reloading Pattern
+
+When updating the same component with different parameters, use this pattern to ensure re-rendering:
+
+```ts
+// First push to the main routing area to force component re-creation
+area.push({
+  area: 'main-area',
+  component: 'user-profile',
+  params: { userId: '456' },
+  historyStrategy: 'push'
+});
+
+// Then update any subscription areas with the silent history strategy
+area.push({
+  area: 'user-area',
+  component: 'user-profile',
+  params: { userId: '456' },
+  historyStrategy: 'silent' // Don't create history entry
+});
+```
+
+This works around the `distinctUntilChanged` behavior in the Area component that compares only component names, not params.
+
+## Related Components
+
+- **[Store](./store.md)** - For more complex state management
+- **[Layout](./layout.md)** - For responsive layouts
+- **[Teleport](./teleport.md)** - For advanced component transportation
+- **[Sheet](./sheet.md)** - For modal overlays
+
+## Type Definitions
+
+```ts
+// Route Action - used for navigation
+interface RouteAction {
+  component: CustomElementConstructor | string | HTMLElement | Promise<NodeModule>;
+  area: string;
+  state?: Record<string, unknown>;
+  params?: Record<string, unknown>;
+  historyStrategy?: 'push' | 'replace' | 'pop' | 'silent';
+  clearQueryParams?: string[] | null;
+}
+
+// Active Route - current state of an area
+interface ActiveRoute {
+  component: string;
+  area: string;
+  state?: Record<string, unknown>;
+  params?: Record<string, unknown>;
+}
+```

package/ai/autocomplete.md

@@ -0,0 +1,135 @@
+# Schmancy Autocomplete - AI Reference
+
+```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" label="Option 1"></schmancy-option>
+  <schmancy-option value="option2" label="Option 2"></schmancy-option>
+  <schmancy-option value="option3" label="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" label="Option 1"></schmancy-option>
+  <schmancy-option value="option2" label="Option 2"></schmancy-option>
+  <schmancy-option value="option3" label="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
+debounceMs: number    // Debounce delay in milliseconds for filtering
+autocomplete: string  // Value for input's autocomplete attribute
+description: string   // Description for screen readers
+
+// 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" label="United States"></schmancy-option>
+  <schmancy-option value="ca" label="Canada"></schmancy-option>
+  <schmancy-option value="mx" label="Mexico"></schmancy-option>
+  <schmancy-option value="fr" label="France"></schmancy-option>
+  <schmancy-option value="de" label="Germany"></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" label="JavaScript"></schmancy-option>
+  <schmancy-option value="ts" label="TypeScript"></schmancy-option>
+  <schmancy-option value="py" label="Python"></schmancy-option>
+  <schmancy-option value="java" label="Java"></schmancy-option>
+  <schmancy-option value="go" label="Go"></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}
+      label=${item.name}>
+    </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" label="Human Resources"></schmancy-option>
+    <schmancy-option value="eng" label="Engineering"></schmancy-option>
+    <schmancy-option value="fin" label="Finance"></schmancy-option>
+  </schmancy-autocomplete>
+  
+  <schmancy-button type="submit">Submit</schmancy-button>
+</schmancy-form>
+```

package/ai/avatar.md

@@ -0,0 +1,178 @@
+# Schmancy Avatar - AI Reference
+
+```js
+// Basic Avatar
+<schmancy-avatar
+  src="path/to/image.jpg"
+  alt="User Name"
+  size="x-small|small|medium|large|x-large">
+</schmancy-avatar>
+
+// Avatar with name initials
+<schmancy-avatar
+  name="John Doe"
+  size="medium">
+</schmancy-avatar>
+
+// Avatar with icon
+<schmancy-avatar
+  icon="user"
+  size="medium">
+</schmancy-avatar>
+
+// Avatar with custom size and color
+<schmancy-avatar
+  name="John Doe"
+  size="48px"
+  background-color="#6200ee"
+  color="white">
+</schmancy-avatar>
+
+// Avatar with shape
+<schmancy-avatar
+  src="path/to/image.jpg"
+  shape="circle|square|rounded">
+</schmancy-avatar>
+
+// Avatar Properties
+src: string             // Image URL
+alt: string             // Alt text for the image
+name: string            // Name for generating initials
+icon: string            // Icon name to display (if no src or name)
+size: string            // Size: "x-small" (24px), "small" (32px), "medium" (40px), "large" (48px), "x-large" (56px), or custom size
+shape: string           // Shape: "circle" (default), "square", "rounded"
+backgroundColor: string // Background color for name and icon avatars
+color: string           // Text/icon color
+bordered: boolean       // Show border
+badgeContent: string    // Content for the badge
+badgeColor: string      // Color for the badge
+fallback: string        // Fallback content if image fails to load
+clickable: boolean      // Make avatar clickable with hover effect
+
+// Avatar Events
+@click              // Fires when avatar is clicked
+@error              // Fires when image fails to load
+
+// Examples
+// Basic image avatar
+<schmancy-avatar
+  src="https://example.com/avatar.jpg"
+  alt="Jane Smith"
+  size="medium">
+</schmancy-avatar>
+
+// Name initials avatar
+<schmancy-avatar
+  name="John Doe"
+  size="large">
+</schmancy-avatar>
+
+// Icon avatar
+<schmancy-avatar
+  icon="user"
+  size="medium"
+  background-color="var(--color-primary)"
+  color="white">
+</schmancy-avatar>
+
+// Avatar with badge
+<schmancy-avatar
+  src="https://example.com/avatar.jpg"
+  badge-content="3"
+  badge-color="error">
+</schmancy-avatar>
+
+// Avatar with status indicator
+<div style="position: relative;">
+  <schmancy-avatar
+    name="Jane Smith"
+    size="large">
+  </schmancy-avatar>
+  
+  <schmancy-badge
+    dot
+    variant="success"
+    style="position: absolute; bottom: 0; right: 0; border: 2px solid white;">
+  </schmancy-badge>
+</div>
+
+// Avatar group
+<div style="display: flex;">
+  <schmancy-avatar
+    src="https://example.com/avatar1.jpg"
+    size="medium"
+    style="margin-right: -8px; border: 2px solid white;">
+  </schmancy-avatar>
+  
+  <schmancy-avatar
+    src="https://example.com/avatar2.jpg"
+    size="medium"
+    style="margin-right: -8px; border: 2px solid white;">
+  </schmancy-avatar>
+  
+  <schmancy-avatar
+    src="https://example.com/avatar3.jpg"
+    size="medium"
+    style="margin-right: -8px; border: 2px solid white;">
+  </schmancy-avatar>
+  
+  <schmancy-avatar
+    name="+5"
+    size="medium"
+    background-color="#e0e0e0"
+    color="#757575"
+    style="border: 2px solid white;">
+  </schmancy-avatar>
+</div>
+
+// Clickable avatar for profile
+<schmancy-avatar
+  src="https://example.com/avatar.jpg"
+  size="large"
+  clickable
+  @click=${openProfile}>
+</schmancy-avatar>
+
+// Avatar with fallback
+<schmancy-avatar
+  src="https://example.com/avatar.jpg"
+  name="John Doe"
+  fallback="JD"
+  @error=${handleImageError}>
+</schmancy-avatar>
+
+// Square avatar
+<schmancy-avatar
+  src="https://example.com/avatar.jpg"
+  shape="square"
+  size="large">
+</schmancy-avatar>
+
+// Avatar in a list item
+<schmancy-list-item>
+  <schmancy-avatar
+    slot="start"
+    src="https://example.com/avatar.jpg"
+    size="medium">
+  </schmancy-avatar>
+  
+  <div slot="main">
+    <div>John Doe</div>
+    <div>Software Engineer</div>
+  </div>
+</schmancy-list-item>
+
+// Avatar in a chat message
+<div style="display: flex; margin-bottom: 16px;">
+  <schmancy-avatar
+    src="https://example.com/avatar.jpg"
+    size="small"
+    style="margin-right: 8px;">
+  </schmancy-avatar>
+  
+  <div>
+    <div><strong>Jane Smith</strong> <span style="color: #757575;">12:34 PM</span></div>
+    <div>Hello! How are you doing today?</div>
+  </div>
+</div>
+```

package/ai/badge.md

@@ -0,0 +1,100 @@
+# Schmancy Badge - AI Reference
+
+```js
+// Basic Badge
+<schmancy-badge>
+  42
+</schmancy-badge>
+
+// Badge with variants
+<schmancy-badge
+  variant="primary|secondary|success|warning|danger|info"
+  size="small|medium|large"
+  shape="square|pill|circle">
+  New
+</schmancy-badge>
+
+// Badge with icon
+<schmancy-badge variant="warning">
+  <schmancy-icon icon="warning"></schmancy-icon>
+  Caution
+</schmancy-badge>
+
+// Dot badge
+<schmancy-badge dot variant="danger"></schmancy-badge>
+
+// Badge on other elements
+<div style="position: relative;">
+  <schmancy-icon icon="notifications"></schmancy-icon>
+  <schmancy-badge
+    position="top-right"
+    value="5">
+  </schmancy-badge>
+</div>
+
+// Badge Properties
+variant: string       // Visual style: "primary", "secondary", "success", "warning", "danger", "info"
+size: string          // Size: "small", "medium", "large"
+shape: string         // Shape: "square", "pill", "circle"
+dot: boolean          // Show as a dot instead of with content
+position: string      // Positioning: "top-right", "top-left", "bottom-right", "bottom-left"
+value: string|number  // Value to display (alternative to slot content)
+max: number           // Maximum value to display before showing "+"
+invisible: boolean    // Hide the badge while maintaining layout
+
+// Examples
+// Simple numeric badge
+<schmancy-badge>10</schmancy-badge>
+
+// Styled text badge
+<schmancy-badge variant="success" shape="pill">
+  Completed
+</schmancy-badge>
+
+// Status badges
+<div>
+  <schmancy-badge variant="success">Active</schmancy-badge>
+  <schmancy-badge variant="warning">Pending</schmancy-badge>
+  <schmancy-badge variant="danger">Failed</schmancy-badge>
+  <schmancy-badge variant="info">Draft</schmancy-badge>
+</div>
+
+// Badge on a button
+<schmancy-button>
+  Notifications
+  <schmancy-badge
+    position="top-right"
+    variant="danger"
+    value="99+">
+  </schmancy-badge>
+</schmancy-button>
+
+// Badge with maximum value
+<schmancy-badge
+  value="125"
+  max="99">
+</schmancy-badge>
+// Shows "99+"
+
+// Dot indicators for status
+<div style="display: flex; align-items: center; gap: 8px;">
+  <schmancy-badge dot variant="success"></schmancy-badge>
+  <span>Online</span>
+</div>
+
+<div style="display: flex; align-items: center; gap: 8px;">
+  <schmancy-badge dot variant="warning"></schmancy-badge>
+  <span>Away</span>
+</div>
+
+<div style="display: flex; align-items: center; gap: 8px;">
+  <schmancy-badge dot variant="danger"></schmancy-badge>
+  <span>Offline</span>
+</div>
+
+// Badge with dynamic content
+<schmancy-badge
+  variant=${status === 'active' ? 'success' : 'warning'}
+  value=${count}>
+</schmancy-badge>
+```