@mhmo91/schmancy 0.7.7 → 0.8.3

package/ai/audio.md

@@ -0,0 +1,241 @@
+# Schmancy Emotional Sound Library - AI Reference
+
+## Overview
+
+A curated collection of soft, elegant sounds organized by emotional categories. Each sound is designed to be non-intrusive, emotionally evocative, and beautiful - inspired by the gentle sounds of nature like soft air puffs and warm tones.
+
+## Quick Start
+
+```typescript
+// Import from the main Schmancy package
+import { $sounds } from '@mhmo91/schmancy'
+
+// Play a feeling
+$sounds.play('joyful')
+$sounds.play('relieved')
+$sounds.play('curious')
+
+// Adjust volume (0.0 - 1.0)
+$sounds.setVolume(0.2)
+
+// Mute/unmute
+$sounds.mute()
+$sounds.unmute()
+```
+
+## Feeling Categories
+
+### 1. Happy / Pleasant
+```typescript
+type HappyFeeling =
+  | 'joyful' | 'content' | 'excited' | 'proud' | 'hopeful'
+  | 'relieved' | 'grateful' | 'peaceful' | 'playful' | 'amused'
+  | 'curious' | 'inspired' | 'confident' | 'loved' | 'comforted' | 'energized'
+
+// Examples
+$sounds.play('joyful')     // Double puff + rising happy tones
+$sounds.play('content')    // Gentle satisfied sigh + warm tones
+$sounds.play('excited')    // Quick ascending puffs + sparkly tones
+$sounds.play('curious')    // Questioning puff + rising tone
+$sounds.play('relieved')   // Long exhale + descending release
+```
+
+### 2. Sad / Low
+```typescript
+type SadFeeling =
+  | 'sad' | 'lonely' | 'disappointed' | 'heartbroken' | 'grieving'
+  | 'hopeless' | 'empty' | 'discouraged' | 'melancholic' | 'homesick'
+  | 'hurt' | 'miserable' | 'regretful' | 'ashamed' | 'inferior'
+
+// Examples
+$sounds.play('sad')           // Heavy sigh + descending tone
+$sounds.play('disappointed')  // Deflating puff + falling tone
+$sounds.play('melancholic')   // Wistful puff + bittersweet tones
+```
+
+### 3. Anxious / Fearful
+```typescript
+type AnxiousFeeling =
+  | 'anxious' | 'worried' | 'afraid' | 'terrified' | 'panicked'
+  | 'nervous' | 'uneasy' | 'insecure' | 'overwhelmed' | 'stressed'
+  | 'tense' | 'apprehensive' | 'startled' | 'suspicious' | 'vulnerable'
+
+// Examples
+$sounds.play('anxious')   // Tight quick puffs + uncertain wobble
+$sounds.play('nervous')   // Quick shallow puffs + trembling tone
+$sounds.play('startled')  // Quick sharp puff + high tone
+```
+
+### 4. Angry / Frustrated
+```typescript
+type AngryFeeling =
+  | 'annoyed' | 'irritated' | 'frustrated' | 'angry' | 'enraged'
+  | 'bitter' | 'resentful' | 'jealous' | 'envious' | 'indignant'
+  | 'impatient' | 'hostile' | 'contemptuous'
+
+// Examples
+$sounds.play('annoyed')     // Short frustrated puff + low rumble
+$sounds.play('frustrated')  // Tense puff + blocked feeling
+$sounds.play('impatient')   // Quick tapping puffs + urgent tone
+```
+
+### 5. Tired / Drained
+```typescript
+type TiredFeeling =
+  | 'tired' | 'exhausted' | 'drained' | 'burnedOut' | 'numb'
+  | 'bored' | 'unmotivated' | 'apathetic' | 'restless'
+
+// Examples
+$sounds.play('tired')     // Heavy slow puff + drooping tone
+$sounds.play('exhausted') // Very slow heavy exhale + descending fade
+$sounds.play('bored')     // Flat sigh + monotone
+```
+
+### 6. Calm / Grounded
+```typescript
+type CalmFeeling =
+  | 'calm' | 'relaxed' | 'atEase' | 'balanced' | 'stable'
+  | 'secure' | 'safe' | 'centered' | 'grounded' | 'accepting'
+
+// Examples
+$sounds.play('calm')      // Slow peaceful puff + sustained gentle tone
+$sounds.play('relaxed')   // Long soft exhale + gentle descending
+$sounds.play('grounded')  // Deep centered puff + low stable tone
+$sounds.play('safe')      // Soft enveloping puff + warm embracing tones
+```
+
+### 7. Connected / Social
+```typescript
+type ConnectedFeeling =
+  | 'connected' | 'accepted' | 'included' | 'belonging' | 'appreciated'
+  | 'valued' | 'respected' | 'supported' | 'protective' | 'compassionate' | 'empathetic'
+
+// Examples
+$sounds.play('connected')   // Warm shared breath + harmonious tones
+$sounds.play('appreciated') // Touched puff + warm ascending
+$sounds.play('supported')   // Held puff + stable harmonies
+```
+
+### 8. Mixed / Complicated
+```typescript
+type MixedFeeling =
+  | 'conflicted' | 'confused' | 'ambivalent' | 'nostalgic' | 'guilty'
+  | 'embarrassed' | 'surprised' | 'shocked' | 'awestruck' | 'skeptical'
+
+// Examples
+$sounds.play('nostalgic')  // Wistful distant puff + bittersweet memory tones
+$sounds.play('surprised')  // Quick gasp + rising tone
+$sounds.play('awestruck')  // Wonder-filled breath + ascending shimmer
+$sounds.play('confused')   // Uncertain puff + questioning wobble
+```
+
+## API Reference
+
+```typescript
+class EmotionalSoundGenerator {
+  // Play any feeling
+  play(feeling: Feeling): void
+
+  // Volume control (0.0 - 1.0, default 0.15)
+  setVolume(vol: number): void
+  getVolume(): number
+
+  // Mute control
+  mute(): void
+  unmute(): void
+  isMuted(): boolean
+
+  // Cleanup
+  dispose(): void
+}
+
+// Singleton instance
+export const $sounds: EmotionalSoundGenerator
+```
+
+## Sound Design Philosophy
+
+All sounds are built from these core primitives:
+
+1. **Puff** - Filtered white noise creating soft air sounds
+2. **Tone** - Simple sine wave with gentle envelope
+3. **Warm Tone** - Low-pass filtered tone for warmth
+4. **Shimmer** - Multiple harmonically related tones
+
+Each feeling combines these primitives with:
+- Quick attack (15-30ms) for responsiveness
+- Gentle exponential release for softness
+- Low default volume (0.15) for subtlety
+- Short duration (0.2-0.5s) for non-intrusiveness
+
+## Use Cases
+
+```typescript
+// Form validation feedback
+onValidationError() {
+  $sounds.play('disappointed')
+}
+
+onValidationSuccess() {
+  $sounds.play('relieved')
+}
+
+// User actions
+onSaveComplete() {
+  $sounds.play('content')
+}
+
+onDelete() {
+  $sounds.play('sad')
+}
+
+// Navigation
+onPageLoad() {
+  $sounds.play('curious')
+}
+
+// Achievements
+onMilestoneReached() {
+  $sounds.play('proud')
+}
+
+// Connections
+onFriendJoined() {
+  $sounds.play('connected')
+}
+
+// Waiting states
+onLoadingTimeout() {
+  $sounds.play('impatient')
+}
+```
+
+## Type Exports
+
+```typescript
+import type {
+  Feeling,
+  FeelingCategory,
+  HappyFeeling,
+  SadFeeling,
+  AnxiousFeeling,
+  AngryFeeling,
+  TiredFeeling,
+  CalmFeeling,
+  ConnectedFeeling,
+  MixedFeeling,
+} from '@mhmo91/schmancy'
+```
+
+## All 88 Feelings at a Glance
+
+| Category | Feelings |
+|----------|----------|
+| **Happy** | joyful, content, excited, proud, hopeful, relieved, grateful, peaceful, playful, amused, curious, inspired, confident, loved, comforted, energized |
+| **Sad** | sad, lonely, disappointed, heartbroken, grieving, hopeless, empty, discouraged, melancholic, homesick, hurt, miserable, regretful, ashamed, inferior |
+| **Anxious** | anxious, worried, afraid, terrified, panicked, nervous, uneasy, insecure, overwhelmed, stressed, tense, apprehensive, startled, suspicious, vulnerable |
+| **Angry** | annoyed, irritated, frustrated, angry, enraged, bitter, resentful, jealous, envious, indignant, impatient, hostile, contemptuous |
+| **Tired** | tired, exhausted, drained, burnedOut, numb, bored, unmotivated, apathetic, restless |
+| **Calm** | calm, relaxed, atEase, balanced, stable, secure, safe, centered, grounded, accepting |
+| **Connected** | connected, accepted, included, belonging, appreciated, valued, respected, supported, protective, compassionate, empathetic |
+| **Mixed** | conflicted, confused, ambivalent, nostalgic, guilty, embarrassed, surprised, shocked, awestruck, skeptical |

package/ai/content-drawer.md

@@ -1,33 +1,32 @@
 # Content Drawer
 
-Responsive sliding panel that switches between push mode (desktop) and overlay mode (mobile).
+Responsive master-detail layout that automatically switches between **push mode** (desktop side panel) and **overlay mode** (mobile bottom sheet).
 
-## Service API
+## Quick Start
 
 ```typescript
 import { schmancyContentDrawer } from '@schmancy/content-drawer'
-```
-
-### `push(options)`
-
-Push a component to the drawer. Component types are passed directly to the area router - no resolution happens in the drawer service.
 
-**Parameters:**
+// Push content to drawer - ALWAYS use props pattern
+schmancyContentDrawer.push({
+  component: ItemDetail,
+  props: { itemId: '123' }
+})
+```
 
-- `options: ComponentType | DrawerPushOptions`
+## Service API
 
-**ComponentType formats (matches area router API):**
+```typescript
+import { schmancyContentDrawer } from '@schmancy/content-drawer'
+```
 
-- `string` - HTML tag name (e.g., `'demo-button'`)
-- `HTMLElement` - Component instance (e.g., `new MyComponent()`)
-- `CustomElementConstructor` - Component class (e.g., `UserDetails`)
-- `LazyComponent<any>` - Lazy import (e.g., `lazy(() => import('./my-component'))`)
+### `push(options)` - Recommended
 
-**DrawerPushOptions object:**
+Push a component to the drawer. Creates a fresh instance each time.
 
 ```typescript
-{
-  component: ComponentType
+interface DrawerPushOptions {
+  component: ComponentType      // Component class, tag name, or lazy import
   props?: Record<string, unknown>    // Properties to set on component
   state?: Record<string, unknown>    // Router state (push mode only)
   params?: Record<string, unknown>   // Router params (push mode only)
@@ -37,59 +36,62 @@ Push a component to the drawer. Component types are passed directly to the area
 **Usage:**
 
 ```typescript
-// String tag
-schmancyContentDrawer.push('demo-button')
-
-// HTMLElement instance
-schmancyContentDrawer.push(new UserDetail())
-
-// Component class (constructor)
-schmancyContentDrawer.push(UserDetails)
-
-// With options object (recommended)
+// Component class with props (RECOMMENDED)
 schmancyContentDrawer.push({
   component: UserDetails,
   props: { userId: '123' }
 })
 
+// String tag name
+schmancyContentDrawer.push({
+  component: 'user-details',
+  props: { userId: '123' }
+})
+
 // Lazy import
 import { lazy } from '@schmancy/area'
-schmancyContentDrawer.push(lazy(() => import('./my-component')))
+schmancyContentDrawer.push({
+  component: lazy(() => import('./user-details')),
+  props: { userId: '123' }
+})
 ```
 
-### `render(ref, component, title?)`
-
-Lower-level API for rendering. Use `push()` instead for most cases.
-
-**Parameters:**
+### `dimiss(ref)` - Close Drawer
 
-- `ref: Element | Window` - Element to dispatch events from
-- `component: HTMLElement` - Component instance
-- `title?: string` - Optional title
+Closes the drawer panel. Note: typo in actual API (`dimiss` not `dismiss`).
 
 ```typescript
-schmancyContentDrawer.render(window, new UserDetail(), 'User Details')
+schmancyContentDrawer.dimiss(window)
 ```
 
-### `dimiss(ref)`
+### `render(ref, component, title?)` - Low-level API
 
-Closes the drawer. *Note: typo in actual API*
+Lower-level API for manual control. Prefer `push()` for most cases.
 
 ```typescript
-schmancyContentDrawer.dimiss(window)
+schmancyContentDrawer.render(window, new UserDetail(), 'User Details')
 ```
 
 ## Component Structure
 
 ```html
 <schmancy-content-drawer>
+  <!-- Main content (list/master view) -->
   <schmancy-content-drawer-main>
-    <!-- Main content area -->
+    <schmancy-list>
+      ${items.map(item => html`
+        <schmancy-list-item @click=${() => this.selectItem(item)}>
+          ${item.name}
+        </schmancy-list-item>
+      `)}
+    </schmancy-list>
   </schmancy-content-drawer-main>
 
+  <!-- Detail panel (sheet view) -->
   <schmancy-content-drawer-sheet>
     <section slot="placeholder">
-      <!-- Empty state content -->
+      <!-- Empty state when nothing selected -->
+      <p>Select an item to view details</p>
     </section>
   </schmancy-content-drawer-sheet>
 </schmancy-content-drawer>
@@ -97,43 +99,134 @@ schmancyContentDrawer.dimiss(window)
 
 ## Properties
 
-- `minWidth: {main: number, sheet: number}` - Minimum widths (default: `{main: 360, sheet: 576}`)
-- `open: 'open' | 'close'` - Auto-managed based on mode
-- `mode: 'push' | 'overlay'` - Auto-switches at 936px breakpoint
+### `<schmancy-content-drawer>`
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `minWidth` | `{main: number, sheet: number}` | `{main: 360, sheet: 576}` | Minimum widths for panels |
+| `open` | `'open' \| 'close'` | Auto | Panel state (auto-managed) |
+| `mode` | `'push' \| 'overlay'` | Auto | Display mode (auto-switches at breakpoint) |
+
+### `<schmancy-content-drawer-sheet>`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `minWidth` | `number` | Override sheet minimum width |
 
 ## How It Works
 
-The drawer service is a simple passthrough to the area router:
+The drawer automatically switches modes based on available width:
 
-1. **Push mode (desktop)**: Calls `area.push()` with your component
-2. **Overlay mode (mobile)**: Calls `sheet.open()` with your component
+| Mode | Breakpoint | Behavior |
+|------|------------|----------|
+| **Push** | >= 936px (main + sheet) | Side panel slides in, main content shrinks |
+| **Overlay** | < 936px | Bottom sheet modal overlays content |
 
-Component resolution is handled entirely by the area router - the drawer service just dispatches events.
+**Internal routing:**
 
-## Example
+- **Push mode**: Uses `area.push()` with `historyStrategy: 'silent'`
+- **Overlay mode**: Uses `sheet.open()` as a modal
+
+## Common Patterns
+
+### Master-Detail List
+
+```typescript
+@customElement('my-list-page')
+class MyListPage extends LitElement {
+  @state() items: Item[] = []
+
+  private selectItem(item: Item) {
+    schmancyContentDrawer.push({
+      component: ItemDetail,
+      props: { itemId: item.id }
+    })
+  }
+
+  render() {
+    return html`
+      <schmancy-content-drawer>
+        <schmancy-content-drawer-main>
+          <schmancy-list>
+            ${repeat(this.items, i => i.id, item => html`
+              <schmancy-list-item @click=${() => this.selectItem(item)}>
+                ${item.name}
+              </schmancy-list-item>
+            `)}
+          </schmancy-list>
+        </schmancy-content-drawer-main>
+
+        <schmancy-content-drawer-sheet>
+          <section slot="placeholder" class="h-full flex items-center justify-center">
+            <div class="text-center">
+              <schmancy-icon class="text-6xl text-surface-300">list</schmancy-icon>
+              <schmancy-typography>Select an item</schmancy-typography>
+            </div>
+          </section>
+        </schmancy-content-drawer-sheet>
+      </schmancy-content-drawer>
+    `
+  }
+}
+```
+
+### With Custom Min Widths
 
 ```typescript
 html`
-  <schmancy-content-drawer>
-    <schmancy-content-drawer-main>
-      <schmancy-list>
-        ${items.map(item => html`
-          <schmancy-list-item @click=${() => {
-            // Pass component class directly - area router handles instantiation
-            schmancyContentDrawer.push({
-              component: ItemDetail,
-              props: { item }
-            })
-          }}>
-            ${item.name}
-          </schmancy-list-item>
-        `)}
-      </schmancy-list>
-    </schmancy-content-drawer-main>
-
-    <schmancy-content-drawer-sheet>
-      <section slot="placeholder">Select an item</section>
-    </schmancy-content-drawer-sheet>
+  <schmancy-content-drawer .minWidth=${{ main: 400, sheet: 600 }}>
+    <schmancy-content-drawer-main>...</schmancy-content-drawer-main>
+    <schmancy-content-drawer-sheet .minWidth=${600}>...</schmancy-content-drawer-sheet>
   </schmancy-content-drawer>
 `
 ```
+
+## Important Notes
+
+### Always Use `props` Pattern
+
+**DO NOT** create component instances manually - use the `props` pattern:
+
+```typescript
+// WRONG - instance won't update on subsequent pushes
+const viewer = new ItemDetail()
+viewer.itemId = '123'
+schmancyContentDrawer.push({ component: viewer })
+
+// CORRECT - fresh instance created each time
+schmancyContentDrawer.push({
+  component: ItemDetail,
+  props: { itemId: '123' }
+})
+```
+
+### Subsequent Pushes
+
+Each `push()` call replaces the current sheet content. The drawer creates a fresh component instance with the provided props.
+
+### Placeholder Slot
+
+The `placeholder` slot in `<schmancy-content-drawer-sheet>` shows when no content has been pushed. Use it for empty states.
+
+### Layout Integration
+
+The content drawer works best as a flex child:
+
+```typescript
+html`
+  <section class="grid grid-rows-[auto_1fr]" ${fullHeight()}>
+    <schmancy-nav-drawer-appbar>Header</schmancy-nav-drawer-appbar>
+    <schmancy-content-drawer class="flex-1">
+      ...
+    </schmancy-content-drawer>
+  </section>
+`
+```
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `schmancy-content-drawer-toggle` | `{ state: 'open' \| 'close' }` | Drawer open/close |
+| `schmancy-content-drawer-render` | `{ component, props, state, params }` | Content render request |
+| `schmancy-content-drawer-resize` | - | Triggers recalculation |