@mhmo91/schmancy 0.2.195 → 0.2.196

package/dist/ai/surface.md

@@ -1,221 +1,160 @@
 # Schmancy Surface - AI Reference
 
 ```js
-// Basic Surface
+// Surface Component
 <schmancy-surface
-  elevation="0|1|2|3|4|5"
-  rounded="none|sm|md|lg|xl|full"
-  padding="none|xs|sm|md|lg|xl">
-  Surface content goes here
+  fill="all|width|height|auto"
+  rounded="none|top|left|right|bottom|all"
+  type="surface|surfaceDim|surfaceBright|containerLowest|containerLow|container|containerHigh|containerHighest"
+  elevation="0|1|2|3|4|5">
+  Content goes here
 </schmancy-surface>
 
-// Surface with color
-<schmancy-surface
-  color="primary|secondary|tertiary|surface|background|error"
-  theme="light|dark">
-  Colored surface content
-</schmancy-surface>
-
-// Interactive surface
-<schmancy-surface
-  interactive
-  @click=${handleClick}>
-  Click me!
-</schmancy-surface>
+// Properties
+fill: string          // "all", "width", "height", "auto" (default: "auto")
+rounded: string       // Corner rounding: "none", "top", "left", "right", "bottom", "all" (default: "none")
+type: string          // Surface color variant (default: "surface")
+elevation: number     // Shadow depth 0-5 (default: 0)
 
-// Surface with border
-<schmancy-surface
-  bordered
-  border-color="primary|secondary|tertiary|divider|error"
-  border-width="thin|medium|thick"
-  border-style="solid|dashed|dotted">
-  Surface with border
-</schmancy-surface>
+// Surface Types (background colors)
+"surface"             // Default surface color
+"surfaceDim"          // Dimmed surface
+"surfaceBright"       // Bright surface
+"containerLowest"     // Lowest container elevation
+"containerLow"        // Low container elevation
+"container"           // Standard container
+"containerHigh"       // High container elevation
+"containerHighest"    // Highest container elevation
 
-// Surface with dimensions
-<schmancy-surface
-  width="300px"
-  height="200px"
-  min-width="200px"
-  max-width="500px"
-  min-height="100px"
-  max-height="300px">
-  Fixed size surface
+// Examples
+// 1. Basic surface
+<schmancy-surface>
+  Basic content
 </schmancy-surface>
 
-// Surface Properties
-elevation: number|string  // Shadow elevation (0-5)
-rounded: string           // Border radius: "none", "sm", "md", "lg", "xl", "full"
-padding: string           // Padding: "none", "xs", "sm", "md", "lg", "xl"
-margin: string            // Margin: "none", "xs", "sm", "md", "lg", "xl"
-color: string             // Background color (theme color or CSS value)
-theme: string             // Theme: "light", "dark"
-interactive: boolean      // Enable hover and active states
-bordered: boolean         // Show border
-borderColor: string       // Border color
-borderWidth: string       // Border width: "thin", "medium", "thick"
-borderStyle: string       // Border style: "solid", "dashed", "dotted"
-width: string             // Width
-height: string            // Height
-minWidth: string          // Minimum width
-maxWidth: string          // Maximum width
-minHeight: string         // Minimum height
-maxHeight: string         // Maximum height
-fullWidth: boolean        // Take full width of parent
-fullHeight: boolean       // Take full height of parent
-
-// Surface Context
-// For theme-aware surfaces and consistent styling
-import { SurfaceContext } from 'schmancy/surface';
-
-const surfaceContext = new SurfaceContext({
-  elevation: 1,
-  rounded: 'md',
-  padding: 'md',
-  theme: 'light'
-});
-
-// Examples
-// Basic card-like surface
-<schmancy-surface
-  elevation="2"
-  rounded="lg"
-  padding="lg">
+// 2. Elevated card
+<schmancy-surface 
+  elevation="2" 
+  rounded="all"
+  type="containerLow">
   <h3>Card Title</h3>
-  <p>This is a basic card surface with elevation, rounded corners, and padding.</p>
+  <p>Card content</p>
 </schmancy-surface>
 
-// Interactive card
-<schmancy-surface
-  elevation="1"
-  rounded="md"
-  padding="md"
-  interactive
-  @click=${navigateToDetails}>
-  <div style="display: flex; align-items: center; gap: 16px;">
-    <schmancy-avatar
-      src="path/to/avatar.jpg"
-      size="large">
-    </schmancy-avatar>
-    
-    <div>
-      <h3>John Doe</h3>
-      <p>Software Engineer</p>
-    </div>
-    
-    <schmancy-icon
-      icon="chevron-right"
-      style="margin-left: auto;">
-    </schmancy-icon>
-  </div>
+// 3. Full-width surface
+<schmancy-surface 
+  fill="width"
+  type="surfaceDim"
+  elevation="1">
+  Full width content
 </schmancy-surface>
 
-// Alert surfaces
+// 4. Dashboard panel
 <schmancy-surface
-  color="primary"
-  rounded="md"
-  padding="md"
-  bordered
-  border-color="primary"
-  style="--surface-color-opacity: 0.1;">
-  <div style="display: flex; align-items: center; gap: 16px;">
-    <schmancy-icon icon="info" color="primary"></schmancy-icon>
-    <div>
-      <h4>Information</h4>
-      <p>This is an informational message.</p>
-    </div>
+  elevation="3"
+  rounded="all"
+  type="containerHighest"
+  fill="all">
+  <div class="dashboard-content">
+    <!-- Content -->
   </div>
 </schmancy-surface>
+```
 
-<schmancy-surface
-  color="error"
-  rounded="md"
-  padding="md"
-  bordered
-  border-color="error"
-  style="--surface-color-opacity: 0.1;">
-  <div style="display: flex; align-items: center; gap: 16px;">
-    <schmancy-icon icon="alert-triangle" color="error"></schmancy-icon>
-    <div>
-      <h4>Error</h4>
-      <p>Something went wrong. Please try again.</p>
-    </div>
-  </div>
-</schmancy-surface>
+## Related Components
+- **[Card](./card.md)**: Pre-styled surface for card layouts
+- **[Sheet](./sheet.md)**: Modal surface overlay
+- **[Dialog](./dialog.md)**: Elevated modal surface
+- **[Layout](./layout.md)**: Layout components that often contain surfaces
 
-// Surface grid layout
-<div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 16px;">
-  <schmancy-surface
-    elevation="1"
-    rounded="md"
-    padding="md">
-    <h3>Card 1</h3>
-    <p>Content for card 1.</p>
-  </schmancy-surface>
-  
-  <schmancy-surface
-    elevation="1"
-    rounded="md"
-    padding="md">
-    <h3>Card 2</h3>
-    <p>Content for card 2.</p>
-  </schmancy-surface>
-  
-  <schmancy-surface
-    elevation="1"
-    rounded="md"
-    padding="md">
-    <h3>Card 3</h3>
-    <p>Content for card 3.</p>
-  </schmancy-surface>
-</div>
-
-// Dashboard panel
-<schmancy-surface
-  elevation="2"
-  rounded="lg"
-  padding="lg"
-  height="300px">
-  <div style="display: flex; flex-direction: column; height: 100%;">
-    <div style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 16px;">
-      <h3>Sales Overview</h3>
-      <schmancy-dropdown>
-        <schmancy-button slot="trigger" variant="tertiary" size="small">
-          <span>This Week</span>
-          <schmancy-icon slot="suffix" icon="chevron-down"></schmancy-icon>
-        </schmancy-button>
-        
-        <schmancy-menu slot="content">
-          <schmancy-menu-item value="day">Today</schmancy-menu-item>
-          <schmancy-menu-item value="week">This Week</schmancy-menu-item>
-          <schmancy-menu-item value="month">This Month</schmancy-menu-item>
-          <schmancy-menu-item value="year">This Year</schmancy-menu-item>
-        </schmancy-menu>
-      </schmancy-dropdown>
-    </div>
-    
-    <div style="flex: 1; display: flex; align-items: center; justify-content: center;">
-      <!-- Chart or content would go here -->
-      <p>Chart placeholder</p>
-    </div>
-  </div>
-</schmancy-surface>
+## Technical Details
+
+### CSS Host Styling
+The component uses `:host` selectors for all styling:
+- No wrapper elements - styles apply directly to the component
+- Properties reflect to HTML attributes for CSS targeting
+- Uses CSS custom properties from the theme system
+
+### Theme Integration
+```css
+/* Background colors use theme variables */
+--schmancy-sys-color-surface-default
+--schmancy-sys-color-surface-dim
+--schmancy-sys-color-surface-bright
+--schmancy-sys-color-surface-lowest
+--schmancy-sys-color-surface-low
+--schmancy-sys-color-surface-container
+--schmancy-sys-color-surface-high
+--schmancy-sys-color-surface-highest
+
+/* Text color */
+--schmancy-sys-color-surface-on
+
+/* Elevation shadows */
+--schmancy-sys-elevation-1 through --schmancy-sys-elevation-5
+```
+
+### Context Provider
+Surface provides its type to descendant components via Lit Context:
+```js
+import { SchmancySurfaceTypeContext } from '@schmancy/surface'
+```
+
+## Common Use Cases
+
+1. **Content Cards**: Elevated surfaces for grouped content
+   ```html
+   <schmancy-surface elevation="2" rounded="all" type="containerLow">
+     <h3>Feature Card</h3>
+     <p>Description of the feature</p>
+     <schmancy-button>Learn More</schmancy-button>
+   </schmancy-surface>
+   ```
+
+2. **Page Sections**: Full-width background surfaces
+   ```html
+   <schmancy-surface fill="width" type="surfaceDim">
+     <section class="hero-section">
+       <h1>Welcome</h1>
+       <p>Hero content here</p>
+     </section>
+   </schmancy-surface>
+   ```
+
+3. **Modal Backgrounds**: High elevation surfaces
+   ```html
+   <schmancy-surface 
+     elevation="5" 
+     rounded="all" 
+     type="containerHighest">
+     <div class="modal-content">
+       <h2>Modal Title</h2>
+       <p>Modal body content</p>
+     </div>
+   </schmancy-surface>
+   ```
+
+4. **Nested Surfaces**: Different elevation levels
+   ```html
+   <schmancy-surface type="surface" fill="all">
+     <schmancy-surface 
+       elevation="1" 
+       rounded="all" 
+       type="containerLow">
+       <p>Nested content with different elevation</p>
+     </schmancy-surface>
+   </schmancy-surface>
+   ```
 
-// Using surface context
-<div .context=${surfaceContext}>
-  <schmancy-surface>
-    <h3>First Panel</h3>
-    <p>This surface inherits settings from the context.</p>
-  </schmancy-surface>
-  
-  <schmancy-surface>
-    <h3>Second Panel</h3>
-    <p>This surface also inherits settings from the context.</p>
-  </schmancy-surface>
-  
-  <schmancy-surface elevation="3" rounded="xl">
-    <h3>Custom Panel</h3>
-    <p>This surface overrides some context settings.</p>
-  </schmancy-surface>
-</div>
-```
+5. **Sidebar Panels**: Directional rounding
+   ```html
+   <schmancy-surface 
+     fill="height" 
+     rounded="right" 
+     elevation="2"
+     type="containerHigh">
+     <nav class="sidebar">
+       <!-- Navigation items -->
+     </nav>
+   </schmancy-surface>
+   ```

package/dist/ai/teleport.md

@@ -0,0 +1,196 @@
+# Teleport Component
+
+An advanced component that enables smooth FLIP (First, Last, Invert, Play) animations for elements transitioning between different DOM positions.
+
+## Quick Start
+
+```html
+<!-- Source element -->
+<schmancy-teleport id="user-avatar">
+  <schmancy-avatar src="/user.jpg" name="John Doe"></schmancy-avatar>
+</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>
+```
+
+## 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
+
+The teleport component uses a sophisticated event system to coordinate animations:
+
+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
+
+## Examples
+
+### Page Transition Animation
+```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>
+  </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/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
+```
+
+## 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
+
+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