@mhmo91/schmancy 0.8.6 → 0.9.3

package/ai/teleport.md

@@ -1,197 +1,55 @@
-# Teleport Component
+# schmancy-teleport
 
-An advanced component that enables smooth FLIP (First, Last, Invert, Play) animations for elements transitioning between different DOM positions.
-
-## Quick Start
+> Move DOM between locations with a FLIP-animated transition. Two instances sharing an `id` handshake via broadcast events — when one mounts, it finds the other and flies the content between them.
 
+## Usage
 ```html
-<!-- Source element -->
-<schmancy-teleport id="user-avatar">
-  <schmancy-avatar src="/user.jpg" name="John Doe"></schmancy-avatar>
+<!-- Start position -->
+<schmancy-teleport id="hero-image">
+  <img src="portrait.jpg" alt="" />
 </schmancy-teleport>
 
-<!-- Target location (different part of DOM) -->
-<schmancy-teleport id="user-avatar">
-  <schmancy-avatar src="/user.jpg" name="John Doe"></schmancy-avatar>
-</schmancy-teleport>
+<!-- Later, in a different view -->
+<schmancy-teleport id="hero-image"></schmancy-teleport>
 ```
 
-## Properties
+When the second instance mounts, the image smoothly animates from its old bounding rect to the new one.
 
+## Properties
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `id` | `string` | - | **Required** - Unique identifier for teleportation pair |
-| `uuid` | `number` | `random` | Auto-generated unique instance ID |
-| `delay` | `number` | `0` | Animation delay in milliseconds |
-
-## How It Works
+| `id` | string | **required** | Shared identifier between source and target |
+| `uuid` | number | auto | Instance UUID for disambiguation (read-only) |
+| `delay` | number | `0` | Delay before teleporting (ms) |
 
-The teleport component uses a sophisticated event system to coordinate animations:
+## Discovery Events
+The service broadcasts on `window`:
+- `FINDING_MORTIES` — "is anyone mounted with id X?"
+- `HERE_RICKY` — instances reply with self reference
+- `WhereAreYouRicky` / `HereMorty` — instance-to-instance handshake
 
-1. **Discovery Phase**: Components with same `id` find each other
-2. **Position Tracking**: Monitors element positions using ResizeObserver
-3. **FLIP Animation**: Smoothly animates between positions
-4. **State Management**: Maintains teleportation state across the app
+Uses RxJS with a race/throwIfEmpty pattern to handle missing counterparts gracefully.
 
-## Examples
-
-### Page Transition Animation
+## Typical Pattern — route transitions
 ```html
 <!-- List view -->
-<schmancy-list>
-  ${items.map(item => html`
-    <schmancy-list-item @click="${() => selectItem(item)}">
-      <schmancy-teleport id="item-${item.id}">
-        <schmancy-card>
-          <img src="${item.thumbnail}" />
-          <h3>${item.title}</h3>
-        </schmancy-card>
-      </schmancy-teleport>
-    </schmancy-list-item>
-  `)}
-</schmancy-list>
-
-<!-- Detail view -->
-${selectedItem ? html`
-  <div class="detail-view">
-    <schmancy-teleport id="item-${selectedItem.id}">
-      <schmancy-card>
-        <img src="${selectedItem.thumbnail}" />
-        <h3>${selectedItem.title}</h3>
-        <p>${selectedItem.description}</p>
-      </schmancy-card>
-    </schmancy-teleport>
-  </div>
-` : ''}
-```
-
-### Navigation Avatar Animation
-```html
-<!-- Collapsed navbar -->
-<nav class="navbar-collapsed">
-  <schmancy-teleport id="nav-user">
-    <schmancy-avatar size="sm" src="/user.jpg"></schmancy-avatar>
-  </schmancy-teleport>
-</nav>
-
-<!-- Expanded sidebar -->
-<aside class="sidebar-expanded">
-  <schmancy-teleport id="nav-user">
-    <div class="user-profile">
-      <schmancy-avatar size="lg" src="/user.jpg"></schmancy-avatar>
-      <h3>John Doe</h3>
-      <p>john@example.com</p>
-    </div>
-  </schmancy-teleport>
-</aside>
-```
-
-### Tab Content Transitions
-```html
-<!-- Tab headers -->
-<schmancy-tabs>
-  ${tabs.map(tab => html`
-    <schmancy-tab>
-      <schmancy-teleport id="tab-icon-${tab.id}">
-        <schmancy-icon>${tab.icon}</schmancy-icon>
-      </schmancy-teleport>
-      ${tab.label}
-    </schmancy-tab>
-  `)}
-</schmancy-tabs>
-
-<!-- Tab content -->
-<div class="tab-content">
-  <schmancy-teleport id="tab-icon-${activeTab.id}">
-    <schmancy-icon size="xl">${activeTab.icon}</schmancy-icon>
+${repeat(items, item => item.id, item => html`
+  <schmancy-teleport id=${`card-${item.id}`}>
+    <schmancy-card @click=${() => router.push(`/item/${item.id}`)}>
+      <img src=${item.thumbnail} />
+    </schmancy-card>
   </schmancy-teleport>
-  <h2>${activeTab.title}</h2>
-  <div>${activeTab.content}</div>
-</div>
-```
-
-## Event System
+`)}
 
-The component uses custom events for coordination:
-
-### Internal Events
-- `WhereAreYouRicky`: Discovery broadcast
-- `HereMorty`: Response to discovery
-- `FINDING_MORTIES`: Global search event
-- `HERE_RICKY`: Component announcement
-
-## Service Integration
-
-The teleport system uses a central service for state management:
-
-```typescript
-// Access active teleportations
-import { teleportationService } from '@schmancy/index';
-// Or specific import: import { teleportationService } from '@schmancy/teleport';
-
-// Get current positions
-const positions = teleportationService.activeTeleportations;
-
-// Subscribe to animations
-teleportationService.flipRequests.subscribe(({ from, to }) => {
-  console.log('Animating from', from.rect, 'to', to.rect);
-});
-```
-
-## Advanced Features
-
-### Position Watching
-Uses `watchElementRect` to monitor element position changes:
-- Handles resize events
-- Tracks DOM mutations
-- Updates on scroll
-
-### FLIP Animation
-Implements the FLIP technique for performant animations:
-- **F**irst: Record initial position
-- **L**ast: Record final position
-- **I**nvert: Calculate the difference
-- **P**lay: Animate to final position
-
-### Visibility Management
-- Initially hidden until position calculated
-- Prevents layout jumps
-- Smooth appearance after teleportation
-
-## Performance Considerations
-
-1. **Unique IDs**: Ensure IDs are unique per teleportation pair
-2. **Cleanup**: Components automatically cleanup on disconnect
-3. **Debouncing**: Position updates are optimized
-4. **Observer Management**: Efficient use of ResizeObserver
-
-## Debugging
-
-Enable debug mode in development:
-```javascript
-// The component has built-in debugging
-debugging = import.meta.env.DEV ? true : false
+<!-- Detail view -->
+<schmancy-teleport id=${`card-${this.params.id}`}></schmancy-teleport>
 ```
 
-## Best Practices
-
-1. **Unique IDs**: Always use unique, stable IDs
-2. **Matching Content**: Ensure teleported content is identical
-3. **Performance**: Limit active teleportations
-4. **Transitions**: Combine with route transitions
-5. **Fallbacks**: Handle cases where pairs don't exist
-
-## Related Components
-
-- [Avatar](./avatar.md) - Common teleportation target
-- [Card](./card.md) - Container animations
-- [Icon](./icons.md) - Icon transitions
-- [Area](./area.md) - Route-based animations
-
-## Use Cases
+## Notes
+- Uses `watchElementRect` (ResizeObserver + scroll tracking) to keep source/target in sync.
+- Animation uses the FLIP technique: capture first rect, invert on mount, play to final.
+- All subscriptions clean up via `takeUntil(this.disconnecting)`.
+- Each teleport pair must share a unique `id` string.
 
-1. **Shared Element Transitions**: Seamless page transitions
-2. **Master-Detail Views**: List to detail animations
-3. **Navigation Morphing**: Navbar state changes
-4. **Tab Transitions**: Content switching animations
-5. **Gallery Effects**: Image zoom transitions
+## See Also
+- For programmatic teleportation from JS: import `teleportationService` from `@mhmo91/schmancy/teleport`.

package/ai/textarea.md

@@ -1,232 +1,48 @@
-# Schmancy Textarea - AI Reference
-
-```js
-// Basic Textarea
-<schmancy-textarea
-  name="textarea-name"
-  label="Textarea Label"
-  value="Initial text"
-  placeholder="Enter text here..."
-  rows="4"
-  cols="50"
-  maxlength="500"
-  minlength="10"
-  required?
-  disabled?
-  readonly?
-  spellcheck?
-  align="left|center|right"
-  hint="Helper text"
-  error?
-  fillHeight?
-  autoHeight?
-  resize="none|vertical|horizontal|both"
-  @change=${handleChange}
-  @enter=${handleEnter}>
-</schmancy-textarea>
-
-// Textarea with fill height (fills container)
-<schmancy-textarea
-  label="Description"
-  fillHeight
-  placeholder="This fills the container height...">
-</schmancy-textarea>
-
-// Auto-growing textarea
-<schmancy-textarea
-  autoHeight
-  label="Comments"
-  placeholder="This grows with content...">
-</schmancy-textarea>
-
-// User-resizable textarea
-<schmancy-textarea
-  resize="vertical"
-  rows="6"
-  label="Notes"
-  placeholder="Drag the corner to resize...">
-</schmancy-textarea>
-
-// Combined features
-<schmancy-textarea
-  fillHeight
-  autoHeight
-  resize="both"
-  label="Full Featured"
-  placeholder="Fills container, auto-grows, and user resizable...">
-</schmancy-textarea>
-
-// Textarea Methods
-textarea.focus(options?) -> void           // Focus the textarea
-textarea.blur() -> void                    // Remove focus
-textarea.select() -> void                  // Select all text
-textarea.checkValidity() -> boolean        // Check validity
-textarea.reportValidity() -> boolean       // Validate and show browser message if invalid
-textarea.setCustomValidity(message) -> void // Set custom validation message
-textarea.adjustHeight() -> void            // Manually adjust height (for autoHeight)
-textarea.setSelectionRange(start, end, direction?) -> void // Set text selection
-textarea.setRangeText(replacement) -> void // Replace selected text
-
-// Textarea Properties
-value: string         // The content of the textarea
-name: string          // The name attribute
-label: string         // Label text
-placeholder: string   // Placeholder text
-rows: number = 2      // Number of rows to display
-cols: number = 20     // Number of columns to display
-minlength: number     // Minimum number of characters required
-maxlength: number     // Maximum number of characters allowed
-disabled: boolean     // Whether the textarea is disabled
-readonly: boolean     // Whether the textarea is read-only
-required: boolean     // Whether the textarea is required
-spellcheck: boolean   // Whether spellcheck is enabled
-align: 'left'|'center'|'right' = 'left' // Text alignment
-hint: string          // Helper text below the textarea
-error: boolean        // Error state
-fillHeight: boolean = false  // Fill container height
-autoHeight: boolean = false  // Auto-adjust height based on content
-resize: 'none'|'vertical'|'horizontal'|'both' = 'none' // Resize behavior
-wrap: 'hard'|'soft' = 'soft' // Text wrapping behavior
-dirname: string       // Direction attribute name
-autofocus: boolean    // Auto focus on page load
-
-// Textarea Events
-@change  // Fires when value changes with { detail: { value } }
-@enter   // Fires when enter key is pressed with { detail: { value } }
-@focus   // Fires when textarea gains focus
-@blur    // Fires when textarea loses focus
-
-// Examples
-// Basic usage
-<schmancy-textarea
-  name="comments"
-  label="Comments"
-  placeholder="Enter your comments here"
-  rows="4"
-  required
-  @change=${(e) => console.log('Comments:', e.detail.value)}>
-</schmancy-textarea>
-
-// Textarea with hint and error state
-<schmancy-textarea
-  name="bio"
-  label="Biography"
-  maxlength="500"
-  hint="Tell us about yourself (max 500 chars)"
-  error=${bio.length > 500}
-  @change=${(e) => bio = e.detail.value}>
-</schmancy-textarea>
-
-// Fill container height
-<div style="height: 300px; display: flex; flex-direction: column;">
-  <schmancy-textarea
-    fillHeight
-    label="Full Height Textarea"
-    placeholder="This fills the container...">
-  </schmancy-textarea>
-</div>
-
-// Auto-growing textarea
-<schmancy-textarea
-  name="notes"
-  label="Meeting Notes"
-  autoHeight
-  placeholder="Type your notes here, field grows automatically...">
-</schmancy-textarea>
-
-// User resizable textarea
-<schmancy-textarea
-  name="description"
-  label="Description"
-  resize="vertical"
-  rows="5"
-  placeholder="You can drag the corner to resize this...">
-</schmancy-textarea>
-
-// Combined features
-<div style="height: 400px; display: flex; flex-direction: column;">
-  <schmancy-textarea
-    fillHeight
-    autoHeight
-    resize="both"
-    label="Advanced Textarea"
-    placeholder="Fills height, auto-grows, and is resizable...">
-  </schmancy-textarea>
-</div>
-
-// Usage in a form
-<schmancy-form @submit=${handleSubmit}>
-  <schmancy-input 
-    name="title" 
-    label="Title" 
-    required>
-  </schmancy-input>
-  
-  <schmancy-textarea
-    name="description"
-    label="Description"
-    rows="5"
-    required
-    hint="Provide a detailed description">
-  </schmancy-textarea>
-  
-  <schmancy-button type="submit">Submit</schmancy-button>
-</schmancy-form>
-
-// Textarea with enter key handling
-<schmancy-textarea
-  name="message"
-  label="Chat Message"
-  placeholder="Type message and press Enter to send..."
-  @enter=${(e) => {
-    sendMessage(e.detail.value);
-    e.target.value = '';
-  }}>
-</schmancy-textarea>
-
-// Centered text alignment
-<schmancy-textarea
-  name="poem"
-  label="Poetry"
-  align="center"
-  rows="8"
-  placeholder="Write your poem here...">
-</schmancy-textarea>
-
-// Textarea with prefilled markdown template
-<schmancy-textarea
-  name="issue"
-  label="Issue Description"
-  value="## Issue Description
-- 
-- 
-
-## Steps to Reproduce
-1. 
-2. 
-3. 
-
-## Expected Behavior
-
-"
-  rows="12"
-  autoHeight>
-</schmancy-textarea>
-
-// Readonly textarea for displaying content
-<schmancy-textarea
-  label="Terms and Conditions"
-  value="Lorem ipsum dolor sit amet..."
-  readonly
-  rows="10">
-</schmancy-textarea>
-
-// Textarea with spellcheck disabled
-<schmancy-textarea
-  name="code"
-  label="Code Snippet"
-  placeholder="Paste your code here..."
-  spellcheck=${false}
-  rows="8">
-</schmancy-textarea>
-```
+# schmancy-textarea
+
+> Multi-line text input with auto-resize and form integration.
+
+## Usage
+```html
+<schmancy-textarea label="Description" placeholder="Enter details..."></schmancy-textarea>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| value | string | `''` | Current text value |
+| label | string | `''` | Label text above the textarea |
+| placeholder | string | `''` | Placeholder text |
+| name | string | auto | Form submission name |
+| required | boolean | `false` | Whether the field is required |
+| disabled | boolean | `false` | Whether the field is disabled |
+| readonly | boolean | `false` | Whether the field is read-only |
+| error | boolean | `false` | Whether the field shows an error state |
+| hint | string | `undefined` | Hint text below the field |
+| rows | number | `undefined` | Fixed visible rows (omit for auto-size) |
+| cols | number | `20` | Column width |
+| maxlength | number | `undefined` | Maximum character length |
+| minlength | number | `undefined` | Minimum character length |
+| autoHeight | boolean | `true` | Auto-grow height with content |
+| fillHeight | boolean | `false` | Fill container height |
+| resize | `'none'\|'vertical'\|'horizontal'\|'both'` | `'vertical'` | Resize handle |
+| align | `'left'\|'center'\|'right'` | `'left'` | Text alignment |
+| wrap | `'hard'\|'soft'` | `'soft'` | Text wrapping mode |
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| change | `{ value: string }` | On input or native change |
+| enter | `{ value: string }` | When Enter key is pressed |
+
+## Examples
+```html
+<!-- Auto-sizing textarea -->
+<schmancy-textarea label="Notes" autoHeight></schmancy-textarea>
+
+<!-- Fixed height, no resize -->
+<schmancy-textarea rows="5" resize="none" placeholder="Comments..."></schmancy-textarea>
+
+<!-- Fill container -->
+<schmancy-textarea fillHeight label="Content"></schmancy-textarea>
+```