@mhmo91/schmancy 0.2.194 → 0.2.196

package/ai/table.md

@@ -50,6 +50,35 @@
   </tbody>
 </schmancy-table>
 
+// Data Table with programmatic columns and custom sorting
+<schmancy-table
+  .columns=${[
+    { 
+      name: 'Name', 
+      key: 'name', 
+      sortable: true 
+    },
+    { 
+      name: 'Date Joined', 
+      key: 'dateJoined', 
+      sortable: true,
+      // Custom sort by Unix timestamp
+      value: (item) => new Date(item.dateJoined).getTime()
+    },
+    { 
+      name: 'Profile Completion', 
+      key: 'profile',
+      sortable: true,
+      // Sort by completion percentage 
+      value: (item) => item.profile.completionPercentage,
+      // Display with custom rendering
+      render: (item) => html`${item.profile.completionPercentage}%`
+    }
+  ]}
+  .data=${users}
+  sortable>
+</schmancy-table>
+
 // Table Properties
 striped: boolean          // Apply alternating row colors
 bordered: boolean         // Add borders to cells
@@ -60,6 +89,15 @@ sortable: boolean         // Enable column sorting
 selectable: boolean       // Enable row selection
 loading: boolean          // Show loading state
 
+// Column Configuration Properties (when using programmatic columns)
+name: string              // Display name for the column header
+key?: keyof T             // Object property to access for this column
+align?: string            // Text alignment ('left', 'right', 'center')
+weight?: string           // Font weight ('normal', 'bold')
+render?: function         // Custom render function for complex content: (item) => TemplateResult
+sortable?: boolean        // Whether this column supports sorting
+value?: function          // Custom value function for sorting: (item) => any
+
 // Row Properties
 selected: boolean         // Whether the row is selected
 data: object              // Data object for the row
@@ -105,7 +143,7 @@ data: object              // Data object for the row
   </tbody>
 </schmancy-table>
 
-// Sortable table
+// Sortable table - standard HTML structure
 <schmancy-table
   sortable
   @sort=${(e) => sortData(e.detail.column, e.detail.direction)}>
@@ -142,6 +180,66 @@ data: object              // Data object for the row
   </tbody>
 </schmancy-table>
 
+// Sortable table - programmatic with custom value functions
+<schmancy-table
+  .data=${userData}
+  .columns=${[
+    {
+      name: 'ID', 
+      key: 'id', 
+      sortable: true
+    },
+    {
+      name: 'User', 
+      key: 'user', 
+      sortable: true,
+      // Sort by last name for "user" column
+      value: (item) => item.user.lastName,
+      // Custom render function for complex data
+      render: (item) => html`
+        <div class="flex items-center">
+          <schmancy-avatar src=${item.user.avatar} size="sm"></schmancy-avatar>
+          <div class="ml-2">
+            <div>${item.user.firstName} ${item.user.lastName}</div>
+            <div class="text-sm text-gray-500">${item.user.email}</div>
+          </div>
+        </div>
+      `
+    },
+    {
+      name: 'Status', 
+      key: 'status', 
+      sortable: true,
+      // Sort by status priority (numeric value) but display text
+      value: (item) => statusPriorities[item.status] || 0,
+      render: (item) => html`
+        <schmancy-badge variant=${getStatusVariant(item.status)}>
+          ${item.status}
+        </schmancy-badge>
+      `
+    },
+    {
+      name: 'Created', 
+      key: 'createdAt', 
+      sortable: true,
+      // Sort by timestamp but display formatted date
+      value: (item) => new Date(item.createdAt).getTime(),
+      render: (item) => formatDate(item.createdAt)
+    },
+    {
+      name: 'Actions',
+      render: (item) => html`
+        <div class="flex space-x-2">
+          <schmancy-icon-button icon="edit" @click=${() => editItem(item)}></schmancy-icon-button>
+          <schmancy-icon-button icon="delete" @click=${() => deleteItem(item)}></schmancy-icon-button>
+        </div>
+      `
+    }
+  ]}
+  sortable
+  @sort=${(e) => console.log('Sort changed:', e.detail)}>
+</schmancy-table>
+
 // Selectable table
 <schmancy-table
   selectable

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

package/ai/theme-button.md

@@ -0,0 +1,173 @@
+# Theme Button Component
+
+A simple, animated button component for theme switching functionality with a rotating palette icon.
+
+## Quick Start
+
+```html
+<!-- Basic theme button -->
+<schmancy-theme-button></schmancy-theme-button>
+
+<!-- In a toolbar -->
+<schmancy-appbar>
+  <h1 slot="title">My App</h1>
+  <schmancy-theme-button slot="actions"></schmancy-theme-button>
+</schmancy-appbar>
+```
+
+## Properties
+
+The component inherits all properties from the base button component through `TailwindElement`.
+
+## Features
+
+### Animated Icon
+The palette icon rotates 360 degrees when clicked:
+
+```javascript
+this.color.animate([
+  { transform: 'rotate(0deg)' },
+  { transform: 'rotate(360deg)' }
+], {
+  duration: 300
+});
+```
+
+### Native Web Animations
+Uses the Web Animations API for smooth, performant animations without external dependencies.
+
+## Examples
+
+### In Navigation Bar
+```html
+<nav class="flex items-center justify-between p-4">
+  <h1>Brand</h1>
+  <div class="flex gap-2">
+    <schmancy-theme-button></schmancy-theme-button>
+    <schmancy-icon-button>settings</schmancy-icon-button>
+  </div>
+</nav>
+```
+
+### With Custom Theme Logic
+```html
+<schmancy-theme-button @click="${() => {
+  // Toggle between themes
+  const currentTheme = document.querySelector('schmancy-theme');
+  currentTheme.scheme = currentTheme.scheme === 'light' ? 'dark' : 'light';
+}}"></schmancy-theme-button>
+```
+
+### In a Settings Panel
+```html
+<schmancy-card>
+  <h3 slot="header">Appearance Settings</h3>
+  
+  <div class="space-y-4">
+    <div class="flex items-center justify-between">
+      <span>Theme</span>
+      <schmancy-theme-button></schmancy-theme-button>
+    </div>
+    
+    <schmancy-divider></schmancy-divider>
+    
+    <schmancy-select label="Color Scheme">
+      <schmancy-option value="auto">Auto</schmancy-option>
+      <schmancy-option value="light">Light</schmancy-option>
+      <schmancy-option value="dark">Dark</schmancy-option>
+    </schmancy-select>
+  </div>
+</schmancy-card>
+```
+
+### With Tooltip
+```html
+<schmancy-tooltip content="Change theme">
+  <schmancy-theme-button></schmancy-theme-button>
+</schmancy-tooltip>
+```
+
+## Implementation Details
+
+The component structure:
+- Uses `schmancy-button` with text variant
+- Contains `schmancy-icon` with palette icon
+- Applies rotation animation on click
+- Maintains reference to icon element via `@query`
+
+## Styling
+
+Since it uses the base button component, all button styling applies:
+
+```css
+/* Custom positioning in toolbar */
+schmancy-theme-button {
+  margin-left: auto;
+}
+
+/* Adjust icon size */
+schmancy-theme-button schmancy-icon {
+  font-size: 1.25rem;
+}
+```
+
+## Animation Customization
+
+You can extend the animation behavior:
+
+```javascript
+// Custom animation options
+{
+  duration: 300,
+  easing: 'ease-out',
+  fill: 'forwards'  // Keep final rotation state
+}
+```
+
+## Integration with Theme System
+
+While the button provides the UI, you'll need to implement the theme switching logic:
+
+```javascript
+// Example theme toggle implementation
+class MyApp extends LitElement {
+  toggleTheme() {
+    const theme = this.shadowRoot.querySelector('schmancy-theme');
+    const themes = ['#6750A4', '#00695C', '#D32F2F', '#1976D2'];
+    const currentIndex = themes.indexOf(theme.color);
+    theme.color = themes[(currentIndex + 1) % themes.length];
+  }
+  
+  render() {
+    return html`
+      <schmancy-theme>
+        <schmancy-theme-button @click="${this.toggleTheme}">
+        </schmancy-theme-button>
+      </schmancy-theme>
+    `;
+  }
+}
+```
+
+## Best Practices
+
+1. **Placement**: Put in consistent location (usually top-right)
+2. **Feedback**: The rotation provides immediate feedback
+3. **Persistence**: Save theme preference to localStorage
+4. **Accessibility**: Include proper ARIA labels
+5. **Mobile**: Ensure adequate touch target size
+
+## Related Components
+
+- [Theme](./theme.md) - The theming system
+- [Button](./button.md) - Base button component
+- [Icon](./icons.md) - Icon system
+- [Tooltip](./tooltip.md) - Help text
+
+## Use Cases
+
+1. **App Headers**: Quick theme toggle in navigation
+2. **Settings Pages**: Part of appearance settings
+3. **Demos**: Showcase theme capabilities
+4. **User Preferences**: Personalization options
+5. **Accessibility**: High contrast mode switching