@mhmo91/schmancy 0.7.5 → 0.7.7

package/ai/directives.md

@@ -3,8 +3,11 @@
 ## Quick Start
 
 ```typescript
-import { ripple, color, height, visibility } from '@schmancy/index'
-// Or specific import: import { ripple, color, height, visibility } from '@schmancy/directives'
+import { ripple, color, height, visibility, drag, drop } from '@schmancy/index'
+// Or specific import: import { ripple, color, height, visibility, drag, drop } from '@schmancy/directives'
+
+// Import types
+import type { SchmancyDropEvent } from '@schmancy/index'
 ```
 
 ## Directives Overview
@@ -60,6 +63,28 @@ Lit directives that add common UI behaviors and styling capabilities to any elem
 // When true, removes display style
 ```
 
+### Drag & Drop Directives
+
+```typescript
+// Make element draggable
+<div ${drag(id: string)}></div>
+
+// Make element a drop zone
+<div ${drop(destinationId: string)} @drop=${handleDrop}></div>
+
+// Drop event type
+export type SchmancyDropEvent = CustomEvent<{
+  source: string;      // ID of dragged element
+  destination: string; // ID of drop zone
+}>
+
+// Handle drop event
+const handleDrop = (e: SchmancyDropEvent) => {
+  const { source, destination } = e.detail
+  // Handle the drop...
+}
+```
+
 ## Examples
 
 ### Basic Usage
@@ -100,12 +125,25 @@ Lit directives that add common UI behaviors and styling capabilities to any elem
 </div>
 
 // Animated drawer
-<div 
+<div
   ${height(isOpen ? '300px' : '0')}
   ${visibility(isOpen)}
   class="transition-all duration-300 overflow-hidden">
   Drawer Content
 </div>
+
+// Drag and drop list items
+<div class="space-y-2">
+  ${items.map(item => html`
+    <div
+      ${drag(item.id)}
+      ${drop(item.id)}
+      @drop=${handleReorder}
+      class="p-4 bg-surface-container rounded cursor-grab">
+      ${item.name}
+    </div>
+  `)}
+</div>
 ```
 
 ### Real-World Examples
@@ -155,10 +193,10 @@ render() {
 render() {
   const isDark = this.theme === 'dark'
   return html`
-    <div 
+    <div
       ${color({
-        bgColor: isDark 
-          ? 'var(--schmancy-sys-color-surface-dim)' 
+        bgColor: isDark
+          ? 'var(--schmancy-sys-color-surface-dim)'
           : 'var(--schmancy-sys-color-surface-bright)',
         color: 'var(--schmancy-sys-color-on-surface)'
       })}
@@ -167,6 +205,109 @@ render() {
     </div>
   `
 }
+
+// Warehouse hierarchy management with drag & drop
+@customElement('warehouse-manager')
+class WarehouseManager extends $LitElement() {
+  @state()
+  warehouses: Warehouse[] = []
+
+  private handleWarehouseReparent = (e: SchmancyDropEvent) => {
+    const { source, destination } = e.detail
+
+    // Find the warehouse being dragged and the new parent
+    const warehouse = this.warehouses.find(w => w.id === source)
+    const newParent = this.warehouses.find(w => w.id === destination)
+
+    if (!warehouse || !newParent) return
+
+    // Update the warehouse's parent
+    warehouse.parentID = newParent.id
+
+    // Save to database
+    this.saveWarehouse(warehouse)
+
+    // Notify user
+    this.dispatchEvent(new CustomEvent('warehouse-moved', {
+      detail: { warehouse, newParent }
+    }))
+  }
+
+  render() {
+    return html`
+      <div class="space-y-2">
+        ${repeat(
+          this.warehouses,
+          w => w.id,
+          w => html`
+            <schmancy-surface
+              ${drag(w.id)}
+              ${drop(w.id)}
+              @drop=${this.handleWarehouseReparent}
+              type="containerLow"
+              class="p-4 cursor-grab active:cursor-grabbing">
+              <div class="flex items-center gap-3">
+                <span>${w.emoji || '📦'}</span>
+                <span>${w.name}</span>
+              </div>
+            </schmancy-surface>
+          `
+        )}
+      </div>
+    `
+  }
+}
+
+// Sortable task list
+@customElement('task-list')
+class TaskList extends $LitElement() {
+  @state()
+  tasks: Task[] = []
+
+  private handleTaskReorder = (e: SchmancyDropEvent) => {
+    const { source, destination } = e.detail
+
+    // Find indices
+    const sourceIndex = this.tasks.findIndex(t => t.id === source)
+    const destIndex = this.tasks.findIndex(t => t.id === destination)
+
+    if (sourceIndex === -1 || destIndex === -1) return
+
+    // Reorder array
+    const [movedTask] = this.tasks.splice(sourceIndex, 1)
+    this.tasks.splice(destIndex, 0, movedTask)
+
+    // Trigger re-render
+    this.tasks = [...this.tasks]
+
+    // Persist order
+    this.saveTasks()
+  }
+
+  render() {
+    return html`
+      <div class="space-y-2">
+        ${repeat(
+          this.tasks,
+          t => t.id,
+          t => html`
+            <div
+              ${drag(t.id)}
+              ${drop(t.id)}
+              @drop=${this.handleTaskReorder}
+              class="p-4 bg-surface-container rounded cursor-grab hover:bg-surface-containerHigh transition-colors">
+              <schmancy-checkbox
+                ?checked=${t.completed}
+                @change=${() => this.toggleTask(t)}>
+                ${t.title}
+              </schmancy-checkbox>
+            </div>
+          `
+        )}
+      </div>
+    `
+  }
+}
 ```
 
 ## Implementation Details
@@ -196,6 +337,42 @@ render() {
 - When true: removes display style
 - Preserves other display values
 
+### Drag & Drop Directives
+
+**Drag Directive:**
+- Sets `draggable="true"` on the element
+- Sets cursor to `grab` (changes to `grabbing` during drag)
+- Uses HTML5 Drag and Drop API
+- Stores dragged element ID in global variable for access by drop zones
+- Transfers data via `dataTransfer` API
+- Implements `dragstart` and `dragend` event handlers
+- Uses RxJS for event handling with automatic cleanup
+- Prevents event bubbling with `stopPropagation()`
+
+**Drop Directive:**
+- Enables element as a drop zone
+- Provides visual feedback during drag-over:
+  - Dashed outline in tertiary color
+  - Drop shadow effect for emphasis
+- Prevents dropping element onto itself
+- Cleans up visual feedback on drag leave
+- Dispatches custom `SchmancyDropEvent` with source and destination IDs
+- Event bubbles up for easy handling
+- Uses RxJS to manage `dragover`, `dragleave`, and `drop` events
+- Automatically calls `preventDefault()` to enable dropping
+
+**Global State Management:**
+- Uses module-level `currentDragSourceId` variable
+- Tracks which element is being dragged
+- Allows drop zones to prevent self-drop
+- Cleared automatically when drag ends
+
+**RxJS Integration:**
+- All event listeners use RxJS `fromEvent()`
+- Cleanup via `takeUntil(this.destroy$)` in `disconnected()`
+- Combines multiple event streams with `merge()`
+- Proper memory management and no event listener leaks
+
 ## Best Practices
 
 1. **Ripple Usage**: Best on interactive elements (buttons, cards, list items)
@@ -203,6 +380,13 @@ render() {
 3. **Height Animations**: Combine with CSS transitions for smooth effects
 4. **Visibility**: Use for simple show/hide; consider v-show for more control
 5. **Performance**: Directives are lightweight but avoid excessive updates
+6. **Drag IDs**: Always use unique, stable IDs (not array indices that can change)
+7. **Drop Zones**: Make drop zones visually distinct so users know where to drop
+8. **Accessibility**: Drag & drop isn't accessible - provide alternative keyboard navigation
+9. **Touch Devices**: HTML5 drag/drop has limited mobile support - consider alternatives for mobile
+10. **Visual Feedback**: Use cursor changes and hover states to indicate draggable elements
+11. **Prevent Self-Drop**: Both directives automatically prevent dropping onto self
+12. **Event Bubbling**: Drop events bubble up - handle at parent level if needed
 
 ## Common Pitfalls
 
@@ -210,6 +394,14 @@ render() {
 - **Color Specificity**: Inline styles from color directive override CSS classes
 - **Height Auto**: Transitioning to/from 'auto' requires special handling
 - **Visibility vs Display**: Visibility directive uses display, not visibility property
+- **Drag Ghost Image**: Browser creates default ghost image - customize with `setDragImage()`
+- **Mobile Support**: Touch events don't trigger HTML5 drag/drop - polyfill required
+- **Z-Index Issues**: Dragged element may appear behind other elements
+- **Drop Validation**: Always validate source/destination IDs before processing
+- **Memory Leaks**: Directives handle cleanup automatically via RxJS `takeUntil()`
+- **Multiple Drops**: If element has both `drag()` and `drop()`, ensure IDs match intent
+- **Event Order**: `dragstart` → `dragover` (repeated) → `drop` → `dragend`
+- **DataTransfer**: Data is only accessible in `drop` event, not `dragover`
 
 ## Related Components
 
@@ -230,9 +422,24 @@ color(config: {
   color?: string;
 }): DirectiveResult
 
-// Height directive  
+// Height directive
 height(value: string | number): DirectiveResult
 
 // Visibility directive
 visibility(isVisible: boolean): DirectiveResult
+
+// Drag directive
+drag(id: string): DirectiveResult
+
+// Drop directive
+drop(destinationId: string): DirectiveResult
+
+// Drop event type
+export type SchmancyDropEvent = CustomEvent<{
+  source: string;      // ID of the dragged element
+  destination: string; // ID of the drop zone
+}>
+
+// Example event handler signature
+type DropHandler = (e: SchmancyDropEvent) => void
 ```

package/ai/typewriter.md

@@ -1,6 +1,6 @@
 # Typewriter Component
 
-An engaging text animation component that simulates typing effects with customizable speed, delays, and advanced sequencing capabilities.
+An engaging text animation component that simulates typing effects with customizable speed, delays, and advanced sequencing capabilities. Features a simple API for cycling through text with automatic character deletion.
 
 ## Quick Start
 
@@ -10,18 +10,20 @@ An engaging text animation component that simulates typing effects with customiz
   Hello, World! This text will be typed out character by character.
 </schmancy-typewriter>
 
-<!-- With custom speed -->
-<schmancy-typewriter speed="30" delay="500">
-  Fast typing with a delay before starting.
+<!-- Cycling through words (auto-calculates delete counts) -->
+<schmancy-typewriter>
+  We are <span cycle="developers | designers | innovators"></span>
 </schmancy-typewriter>
 
-<!-- With actions -->
-<schmancy-typewriter>
-  Type this first.
-  <span action="pause" value="1000"></span>
-  Then type this after a pause.
-  <span action="delete" value="10"></span>
-  And finally this!
+<!-- With custom speed and cursor -->
+<schmancy-typewriter speed="30" delay="500" cursorChar="|">
+  Fast typing with a blinking cursor.
+</schmancy-typewriter>
+
+<!-- Infinite loop -->
+<schmancy-typewriter loop>
+  This will type and delete forever!
+  <span cycle="Amazing | Incredible | Fantastic"></span>
 </schmancy-typewriter>
 ```
 
@@ -32,9 +34,11 @@ An engaging text animation component that simulates typing effects with customiz
 | `speed` | `number` | `50` | Typing speed (ms per character) |
 | `delay` | `number` | `0` | Initial delay before typing starts |
 | `autoStart` | `boolean` | `true` | Start typing automatically |
-| `cursorChar` | `string` | `''` | Custom cursor character |
+| `cursorChar` | `string` | `''` | Custom cursor character (empty = no cursor) |
 | `deleteSpeed` | `number` | `25` | Speed for deletion (ms per character) |
+| `cyclePause` | `number` | `1500` | Default pause between cycle items (ms) |
 | `once` | `boolean` | `true` | Only animate once per session |
+| `loop` | `boolean` | `false` | Loop animation infinitely (overrides `once`) |
 
 ## Events
 
@@ -49,12 +53,12 @@ element.addEventListener('typeit-complete', () => {
 
 ## Examples
 
-### Hero Section
+### Hero Section with Cycling
 ```html
 <div class="hero">
   <h1>
     <schmancy-typewriter speed="100" delay="300">
-      Welcome to the Future
+      Welcome to the <span cycle="Future | Innovation | Revolution"></span>
     </schmancy-typewriter>
   </h1>
   <p>
@@ -65,6 +69,17 @@ element.addEventListener('typeit-complete', () => {
 </div>
 ```
 
+### Rotating Value Propositions
+```html
+<schmancy-typewriter speed="80" cyclePause="1200">
+  Building systems that are
+  <br />
+  <span cycle="Trustless | Permissionless | Transparent | Borderless | Resilient" pause="1500"></span>
+  <br />
+  empowering everyone to operate freely.
+</schmancy-typewriter>
+```
+
 ### Multi-line Typing
 ```html
 <schmancy-typewriter speed="60">
@@ -87,21 +102,20 @@ element.addEventListener('typeit-complete', () => {
 </div>
 ```
 
-### Dynamic Typing Sequence
+### Product Features Carousel
 ```html
-<schmancy-typewriter>
-  We are
-  <span action="pause" value="500"></span>
-  developers
-  <span action="delete" value="10"></span>
-  designers
-  <span action="delete" value="9"></span>
-  innovators
-  <span action="pause" value="1000"></span>
-  !
+<schmancy-typewriter loop cursorChar="_">
+  <span cycle="Lightning Fast ⚡ | Fully Typed 📘 | Zero Config 🎯 | Production Ready 🚀"></span>
 </schmancy-typewriter>
 ```
 
+### Dynamic Job Titles
+```html
+<h2>
+  We're hiring <span cycle="Frontend Developers | Backend Engineers | UI/UX Designers | DevOps Specialists"></span>
+</h2>
+```
+
 ### Code Tutorial
 ```html
 <schmancy-typewriter speed="40">
@@ -115,20 +129,72 @@ element.addEventListener('typeit-complete', () => {
 </schmancy-typewriter>
 ```
 
+## Cycling API (NEW!)
+
+The `cycle` attribute makes it effortless to rotate through text with **automatic character deletion**. No need to manually count characters!
+
+### Basic Usage
+
+```html
+<!-- Simple cycling -->
+<span cycle="Option 1 | Option 2 | Option 3"></span>
+
+<!-- With custom pause duration -->
+<span cycle="Fast | Quick | Rapid" pause="800"></span>
+
+<!-- In context -->
+<schmancy-typewriter>
+  We are <span cycle="developers | designers | innovators"></span>
+</schmancy-typewriter>
+```
+
+### Cycle Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `cycle` | `string` | Pipe-separated list of text items to cycle through |
+| `pause` | `number` | Override default pause between items (milliseconds) |
+
+### Benefits
+
+- ✅ **Auto-calculated deletes** - no manual character counting
+- ✅ **Clean syntax** - just list your items with `|` separator
+- ✅ **Consistent timing** - uses `cyclePause` property or custom `pause`
+- ✅ **Works with `loop`** - infinite cycling made simple
+
+### Advanced Cycling
+
+```html
+<!-- Hero headline that cycles forever -->
+<schmancy-typewriter loop cyclePause="2000">
+  <h1>Welcome to <span cycle="the Future | Innovation | Tomorrow"></span></h1>
+</schmancy-typewriter>
+
+<!-- Mixed static and cycling text -->
+<schmancy-typewriter>
+  Our product is
+  <span action="pause" value="500"></span>
+  <span cycle="Fast ⚡ | Secure 🔒 | Reliable ✅ | Modern 🚀" pause="1800"></span>
+  for your business.
+</schmancy-typewriter>
+```
+
 ## Actions System
 
-Special action elements control typing behavior:
+Special action elements for fine-grained control:
 
 | Action | Value | Description |
 |--------|-------|-------------|
 | `pause` | milliseconds | Pause typing for specified duration |
-| `delete` | character count | Delete specified number of characters |
+| `delete` | character count | Delete specified number of characters (manual) |
 
 ```html
 <span action="pause" value="1000"></span> <!-- 1 second pause -->
-<span action="delete" value="5"></span> <!-- Delete 5 characters -->
+<span action="delete" value="5"></span> <!-- Delete 5 characters manually -->
 ```
 
+**Note:** For cycling text with automatic deletion, use the `cycle` attribute instead!
+
 ## Features
 
 ### Session Memory
@@ -210,8 +276,60 @@ const typeItOptions = {
 
 ## Use Cases
 
-1. **Landing Pages**: Engaging hero text
-2. **Tutorials**: Step-by-step code examples
-3. **Storytelling**: Narrative experiences
-4. **Loading States**: Entertaining wait messages
-5. **Terminal UIs**: Command-line interfaces
+### Perfect for:
+
+1. **Hero Headlines**: Rotating value propositions and key messages
+   ```html
+   <span cycle="Fast | Secure | Reliable"></span>
+   ```
+
+2. **Product Features**: Cycling through benefits and capabilities
+   ```html
+   <span cycle="Zero Config 🎯 | Type-Safe 📘 | Lightning Fast ⚡"></span>
+   ```
+
+3. **Job Postings**: Dynamic role descriptions
+   ```html
+   We're hiring <span cycle="Developers | Designers | Engineers"></span>
+   ```
+
+4. **Testimonials**: Rotating customer quotes
+   ```html
+   <span cycle="Amazing product! | Best tool ever! | Game changer!"></span>
+   ```
+
+5. **Tutorials**: Step-by-step code examples with timing
+6. **Storytelling**: Narrative experiences with dramatic pauses
+7. **Loading States**: Entertaining wait messages that cycle
+8. **Terminal UIs**: Command-line interface simulations
+
+## Migration Guide
+
+### From Manual Deletes to Cycle API
+
+**Before (Manual counting - error prone!):**
+```html
+<schmancy-typewriter>
+  We are
+  developers
+  <span action="delete" value="10"></span>
+  designers
+  <span action="delete" value="9"></span>
+  innovators
+</schmancy-typewriter>
+```
+
+**After (Automatic - clean & simple!):**
+```html
+<schmancy-typewriter>
+  We are <span cycle="developers | designers | innovators"></span>
+</schmancy-typewriter>
+```
+
+### Benefits of the New API
+
+- 🚫 **No more counting characters** - automatic deletion
+- ✨ **Cleaner markup** - one line instead of many
+- 🛡️ **Less error-prone** - no typos in character counts
+- 🔄 **Easy updates** - just add/remove words from the list
+- 🎨 **Better readability** - see all options at a glance