@mhmo91/schmancy 0.8.4 → 0.9.2

package/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.

package/ai/avatar.md

@@ -1,178 +1,47 @@
-# 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>
-```
+# schmancy-avatar
+
+> Avatar component displaying initials, image, or icon with color themes, shapes, and status indicators.
+
+## Usage
+```html
+<schmancy-avatar initials="JD" color="primary"></schmancy-avatar>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| initials | string | `''` | Text initials (max 2 characters) |
+| src | string | `''` | Image URL |
+| icon | string | `''` | Material icon name |
+| size | `'xxs'\|'xs'\|'sm'\|'md'\|'lg'\|'xl'` | `'md'` | Avatar size (20-64px) |
+| color | `'primary'\|'secondary'\|'tertiary'\|'success'\|'error'\|'neutral'` | `'primary'` | Color theme |
+| shape | `'circle'\|'square'` | `'circle'` | Avatar shape |
+| bordered | boolean | `false` | Show border ring |
+| status | `'online'\|'offline'\|'busy'\|'away'\|'none'` | `'none'` | Status indicator dot |
+
+## Size Reference
+| Token | Size | Description |
+|-------|------|-------------|
+| xxs | 20px | Ultra-compact |
+| xs | 24px | Compact |
+| sm | 32px | Small |
+| md | 40px | Default |
+| lg | 48px | Large |
+| xl | 64px | Extra large |
+
+## Examples
+```html
+<!-- Image avatar with status -->
+<schmancy-avatar src="/photos/alice.jpg" size="lg" status="online"></schmancy-avatar>
+
+<!-- Icon avatar -->
+<schmancy-avatar icon="group" color="secondary" shape="square"></schmancy-avatar>
+
+<!-- Bordered initials -->
+<schmancy-avatar initials="AB" color="tertiary" bordered></schmancy-avatar>
+
+<!-- Default (person icon) -->
+<schmancy-avatar size="sm" color="neutral"></schmancy-avatar>
+```
+
+Priority: `src` (image) > `initials` > `icon` > default person icon.

package/ai/badge.md

@@ -1,108 +1,41 @@
-# Schmancy Badge - AI Reference
-
-```js
-// Basic Badge
-<schmancy-badge>
-  42
-</schmancy-badge>
-
-// Also supports <schmancy-badge> for backward compatibility
-
-// Badge with color variants
-<schmancy-badge
-  color="primary|secondary|tertiary|success|warning|error|neutral"
-  size="xs|sm|md|lg"
-  shape="square|rounded|pill">
-  New
-</schmancy-badge>
-
-// Badge with icon slot
-<schmancy-badge color="warning">
-  <schmancy-icon slot="icon" icon="warning"></schmancy-icon>
-  Caution
-</schmancy-badge>
-
-// Badge with icon property
-<schmancy-badge color="success" icon="check">
-  Complete
-</schmancy-badge>
-
-// Outlined badge
-<schmancy-badge color="primary" outlined>
-  Outlined
-</schmancy-badge>
-
-// Pulsing badge
-<schmancy-badge color="error" pulse>
-  Alert
-</schmancy-badge>
-
-// Badge Properties
-color: BadgeColor     // Color variant: "primary", "secondary", "tertiary", "success", "warning", "error", "neutral"
-size: BadgeSize       // Size: "xs", "sm", "md", "lg"
-shape: BadgeShape     // Shape: "square", "rounded", "pill"
-outlined: boolean     // Outlined style instead of filled
-icon: string          // Icon name to display (if no icon slot is provided)
-pulse: boolean        // Make the badge pulse for attention
-
-// Slots
-default: Badge content (text or HTML)
-icon: Optional icon to display before the content
-
-// Examples
-// Simple numeric badge
-<schmancy-badge>10</schmancy-badge>
-
-// Styled text badge
-<schmancy-badge color="success" shape="pill">
-  Completed
-</schmancy-badge>
-
-// Status badges
-<div>
-  <schmancy-badge color="success">Active</schmancy-badge>
-  <schmancy-badge color="warning">Pending</schmancy-badge>
-  <schmancy-badge color="error">Failed</schmancy-badge>
-  <schmancy-badge color="primary">Draft</schmancy-badge>
-</div>
-
-// Badge sizes
-<schmancy-badge size="xs">XS</schmancy-badge>
-<schmancy-badge size="sm">Small</schmancy-badge>
-<schmancy-badge size="md">Medium</schmancy-badge>
-<schmancy-badge size="lg">Large</schmancy-badge>
-
-// Badge shapes
-<schmancy-badge shape="square">Square</schmancy-badge>
-<schmancy-badge shape="rounded">Rounded</schmancy-badge>
-<schmancy-badge shape="pill">Pill</schmancy-badge>
-
-// Outlined badges
-<schmancy-badge color="primary" outlined>Primary</schmancy-badge>
-<schmancy-badge color="secondary" outlined>Secondary</schmancy-badge>
-<schmancy-badge color="error" outlined>Error</schmancy-badge>
-
-// Badge with icon
-<schmancy-badge color="success" icon="check_circle">
-  Verified
-</schmancy-badge>
-
-// Badge with custom icon slot
-<schmancy-badge color="warning">
-  <schmancy-icon slot="icon" icon="warning"></schmancy-icon>
-  Warning
-</schmancy-badge>
-
-// Pulsing badges for attention
-<schmancy-badge color="error" pulse>
-  New
-</schmancy-badge>
-
-// Badge with dynamic properties
-<schmancy-badge
-  color=${status === 'active' ? 'success' : 'neutral'}
-  outlined=${isOutlined}
-  pulse=${needsAttention}>
-  ${statusText}
-</schmancy-badge>
-```
+# schmancy-badge
+
+> Versatile badge for status indicators, labels, and counts with color variants and shapes.
+
+## Usage
+```html
+<schmancy-badge color="success">Active</schmancy-badge>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| color | `'primary'\|'secondary'\|'tertiary'\|'success'\|'warning'\|'error'\|'neutral'\|'surface'` | `'primary'` | Color variant |
+| size | `'xs'\|'sm'\|'md'\|'lg'` | `'md'` | Badge size |
+| shape | `'rounded'\|'pill'\|'square'` | `'pill'` | Badge shape |
+| outlined | boolean | `false` | Outlined style (transparent background) |
+| icon | string | `''` | Material icon name |
+| pulse | boolean | `false` | Pulse animation for attention |
+
+## Slots
+| Slot | Description |
+|------|-------------|
+| default | Badge text content |
+| icon | Custom icon content |
+
+## Examples
+```html
+<!-- Outlined badge -->
+<schmancy-badge color="error" outlined>Overdue</schmancy-badge>
+
+<!-- With icon -->
+<schmancy-badge color="success" icon="check_circle">Verified</schmancy-badge>
+
+<!-- Pulsing notification badge -->
+<schmancy-badge color="error" size="sm" pulse>3</schmancy-badge>
+
+<!-- Square shape -->
+<schmancy-badge color="neutral" shape="square">Draft</schmancy-badge>
+```
+
+**Tag aliases:** `<sch-badge>` (backward compatible)