@mhmo91/schmancy 0.2.193 → 0.2.194

package/ai/area.md

@@ -0,0 +1,125 @@
+# Schmancy Area - AI Reference
+
+```js
+// Area Router Component
+<schmancy-area
+  name="root"
+  default="home-component">
+</schmancy-area>
+
+// Area Service
+import { area } from '@schmancy/area';
+
+// Navigation methods
+area.push({
+  component: UserProfileComponent,  // Component constructor, string tag name, or element instance
+  area: 'root',                     // Target area name
+  state?: { view: 'profile' },      // Optional state object
+  params?: { id: '123' },           // Optional parameters
+  historyStrategy: 'push'           // 'push', 'replace', 'pop', 'silent'
+});
+
+area.pop('sidebar');                // Remove an area
+
+// Subscription methods
+area.on(areaName, skipCurrent?) -> Observable<ActiveRoute>
+area.all(skipCurrent?) -> Observable<Map<string, ActiveRoute>>
+area.getState<T>(areaName) -> Observable<T>
+area.params<T>(areaName) -> Observable<T>
+area.param<T>(areaName, key) -> Observable<T>
+
+// Event name format for DOM event listeners
+schmancy-area-${areaName}-changed
+
+// Examples
+// 1. Basic navigation
+area.push({
+  component: 'home-page',
+  area: 'main',
+  historyStrategy: 'push'
+});
+
+// 2. Navigation with params
+area.push({
+  component: ProductDetailComponent,
+  area: 'main',
+  params: { productId: '12345' },
+  historyStrategy: 'push'
+});
+
+// 3. Subscribe to an area
+area.on('main').subscribe(route => {
+  console.log(`Component: ${route.component}, Params: ${route.params}`);
+});
+
+// 4. Get and react to a specific param
+area.param<string>('product', 'productId').subscribe(id => {
+  fetchProductDetails(id);
+});
+
+// 5. DOM event listening (non-RxJS approach)
+window.addEventListener('schmancy-area-main-changed', event => {
+  const { component, params } = event.detail;
+  updateUI(component, params);
+});
+```
+
+## Related Components
+- **[Teleport](./teleport.md)**: Can be used with Area for advanced component transportation
+- **[Store](./store.md)**: Complements Area for more complex state management
+- **[Layout](./layout.md)**: Often used as a container for areas
+
+## Technical Details
+
+### ActiveRoute Interface
+```typescript
+interface ActiveRoute {
+  component: string;        // Component tag name
+  area: string;             // Area name
+  state?: Record<string, unknown>;  // Optional state
+  params?: Record<string, unknown>; // Optional parameters
+}
+```
+
+### RouteAction Interface
+```typescript
+interface RouteAction {
+  component: CustomElementConstructor | string | HTMLElement;
+  area: string;
+  state?: Record<string, unknown>;
+  params?: Record<string, unknown>;
+  historyStrategy?: 'push' | 'replace' | 'pop' | 'silent';
+  clearQueryParams?: string[] | null;
+}
+```
+
+### Common Use Cases
+
+1. **Single Page Applications**: Define multiple areas for different sections of your app
+   ```html
+   <schmancy-area name="main"></schmancy-area>
+   <schmancy-area name="sidebar"></schmancy-area>
+   <schmancy-area name="modal"></schmancy-area>
+   ```
+
+2. **Typed Params and State**: Use TypeScript generics for type safety
+   ```typescript
+   interface UserParams { id: string; tab?: string; }
+   area.params<UserParams>('user').subscribe(params => {
+     fetchUser(params.id);
+     setActiveTab(params.tab || 'profile');
+   });
+   ```
+
+3. **Navigation Guards**: Implement navigation guards with RxJS operators
+   ```typescript
+   area.on('protected').pipe(
+     switchMap(route => {
+       if (!isAuthenticated()) {
+         area.push({ component: 'login-page', area: 'main' });
+         return EMPTY;
+       }
+       return of(route);
+     })
+   ).subscribe(handleProtectedRoute);
+   ```

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>
+```