@mhmo91/schmancy 0.7.7 → 0.8.3

package/ai/lightbox.md

@@ -0,0 +1,381 @@
+# Lightbox Directive
+
+A Lit directive that adds lightbox functionality to images, allowing them to be viewed in a full-screen overlay with optional gallery navigation.
+
+## Import
+
+```typescript
+import { lightbox } from '@mhmo91/schmancy/directives'
+```
+
+## Basic Usage
+
+### Single Image Lightbox
+
+The simplest use case - click an image to view it full-screen:
+
+```typescript
+import { html, LitElement } from 'lit'
+import { customElement } from 'lit/decorators.js'
+import { lightbox } from '@mhmo91/schmancy/directives'
+
+@customElement('my-component')
+export class MyComponent extends LitElement {
+  render() {
+    return html`
+      <img
+        src="https://example.com/image.jpg"
+        alt="Product photo"
+        ${lightbox()}
+      />
+    `
+  }
+}
+```
+
+### Image Gallery
+
+Show multiple images with navigation controls:
+
+```typescript
+import { html, LitElement } from 'lit'
+import { customElement, property } from 'lit/decorators.js'
+import { lightbox } from '@mhmo91/schmancy/directives'
+
+@customElement('gallery-component')
+export class GalleryComponent extends LitElement {
+  @property({ type: Array })
+  images = [
+    'https://example.com/photo1.jpg',
+    'https://example.com/photo2.jpg',
+    'https://example.com/photo3.jpg',
+    'https://example.com/photo4.jpg'
+  ]
+
+  render() {
+    return html`
+      <div class="gallery">
+        ${this.images.map((image, index) => html`
+          <img
+            src=${image}
+            alt="Gallery image ${index + 1}"
+            ${lightbox({ images: this.images, index })}
+            class="thumbnail"
+          />
+        `)}
+      </div>
+    `
+  }
+}
+```
+
+## Options
+
+The directive accepts an optional `LightboxOptions` object:
+
+```typescript
+interface LightboxOptions {
+  images?: string[]       // Array of image URLs for gallery mode
+  index?: number          // Starting index when opening the gallery
+  overlay?: TemplateResult // Optional Lit template to render over the image
+}
+```
+
+### Options Examples
+
+**Single image (no options needed):**
+```typescript
+${lightbox()}
+```
+
+**Gallery with specific starting image:**
+```typescript
+${lightbox({
+  images: this.allImages,
+  index: 2  // Opens at the 3rd image
+})}
+```
+
+**Image with overlay (name/price):**
+```typescript
+${lightbox({
+  overlay: html`
+    <div class="absolute inset-x-0 bottom-0 pt-10 pb-3 px-4 bg-linear-to-t from-black/80 via-black/40 to-transparent rounded-b-lg">
+      <div class="flex items-end justify-between gap-2">
+        <schmancy-typography type="title" token="lg" class="text-white">
+          ${this.item.name}
+        </schmancy-typography>
+        <schmancy-typography type="title" token="lg" class="text-white font-semibold">
+          ${formatCurrency(this.item.price, this.cart.currency)}
+        </schmancy-typography>
+      </div>
+    </div>
+  `,
+})}
+```
+
+## Features
+
+### Keyboard Navigation
+
+When the lightbox is open:
+- **Escape** - Close the lightbox
+- **Arrow Left** - Previous image (gallery mode only)
+- **Arrow Right** - Next image (gallery mode only)
+
+### Click Behavior
+
+- **Overlay background** - Click to close
+- **Single image** - Click the image itself to close
+- **Gallery** - Click navigation buttons to move between images
+- **Close button** - Always available in top-right corner
+
+### Automatic Enhancements
+
+The directive automatically:
+- Adds `cursor: pointer` style to images
+- Adds hover effects (`hover:opacity-80` and `transition-opacity` classes)
+- Creates full-screen overlay with backdrop blur
+- Handles focus management and cleanup
+- Supports smooth animations
+
+## Real-World Examples
+
+### Product Images
+
+```typescript
+@customElement('product-card')
+export class ProductCard extends LitElement {
+  @property({ type: Object })
+  product!: {
+    thumbnail: string
+    images: string[]
+  }
+
+  render() {
+    return html`
+      <div class="product-card">
+        <img
+          src=${this.product.thumbnail}
+          alt=${this.product.name}
+          ${lightbox({
+            images: this.product.images,
+            index: 0
+          })}
+          class="product-thumbnail"
+        />
+      </div>
+    `
+  }
+}
+```
+
+### Document Viewer
+
+```typescript
+@customElement('invoice-viewer')
+export class InvoiceViewer extends LitElement {
+  @property({ type: Array })
+  pageImages: string[] = []
+
+  render() {
+    return html`
+      <div class="invoice-pages">
+        ${this.pageImages.map((page, i) => html`
+          <div class="page-preview">
+            <img
+              src=${page}
+              alt="Invoice page ${i + 1}"
+              ${lightbox({ images: this.pageImages, index: i })}
+            />
+            <p>Page ${i + 1}</p>
+          </div>
+        `)}
+      </div>
+    `
+  }
+}
+```
+
+### Avatar with Enlargement
+
+```typescript
+@customElement('user-profile')
+export class UserProfile extends LitElement {
+  @property({ type: String })
+  avatarUrl!: string
+
+  render() {
+    return html`
+      <div class="profile-header">
+        <img
+          src=${this.avatarUrl}
+          alt="User avatar"
+          ${lightbox()}
+          class="avatar"
+        />
+        <div class="user-info">
+          <h2>John Doe</h2>
+          <p>Click avatar to enlarge</p>
+        </div>
+      </div>
+    `
+  }
+}
+```
+
+## Styling Tips
+
+The directive works with any image styling. Common patterns:
+
+```css
+/* Thumbnail grid */
+.thumbnail {
+  width: 200px;
+  height: 200px;
+  object-fit: cover;
+  border-radius: 8px;
+}
+
+/* Product image */
+.product-thumbnail {
+  width: 100%;
+  max-width: 400px;
+  height: auto;
+  border-radius: 12px;
+}
+
+/* Avatar */
+.avatar {
+  width: 80px;
+  height: 80px;
+  border-radius: 50%;
+  object-fit: cover;
+}
+```
+
+## Blackbird Animation
+
+The lightbox uses a **Blackbird two-stage arc animation** inspired by bird flight patterns. When opening, the image follows a curved trajectory like a bird taking flight.
+
+### How It Works
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                                                             │
+│    (2) Takeoff Arc Peak                                     │
+│         ↗     ↘                                             │
+│       ↗         ↘                                           │
+│  (1) Source      (3) Click Position                         │
+│  [Thumbnail]          ↘                                     │
+│                         ↘  (4) Landing Arc                  │
+│                           ↘                                 │
+│                             ↘                               │
+│                          (5) Final [Large Image]            │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 5 Keyframes (like bird flight)
+
+| Offset | Stage | Movement |
+|--------|-------|----------|
+| 0% | Start | At thumbnail (source element) |
+| 25% | Takeoff Arc | Arcs **UP** (bird lifts off) |
+| 50% | Waypoint | At click position (transition) |
+| 75% | Landing Arc | Arcs **DOWN** (bird descends) |
+| 100% | Final | At destination position |
+
+### Key Features
+
+- **Arc UP** during takeoff (like a bird gaining altitude)
+- **Arc DOWN** during landing (like a bird descending)
+- **Scale progression**: small → medium → large
+- **Organic easing**: `cubic-bezier(0.34, 1.2, 0.64, 1)` with slight overshoot
+- **Duration**: 600ms total for the full flight path
+- **Respects `prefers-reduced-motion`** for accessibility
+
+### Animation Sources
+
+The animation is based on research from:
+- [Animator Notebook - Bird Flight](https://www.animatornotebook.com/learn/bird-flight) - Three stages of flight (lift-off, flying, landing)
+- [Moving along curved paths in CSS](https://tobiasahlin.com/blog/curved-path-animations-in-css/) - Layered animation technique
+- [Spring Physics Animation](https://www.joshwcomeau.com/animation/a-friendly-introduction-to-spring-physics/) - Organic easing functions
+
+---
+
+## Flip Directive
+
+The lightbox includes a reusable `flip` directive for FLIP (First, Last, Invert, Play) animations.
+
+### Import
+
+```typescript
+import { flip } from '@mhmo91/schmancy/lightbox'
+```
+
+### Options
+
+```typescript
+interface FlipOptions {
+  sourceElement?: HTMLElement  // Source element to animate from
+  position?: { x: number; y: number } | MouseEvent | TouchEvent  // Click position
+  duration?: number            // Animation duration in ms (default: 600)
+  easing?: string              // CSS easing function
+  scale?: boolean              // Whether to animate scale (default: true)
+  blackbird?: boolean          // Enable two-stage arc animation (default: true)
+}
+```
+
+### Usage
+
+```typescript
+// Basic usage - animate from source element
+<div ${flip({ sourceElement: thumbnailElement })}>
+  Expanding content
+</div>
+
+// With click position for blackbird animation
+<img
+  src=${imageSrc}
+  ${flip({
+    sourceElement: this.thumbnailElement,
+    position: this.clickPosition,
+    duration: 600,
+    scale: true,
+    blackbird: true,
+  })}
+/>
+
+// Simple animation without blackbird arcs
+<div ${flip({ position: { x: 100, y: 200 }, blackbird: false })}>
+  Content
+</div>
+```
+
+---
+
+## Positioning
+
+The lightbox uses [Floating UI](https://floating-ui.com/) for smart positioning:
+
+### Desktop Behavior
+- Positions near the click point (quadrant-based)
+- Expands away from the click to maximize visibility
+- Automatically flips/shifts to stay in viewport
+
+### Mobile Behavior (< 768px)
+- **Centered horizontally** for better mobile UX
+- Vertical placement based on click position (top/bottom half)
+- Full-width image display
+
+---
+
+## Notes
+
+- The lightbox automatically handles cleanup when the component disconnects
+- Images are displayed at their natural resolution in the lightbox
+- The overlay uses Tailwind classes for styling (dark background, backdrop blur)
+- Gallery counter shows current position (e.g., "2 / 5")
+- Works seamlessly with lazy-loaded images
+- Mobile-friendly with touch-friendly controls

package/ai/typography.md

@@ -62,10 +62,12 @@ import '@schmancy/index'  // For all Schmancy components
   Section Header
 </schmancy-typography>
 
-// 8. Clickable text
-<schmancy-typography type="body" token="md" class="cursor-pointer hover:text-primary" @click="${handleClick}">
-  Click me for more information
-</schmancy-typography>
+// 8. Clickable text (wrap in surface or use native link)
+<schmancy-surface type="primaryContainer" class="inline-block px-2 py-1 rounded cursor-pointer" @click="${handleClick}">
+  <schmancy-typography type="body" token="md">
+    Click me for more information
+  </schmancy-typography>
+</schmancy-surface>
 
 // 9. Truncated text with ellipsis
 <schmancy-typography type="body" token="md" maxLines="2">
@@ -80,9 +82,11 @@ import '@schmancy/index'  // For all Schmancy components
   <schmancy-typography type="body" token="md" class="block mb-4">
     This is a description that provides more context about the card content.
   </schmancy-typography>
-  <schmancy-typography type="label" token="lg" class="text-primary">
-    View Details →
-  </schmancy-typography>
+  <schmancy-surface type="primaryContainer" class="inline-block px-2 py-1 rounded">
+    <schmancy-typography type="label" token="lg">
+      View Details →
+    </schmancy-typography>
+  </schmancy-surface>
 </schmancy-card>
 ```
 
@@ -172,61 +176,81 @@ Typography automatically inherits colors from the theme:
 
 ### Color Inheritance
 
-**CRITICAL: Typography components automatically inherit the correct color from their parent surface.**
+## 🚨 ABSOLUTE RULE: NEVER PUT COLOR CLASSES ON SCHMANCY-TYPOGRAPHY
+
+**Typography MUST inherit its color from the parent surface. NO EXCEPTIONS.**
+
+### Why This Rule Exists
+- `schmancy-typography` automatically gets the correct contrast color from its parent surface
+- Adding `text-*` classes breaks the design system's color inheritance
+- It causes visual inconsistency when themes change
+- It violates Material Design 3's surface/on-color relationship
 
-#### ✅ CORRECT - Let Surface Handle Colors
+### ❌ FORBIDDEN - Color Classes on Typography
 ```html
-<!-- Typography inherits the correct on-color from the surface -->
-<schmancy-surface type="containerLow" class="p-4">
-  <schmancy-typography type="headline" token="md">
-    This text automatically uses the correct contrast color
+<!-- ALL OF THESE ARE WRONG - NEVER DO THIS -->
+<schmancy-typography type="headline" token="md" class="text-error">Wrong</schmancy-typography>
+<schmancy-typography type="body" token="sm" class="text-success">Wrong</schmancy-typography>
+<schmancy-typography type="title" token="lg" class="text-primary">Wrong</schmancy-typography>
+<schmancy-typography type="label" token="md" class="text-warning">Wrong</schmancy-typography>
+<schmancy-typography class="text-surface-onVariant">Wrong</schmancy-typography>
+```
+
+### ✅ CORRECT - Use Surfaces to Control Color
+```html
+<!-- Need error text? Use error surface -->
+<schmancy-surface type="error" class="px-2 py-1 rounded">
+  <schmancy-typography type="body" token="sm">
+    Error message here (automatically gets on-error color)
   </schmancy-typography>
 </schmancy-surface>
 
-<!-- Different surface types provide different text colors automatically -->
-<schmancy-surface type="primary" class="p-4">
-  <schmancy-typography type="body" token="md">
-    White text on primary background (automatic)
+<!-- Need primary-colored text? Use primary surface -->
+<schmancy-surface type="primary" class="px-2 py-1 rounded">
+  <schmancy-typography type="label" token="md">
+    Primary text (automatically gets on-primary color)
   </schmancy-typography>
 </schmancy-surface>
-```
 
-#### ❌ WRONG - Explicit Color Classes Inside Surfaces
-```html
-<!-- BAD: Overriding the surface's automatic color selection -->
-<schmancy-surface type="containerLow" class="p-4">
-  <schmancy-typography type="headline" token="md" class="text-surface-onVariant">
-    Don't add color classes - the surface already provides the right color!
+<!-- Normal text inside container -->
+<schmancy-surface type="container" class="p-4">
+  <schmancy-typography type="headline" token="md">
+    This text automatically uses the correct contrast color
   </schmancy-typography>
 </schmancy-surface>
 ```
 
-#### When to Use Color Classes
-
-**ONLY add explicit color classes when:**
-1. Typography is used standalone (not inside a surface)
-2. You need a specific semantic color (e.g., `text-error` for errors)
-3. Creating interactive elements that change color on hover
-
+### ❌ ALSO FORBIDDEN - Spans with Colors Inside Typography
 ```html
-<!-- Standalone typography (not in a surface) - color class is appropriate -->
-<div class="p-4">
-  <schmancy-typography type="label" token="md" class="text-error">
-    Error: Invalid input
-  </schmancy-typography>
-</div>
-
-<!-- Interactive element with hover state -->
-<schmancy-typography type="body" token="md" class="cursor-pointer hover:text-primary">
-  Click for more info
+<!-- WRONG - No color classes inside typography either! -->
+<schmancy-typography type="body" token="md">
+  Total: <span class="text-error">-€338.89</span>  <!-- WRONG -->
 </schmancy-typography>
 ```
 
-**Key Rules:**
-- NEVER add `text-surface-onVariant` or similar classes inside surfaces
-- Surfaces automatically provide the correct contrast color
-- Each surface type (primary, secondary, tertiary, containerLow, etc.) knows its appropriate text color
-- Trust the component system - it handles accessibility and contrast automatically
+### ✅ CORRECT - Always Wrap with Surface
+```html
+<!-- For colored values, wrap the typography in a surface -->
+<schmancy-surface type="errorContainer" class="px-2 py-0.5 rounded inline-block">
+  <schmancy-typography type="body" token="md">-€338.89</schmancy-typography>
+</schmancy-surface>
+```
+
+### Available Surface Types for Colored Text
+| Need This Color | Use This Surface |
+|-----------------|------------------|
+| Error/Red text | `type="error"` or `type="errorContainer"` |
+| Success/Green text | `type="success"` or `type="successContainer"` |
+| Warning/Amber text | `type="warning"` or `type="warningContainer"` |
+| Primary accent | `type="primary"` or `type="primaryContainer"` |
+| Secondary accent | `type="secondary"` or `type="secondaryContainer"` |
+| Tertiary accent | `type="tertiary"` or `type="tertiaryContainer"` |
+
+### The Principle
+**Surfaces define the background AND automatically provide the correct text color.**
+- `schmancy-surface type="error"` → red background, white text (automatic)
+- `schmancy-surface type="errorContainer"` → light red background, dark red text (automatic)
+- Trust the design system - don't override it with color classes
 
 ### Implementation Details
 - Uses Shadow DOM with encapsulated styles
@@ -257,9 +281,11 @@ Typography automatically inherits colors from the theme:
 
 3. **Data Display**
    ```html
-   <schmancy-typography type="headline" token="md" class="block text-primary">
-     $1,234.56
-   </schmancy-typography>
+   <schmancy-surface type="primaryContainer" class="inline-block px-3 py-2 rounded">
+     <schmancy-typography type="headline" token="md" class="block">
+       $1,234.56
+     </schmancy-typography>
+   </schmancy-surface>
    <schmancy-typography type="label" token="sm">
      Total Revenue
    </schmancy-typography>