@mhmo91/schmancy 0.4.76 → 0.4.78

package/ai/chips.md

@@ -1,175 +1,397 @@
 # Schmancy Chips - AI Reference
 
+## 🎯 Chip Type Behavior Matrix
+
+Understanding the behavioral differences between chip types is crucial for proper implementation:
+
+| Chip Type | Has Selected State | Click Behavior | Primary Purpose | Remove Button |
+|-----------|-------------------|----------------|-----------------|---------------|
+| **Filter** | ✅ Yes (toggles) | Toggles selected state on/off | Filtering content, toggling options | ❌ No |
+| **Assist** | ❌ No | Triggers an action (no state change) | Smart actions, automation, help | ❌ No |
+| **Input** | ❌ No | No default behavior (custom action) | Representing user data/selections | ✅ Optional |
+| **Suggestion** | ❌ No | Triggers an action (no state change) | Quick recommendations, shortcuts | ❌ No |
+
+### ⚠️ Important Behavioral Notes
+
+- **ONLY Filter chips have a selected state** - They toggle on/off to filter content
+- **Assist/Suggestion chips trigger actions** - They don't change state, they perform operations
+- **Input chips represent data** - They show user selections and can be removed
+- **Default type is 'filter'** - For backward compatibility with existing code
+
+### 🔧 Pure Schmancy Implementation
+
+This is a pure Schmancy implementation that:
+- ✅ **No Material Design imports** - Built entirely with Lit, Tailwind CSS, and RxJS
+- ✅ **Full Material Design 3 compliance** - Maintains all MD3 behaviors and styling
+- ✅ **Reactive architecture** - Uses RxJS for state management and event handling
+- ✅ **Tailwind styling** - All styling done with Tailwind classes, no CSS-in-JS
+
+## Material Web Aligned API
+
+The schmancy chips component fully supports Material Design 3 chip specifications with all four chip types:
+
+- **filter**: Toggle chips for filtering content (selectable) - default type
+- **assist**: Action chips for prompting smart/automated actions
+- **input**: Removable chips for user inputs and data
+- **suggestion**: Chips for quick suggestions and recommendations
+
+## Usage Examples
+
 ```js
-// Single Chip - now accepts ANY content!
-<schmancy-chip
-  value="chip-value"
-  selected?
-  readOnly?
-  disabled?
-  @change=${handleChange}>
-  Any content here
+// MATERIAL WEB COMPLIANT CHIP TYPES
+
+// Assist Chip - For actions and navigation
+<schmancy-chip type="assist" value="share">
+  <schmancy-icon slot="icon">share</schmancy-icon>
+  Share
+</schmancy-chip>
+
+// Filter Chip - Toggleable filters (default type for backward compatibility)
+<schmancy-chip type="filter" value="starred" selected>
+  <schmancy-icon slot="icon">star</schmancy-icon>
+  Starred
 </schmancy-chip>
 
-// Simple text chip
+// Input Chip - User inputs with optional remove button
+<schmancy-chip type="input" value="john-doe" removable @remove=${handleRemove}>
+  <schmancy-icon slot="icon">person</schmancy-icon>
+  John Doe
+</schmancy-chip>
+
+// Suggestion Chip - Quick suggestions
+<schmancy-chip type="suggestion" value="reply">
+  <schmancy-icon slot="icon">reply</schmancy-icon>
+  Reply
+</schmancy-chip>
+
+// ENHANCED PROPERTIES
+
+// Elevated chips for more emphasis
+<schmancy-chip type="assist" elevated>
+  <schmancy-icon slot="icon">add</schmancy-icon>
+  Create New
+</schmancy-chip>
+
+// Soft-disabled for partial interaction
+<schmancy-chip type="filter" soft-disabled>
+  Premium Only
+</schmancy-chip>
+
+// Avatar support for input chips
+<schmancy-chip type="input" avatar removable>
+  <img slot="icon" src="user.jpg" alt="User">
+  Alice Smith
+</schmancy-chip>
+
+// BACKWARD COMPATIBLE USAGE (still works!)
+
+// Simple text chip (defaults to filter type)
 <schmancy-chip value="javascript">
   JavaScript
 </schmancy-chip>
 
-// Chip with icon
+// Chip with icon in content (legacy style - still supported)
 <schmancy-chip value="edit">
   <schmancy-icon>edit</schmancy-icon>
   Edit
 </schmancy-chip>
 
-// Chip with avatar and text
+// Icon slot usage (recommended for proper Material Web alignment)
+<schmancy-chip value="star" selected>
+  <schmancy-icon slot="icon">star</schmancy-icon>
+  Starred
+</schmancy-chip>
+
+// Complex content with Tailwind classes
 <schmancy-chip value="user1" class="flex items-center gap-2">
   <schmancy-avatar size="sm">JD</schmancy-avatar>
   <schmancy-typography type="body" token="sm">john.doe@example.com</schmancy-typography>
 </schmancy-chip>
 
-// Chip with badge
-<schmancy-chip value="notifications" class="flex items-center gap-2">
-  <schmancy-icon>notifications</schmancy-icon>
-  <span>Notifications</span>
-  <schmancy-badge>5</schmancy-badge>
-</schmancy-chip>
+// CHIPS CONTAINER
 
-// Chips Container - Single Selection
+// Single Selection Mode - Automatically detected from .value property
 <schmancy-chips
   .value=${selectedValue}
   @change=${handleSelectionChange}>
-  <schmancy-chip value="1">Option 1</schmancy-chip>
-  <schmancy-chip value="2">Option 2</schmancy-chip>
-  <schmancy-chip value="3">Option 3</schmancy-chip>
+  <schmancy-chip type="filter" value="1">Option 1</schmancy-chip>
+  <schmancy-chip type="filter" value="2">Option 2</schmancy-chip>
+  <schmancy-chip type="filter" value="3">Option 3</schmancy-chip>
 </schmancy-chips>
 
-// Chips Container - Multiple Selection
+// Multiple Selection Mode - Automatically detected from .values property
 <schmancy-chips
-  multi
   .values=${selectedValues}
   @change=${handleSelectionChange}>
-  <schmancy-chip value="red">Red</schmancy-chip>
-  <schmancy-chip value="green">Green</schmancy-chip>
-  <schmancy-chip value="blue">Blue</schmancy-chip>
+  <schmancy-chip type="filter" value="red">Red</schmancy-chip>
+  <schmancy-chip type="filter" value="green">Green</schmancy-chip>
+  <schmancy-chip type="filter" value="blue">Blue</schmancy-chip>
 </schmancy-chips>
 
-// Horizontal scrolling chips
-<schmancy-chips wrap="false">
-  <schmancy-chip value="mon">Monday</schmancy-chip>
-  <schmancy-chip value="tue">Tuesday</schmancy-chip>
-  <schmancy-chip value="wed">Wednesday</schmancy-chip>
-  <schmancy-chip value="thu">Thursday</schmancy-chip>
-  <schmancy-chip value="fri">Friday</schmancy-chip>
+// Layout-only Mode - No selection management when neither property is used
+<schmancy-chips>
+  <schmancy-chip type="assist" value="share">Share</schmancy-chip>
+  <schmancy-chip type="assist" value="save">Save</schmancy-chip>
 </schmancy-chips>
 
-// Chip Properties
-value: string           // Value for selection purposes
-selected: boolean       // Whether the chip is selected
-readOnly: boolean       // Makes chip non-interactive (no selection change)
-disabled: boolean       // Disable the chip (no interaction at all)
-
-// Chips Container Properties
-multi: boolean          // Enable multiple selection mode
-value: string           // Selected value (single selection)
-values: string[]        // Selected values (multiple selection)
-wrap: boolean           // Whether chips wrap to new lines (default: true)
-
-// Chip Events
-@click   // Fires when chip is clicked
-@change  // Fires when selection changes, with { detail: { value: string, selected: boolean } }
-
-// Chips Container Events
-@change  // Fires when selection changes, with detail being string (single) or string[] (multi)
-
-// Examples
-// Basic chips with emoji and Material icons
-<div>
-  <schmancy-chip value="basic">Basic</schmancy-chip>
-  <schmancy-chip value="javascript" icon="📝">JavaScript</schmancy-chip>
-  <schmancy-chip value="settings" icon="settings">Settings</schmancy-chip>
-  <schmancy-chip value="star" icon="star">Starred</schmancy-chip>
-  <schmancy-chip value="delete" icon="delete">Delete</schmancy-chip>
-</div>
-
-// User chips with avatars - now fully supported!
-<div class="flex flex-wrap gap-2">
-  <schmancy-chip value="user1" class="flex items-center gap-2">
-    <schmancy-avatar size="sm">JD</schmancy-avatar>
-    <schmancy-typography type="body" token="sm">john.doe@example.com</schmancy-typography>
+// Mixed chip types in container
+<schmancy-chips @remove=${handleRemove}>
+  <schmancy-chip type="input" value="tag1" removable>
+    <schmancy-icon slot="icon">label</schmancy-icon>
+    Important
   </schmancy-chip>
-  
-  <schmancy-chip value="user2" selected class="flex items-center gap-2">
-    <schmancy-avatar size="sm">AS</schmancy-avatar>
-    <schmancy-typography type="body" token="sm">alice.smith@example.com</schmancy-typography>
+  <schmancy-chip type="assist" value="add">
+    <schmancy-icon slot="icon">add</schmancy-icon>
+    Add Tag
   </schmancy-chip>
-</div>
-
-// Single selection chips
-<schmancy-chips
-  .value=${selectedSize}
-  @change=${(e) => selectedSize = e.detail}>
-  <schmancy-chip value="sm">Small</schmancy-chip>
-  <schmancy-chip value="md">Medium</schmancy-chip>
-  <schmancy-chip value="lg">Large</schmancy-chip>
 </schmancy-chips>
 
-// Multiple selection chips
-<schmancy-chips
-  multi
-  .values=${selectedToppings}
-  @change=${(e) => selectedToppings = e.detail}>
-  <schmancy-chip value="cheese">Cheese</schmancy-chip>
-  <schmancy-chip value="pepperoni">Pepperoni</schmancy-chip>
-  <schmancy-chip value="mushrooms">Mushrooms</schmancy-chip>
-  <schmancy-chip value="onions">Onions</schmancy-chip>
-  <schmancy-chip value="peppers">Peppers</schmancy-chip>
+// Horizontal scrolling chips
+<schmancy-chips wrap="false">
+  <schmancy-chip type="filter" value="mon">Monday</schmancy-chip>
+  <schmancy-chip type="filter" value="tue">Tuesday</schmancy-chip>
+  <schmancy-chip type="filter" value="wed">Wednesday</schmancy-chip>
+  <schmancy-chip type="filter" value="thu">Thursday</schmancy-chip>
+  <schmancy-chip type="filter" value="fri">Friday</schmancy-chip>
 </schmancy-chips>
+```
 
-// Date selector with horizontal scrolling
-<schmancy-chips
-  wrap="false"
-  .value=${selectedDate}
-  @change=${(e) => selectedDate = e.detail}>
-  <schmancy-chip value="2024-01-15">Mon 15</schmancy-chip>
-  <schmancy-chip value="2024-01-16">Tue 16</schmancy-chip>
-  <schmancy-chip value="2024-01-17">Wed 17</schmancy-chip>
-  <schmancy-chip value="2024-01-18">Thu 18</schmancy-chip>
-  <schmancy-chip value="2024-01-19">Fri 19</schmancy-chip>
-  <schmancy-chip value="2024-01-20">Sat 20</schmancy-chip>
-  <schmancy-chip value="2024-01-21">Sun 21</schmancy-chip>
+## Component Properties
+
+### schmancy-chip
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `type` | `'assist' \| 'filter' \| 'input' \| 'suggestion'` | `'filter'` | Chip type (Material Web spec) |
+| `value` | `string` | `''` | Value for selection/identification |
+| `selected` | `boolean` | `false` | Whether chip is selected (ONLY applies to filter chips) |
+| `label` | `string` | `''` | Text label (alternative to slot content) |
+| `icon` | `string` | `''` | Legacy emoji/icon support |
+| `avatar` | `boolean` | `false` | Enable avatar mode (input chips) |
+| `elevated` | `boolean` | `false` | Add elevation shadow |
+| `soft-disabled` | `boolean` | `false` | Partial disable state |
+| `removable` | `boolean` | `false` | Show remove button (input chips) |
+| `readOnly` | `boolean` | `false` | Make chip non-interactive |
+| `disabled` | `boolean` | `false` | Fully disable chip |
+
+### schmancy-chips
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `multi` | `boolean` | `false` | **[Deprecated]** Use `.values` for multi-selection or `.value` for single-selection |
+| `value` | `string` | `''` | Selected value (automatically enables single-selection mode) |
+| `values` | `string[]` | `[]` | Selected values (automatically enables multi-selection mode) |
+| `wrap` | `boolean` | `true` | Whether chips wrap to new lines |
+
+#### 🎯 Automatic Mode Detection
+
+The `schmancy-chips` container now **automatically detects** the selection mode based on which property you use:
+
+- **`.values` array** → Automatically enables **multi-selection mode**
+- **`.value` string** → Automatically enables **single-selection mode**
+- **Neither property** → Layout-only mode (no selection management)
+
+The deprecated `multi` property is kept for backward compatibility but is no longer needed.
+
+## Events
+
+### schmancy-chip Events
+
+- `@change` - Fires when selection changes (ONLY for filter chips)
+  - Detail: `{ value: string, selected: boolean }`
+  - Note: Only filter chips emit this event when toggling selected state
+- `@remove` - Fires when remove button clicked (ONLY for input chips with `removable` prop)
+  - Detail: `{ value: string }`
+  - Note: Requires `type="input"` and `removable` property
+- `@click` - Standard click event (all chip types)
+  - For assist/suggestion chips: Use this to trigger actions
+  - For filter chips: Internally handled to toggle selection
+  - For input chips: Use for custom click handling
+
+### schmancy-chips Events
+
+- `@change` - Fires when selection changes
+  - Detail: `string` (single mode) or `string[]` (multi mode)
+- `@remove` - Bubbled from child chip remove events
+  - Detail: `{ value: string }`
+
+## Slots
+
+### Icon Slot (Recommended)
+Use the `icon` slot for proper Material Web icon alignment:
+
+```html
+<schmancy-chip value="star">
+  <schmancy-icon slot="icon">star</schmancy-icon>
+  Starred
+</schmancy-chip>
+```
+
+### Default Slot
+The default slot accepts any content, including text, icons, and complex layouts:
+
+```html
+<schmancy-chip value="complex">
+  <div class="flex items-center gap-2">
+    <schmancy-avatar size="sm">JD</schmancy-avatar>
+    <span>John Doe</span>
+    <schmancy-badge>5</schmancy-badge>
+  </div>
+</schmancy-chip>
+```
+
+## Real-World Examples
+
+### Tag Input with Remove
+```js
+<schmancy-chips @remove=${handleTagRemove}>
+  ${tags.map(tag => html`
+    <schmancy-chip
+      type="input"
+      value=${tag.id}
+      removable>
+      <schmancy-icon slot="icon">label</schmancy-icon>
+      ${tag.name}
+    </schmancy-chip>
+  `)}
+  <schmancy-chip type="assist" value="add" @click=${addTag}>
+    <schmancy-icon slot="icon">add</schmancy-icon>
+    Add Tag
+  </schmancy-chip>
 </schmancy-chips>
+```
 
-// Category filters
-<schmancy-chips
-  multi
-  .values=${selectedCategories}
-  @change=${(e) => selectedCategories = e.detail}>
-  <schmancy-chip value="electronics" icon="💻">Electronics</schmancy-chip>
-  <schmancy-chip value="clothing" icon="👕">Clothing</schmancy-chip>
-  <schmancy-chip value="books" icon="📚">Books</schmancy-chip>
-  <schmancy-chip value="home" icon="🏠">Home & Garden</schmancy-chip>
-  <schmancy-chip value="sports" icon="⚽">Sports</schmancy-chip>
+### Filter Bar with Multiple Types
+```js
+<schmancy-chips .values=${activeFilters}>
+  <schmancy-chip type="filter" value="in-stock">
+    <schmancy-icon slot="icon">inventory</schmancy-icon>
+    In Stock
+  </schmancy-chip>
+  <schmancy-chip type="filter" value="on-sale">
+    <schmancy-icon slot="icon">sell</schmancy-icon>
+    On Sale
+  </schmancy-chip>
+  <schmancy-chip type="filter" value="free-shipping">
+    <schmancy-icon slot="icon">local_shipping</schmancy-icon>
+    Free Shipping
+  </schmancy-chip>
 </schmancy-chips>
+```
 
-// Skills/Tags selection
-<schmancy-chips
-  multi
-  .values=${selectedSkills}
-  @change=${(e) => selectedSkills = e.detail}>
-  ${availableSkills.map(skill => html`
-    <schmancy-chip 
-      value=${skill.id}
-      icon=${skill.icon}>
-      ${skill.name}
+### User Selection with Avatars
+```js
+<schmancy-chips>
+  ${users.map(user => html`
+    <schmancy-chip
+      type="input"
+      value=${user.id}
+      avatar
+      removable>
+      <img slot="icon" src=${user.avatar} alt=${user.name}>
+      ${user.name}
     </schmancy-chip>
   `)}
 </schmancy-chips>
+```
 
-// Read-only chips display
-<div>
-  <schmancy-chip value="completed" icon="✅" readOnly>Completed</schmancy-chip>
-  <schmancy-chip value="pending" icon="⏳" readOnly>Pending</schmancy-chip>
-  <schmancy-chip value="cancelled" icon="❌" readOnly>Cancelled</schmancy-chip>
+### Action Chips
+```js
+<div class="flex gap-2">
+  <schmancy-chip type="assist" elevated @click=${handleShare}>
+    <schmancy-icon slot="icon">share</schmancy-icon>
+    Share
+  </schmancy-chip>
+  <schmancy-chip type="assist" @click=${handleBookmark}>
+    <schmancy-icon slot="icon">bookmark</schmancy-icon>
+    Save
+  </schmancy-chip>
+  <schmancy-chip type="assist" @click=${handlePrint}>
+    <schmancy-icon slot="icon">print</schmancy-icon>
+    Print
+  </schmancy-chip>
 </div>
-```
+```
+
+### Suggestion Chips
+```js
+<schmancy-chips>
+  <schmancy-chip type="suggestion" value="recently-viewed">
+    <schmancy-icon slot="icon">history</schmancy-icon>
+    Recently Viewed
+  </schmancy-chip>
+  <schmancy-chip type="suggestion" value="recommended">
+    <schmancy-icon slot="icon">thumb_up</schmancy-icon>
+    Recommended
+  </schmancy-chip>
+  <schmancy-chip type="suggestion" value="trending">
+    <schmancy-icon slot="icon">trending_up</schmancy-icon>
+    Trending
+  </schmancy-chip>
+</schmancy-chips>
+```
+
+## Common Mistakes to Avoid
+
+### ❌ Trying to use `selected` on non-filter chips
+```js
+// WRONG - Only filter chips support selected state
+<schmancy-chip type="assist" selected>Help</schmancy-chip>
+<schmancy-chip type="input" selected>Tag</schmancy-chip>
+<schmancy-chip type="suggestion" selected>Tip</schmancy-chip>
+
+// CORRECT - Only use selected with filter type
+<schmancy-chip type="filter" selected>Active Filter</schmancy-chip>
+```
+
+### ❌ Expecting state changes from assist/suggestion chips
+```js
+// WRONG - Expecting assist chip to maintain state
+<schmancy-chip type="assist" @change=${handleChange}>
+  Share
+</schmancy-chip>
+
+// CORRECT - Use click event for actions
+<schmancy-chip type="assist" @click=${handleShare}>
+  Share
+</schmancy-chip>
+```
+
+### ❌ Using remove button on non-input chips
+```js
+// WRONG - Only input chips support removable
+<schmancy-chip type="filter" removable>Filter</schmancy-chip>
+<schmancy-chip type="assist" removable>Action</schmancy-chip>
+
+// CORRECT - Use removable only with input type
+<schmancy-chip type="input" removable @remove=${handleRemove}>
+  User Tag
+</schmancy-chip>
+```
+
+## Migration Guide
+
+### From Legacy to Material Web API
+
+```js
+// OLD (still works for backward compatibility)
+<schmancy-chip value="star" selected icon="">
+  <schmancy-icon>star</schmancy-icon>
+  Starred
+</schmancy-chip>
+
+// NEW (Material Web compliant)
+<schmancy-chip type="filter" value="star" selected>
+  <schmancy-icon slot="icon">star</schmancy-icon>
+  Starred
+</schmancy-chip>
+```
+
+### Key Changes
+1. Add `type` property to explicitly set chip behavior
+2. Use `slot="icon"` for icons to ensure proper placement
+3. Use `removable` property for input chips with remove functionality
+4. Use `elevated` for visual emphasis
+5. Use `soft-disabled` for partial interaction states
+
+All existing code continues to work - the default type is `'filter'` for backward compatibility.