@mhmo91/schmancy 0.9.4 → 0.9.6

package/skills/schmancy/area.md

@@ -0,0 +1,141 @@
+# Area — Routing
+
+Schmancy's client-side router. Three pieces:
+
+| Piece | Role |
+|-------|------|
+| `<schmancy-area name="...">` | Named region that renders one route at a time |
+| `<schmancy-route when="tag">` | Declares which component can render in an area |
+| `area.push(...)` | Imperative navigation |
+
+Areas can be nested to compose shell-plus-sub-view layouts.
+
+## Example
+
+```html
+<schmancy-area name="root" .default=${lazy(() => import('./pages/home.page'))}>
+  <schmancy-route when="home-page"
+    .component=${lazy(() => import('./pages/home.page'))}></schmancy-route>
+
+  <schmancy-route when="app-index"
+    .component=${lazy(() => import('./app/app.page'))}
+    .guard=${authState$.pipe(
+      map(u => !!u && !u.isAnonymous),
+      takeUntil(this.disconnecting),
+    )}
+    @redirect=${() => area.push({
+      component: 'home-page',
+      area: 'root',
+      historyStrategy: 'replace',
+    })}></schmancy-route>
+</schmancy-area>
+```
+
+## `schmancy-area` properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | string (required) | Area identifier used in `area.push({ area })` |
+| `default` | `RouteComponent \| string` | Fallback when no route matches |
+
+## `schmancy-route` properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `when` | string (required) | Must match a `@customElement('tag')` tag name |
+| `component` | `RouteComponent` (required) | Class, tag name, or `lazy()` wrapper |
+| `guard` | `Observable<boolean>` | When emits `false`, blocks and dispatches `redirect` event |
+| `exact` | boolean | Strict-equality matching |
+
+## `area` service
+
+```typescript
+import { area } from '@mhmo91/schmancy'
+
+area.push({
+  area: 'root',
+  component: 'app-index',
+  params?: { id: '123' },
+  historyStrategy?: 'push' | 'replace' | 'silent',
+})
+```
+
+`historyStrategy`:
+- `'push'` (default) — adds a browser-history entry
+- `'replace'` — overwrites the current entry (use after guards or redirects)
+- `'silent'` — changes the area without touching history
+
+### Subscribe to route state
+
+```typescript
+area.on('root').pipe(
+  takeUntil(this.disconnecting),
+).subscribe(route => { /* route.component, route.params */ })
+
+area.params<{ id: string }>('detail').pipe(
+  takeUntil(this.disconnecting),
+).subscribe(params => this.loadItem(params.id))
+```
+
+## Lazy loading
+
+```typescript
+import { lazy } from '@mhmo91/schmancy'
+const HomePage = lazy(() => import('./home.page'))
+
+// Optional preload
+html`<button @mouseenter=${() => HomePage.preload()}>Home</button>`
+```
+
+## Guards
+
+`guard` is an Observable<boolean>.
+
+- Emits `true` → route renders.
+- Emits `false` → route dispatches a `redirect` event. Handle it with `area.push(...)`.
+
+Auth guard:
+
+```typescript
+<schmancy-route when="app-index"
+  .component=${lazy(() => import('./app'))}
+  .guard=${authState$.pipe(
+    map(u => !!u),
+    takeUntil(this.disconnecting),
+  )}
+  @redirect=${() => area.push({
+    component: 'home-page', area: 'root', historyStrategy: 'replace',
+  })}></schmancy-route>
+```
+
+Compound guard (multiple streams):
+
+```typescript
+.guard=${combineLatest([permissions$, orgContext.$]).pipe(
+  takeUntil(this.disconnecting),
+  map(([perms, org]) => perms.includes('billing.view') && org?.billing?.configured),
+)}
+```
+
+## Nested areas
+
+Areas nest by rendering an inner `<schmancy-area>` inside a route component. A common shape is an outer area for "signed-in vs. not" and an inner area for sub-views of the signed-in shell.
+
+```html
+<!-- outer -->
+<schmancy-area name="root">
+  <schmancy-route when="app-index" .component=${AppShell}></schmancy-route>
+</schmancy-area>
+
+<!-- inner (inside AppShell.render()) -->
+<schmancy-area name="app" default="home-page">
+  <schmancy-route when="home-page" .component=${...}></schmancy-route>
+  <schmancy-route when="settings-page" .component=${...}></schmancy-route>
+</schmancy-area>
+```
+
+## Rules
+
+- `when="tag-name"` must match `@customElement('tag-name')` exactly.
+- Guards emit `false` → always use `historyStrategy: 'replace'` in the `@redirect` handler.
+- Every subscription in guards / route state uses `takeUntil(this.disconnecting)`.

package/skills/schmancy/audio.md

@@ -0,0 +1,69 @@
+# Schmancy Audio
+
+> Emotional sound service — synthesizes short, empathetic sounds via Web Audio API keyed on feelings (joyful, tense, calm, etc.). No assets. No external players. Just tones + puffs generated on demand.
+
+## Usage
+```typescript
+import { sound } from '@mhmo91/schmancy'
+
+sound.play('joyful')     // trigger a feeling sound
+sound.setVolume(0.2)     // 0..1
+sound.setMuted(true)
+sound.resetTheme()       // back to defaults
+```
+
+## Feelings
+Organized by emotional category:
+
+| Category | Feelings |
+|----------|----------|
+| Happy | `joyful`, `content`, `excited`, `grateful`, `proud`, `loved` |
+| Sad | `sad`, `disappointed`, `hurt`, `lonely`, `melancholy` |
+| Anxious | `worried`, `nervous`, `overwhelmed`, `tense` |
+| Angry | `frustrated`, `angry`, `annoyed` |
+| Tired | `tired`, `drained`, `bored` |
+| Calm | `calm`, `peaceful`, `relaxed`, `focused` |
+| Connected | `connected`, `supported`, `welcomed` |
+| Mixed | `confused`, `nostalgic`, `bittersweet` |
+
+(See `mood-audio.types.ts` for the authoritative list.)
+
+## Observable API
+```typescript
+sound.theme$.subscribe(theme => console.log(theme?.name ?? 'default'))
+sound.volume$.subscribe(v => {})
+sound.muted$.subscribe(m => {})
+```
+
+## Settings Persistence
+Volume, mute, and custom theme persist to `localStorage` under key `schmancy-sound-settings` (via `createContext`).
+
+## AI-Generated Themes
+```typescript
+import type { SoundTheme } from '@mhmo91/schmancy'
+
+const customTheme: SoundTheme = {
+  name: 'ocean',
+  sounds: {
+    joyful: { puffs: [...], tones: [...] },
+    // partial override — falls through to defaults for anything omitted
+  }
+}
+
+sound.setTheme(customTheme)
+```
+
+Each `FeelingSound` consists of:
+- **puffs** — short bursts (air/noise, e.g. `{ startTime, duration, frequency, volume }`)
+- **tones** — oscillators (`sine`/`triangle`/`square`/`sawtooth` with envelope)
+
+## Built-in Feedback Hooks
+Other Schmancy components play these automatically:
+- [`schmancy-connectivity-status`](./connectivity.md) on offline/online.
+- Some success/error paths in notifications and dialogs via the `$sounds` legacy helper.
+
+## Legacy API
+- `$sounds` — older generator exported for compatibility.
+- `EmotionalSoundGenerator` — underlying class.
+
+Prefer `sound` for new code.

package/skills/schmancy/autocomplete.md

@@ -0,0 +1,53 @@
+# schmancy-autocomplete
+
+> Searchable input with fuzzy filtering, single/multi-select, and inline chip display.
+
+## Usage
+```html
+<schmancy-autocomplete label="Assignee" placeholder="Search...">
+  <schmancy-option value="alice" label="Alice"></schmancy-option>
+  <schmancy-option value="bob" label="Bob"></schmancy-option>
+</schmancy-autocomplete>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| value | string | `''` | Selected value (single) or comma-separated (multi) |
+| values | string[] | `[]` | Selected values (multi-select) |
+| label | string | `''` | Label text |
+| placeholder | string | `''` | Placeholder text |
+| name | string | `''` | Form submission name |
+| required | boolean | `false` | Whether selection is required |
+| multi | boolean | `false` | Enable multi-select with inline chips |
+| size | `'xs'\|'sm'\|'md'\|'lg'` | `'md'` | Input height |
+| maxHeight | string | `'300px'` | Max dropdown height |
+| debounceMs | number | `200` | Search debounce in ms |
+| similarityThreshold | number | `0.3` | Minimum fuzzy match score (0-1) |
+| error | boolean | `false` | Error state |
+| validationMessage | string | `''` | Validation message |
+| description | string | `''` | Screen reader description |
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| change | `{ value: string \| string[], values?: string[] }` | When selection changes |
+
+## Examples
+```html
+<!-- Multi-select with chips -->
+<schmancy-autocomplete label="Skills" multi placeholder="Type to search...">
+  <schmancy-option value="ts" label="TypeScript"></schmancy-option>
+  <schmancy-option value="lit" label="Lit"></schmancy-option>
+  <schmancy-option value="rxjs" label="RxJS"></schmancy-option>
+</schmancy-autocomplete>
+
+<!-- Single select, auto-selects best match on blur -->
+<schmancy-autocomplete label="City" placeholder="Search city..."
+  @change=${(e) => console.log(e.detail.value)}>
+  <schmancy-option value="berlin" label="Berlin"></schmancy-option>
+  <schmancy-option value="munich" label="Munich"></schmancy-option>
+</schmancy-autocomplete>
+```
+
+Children must be `<schmancy-option>` elements. In multi mode, selected items appear as removable chips.

package/skills/schmancy/avatar.md

@@ -0,0 +1,47 @@
+# schmancy-avatar
+
+> Avatar component displaying initials, image, or icon with color themes, shapes, and status indicators.
+
+## Usage
+```html
+<schmancy-avatar initials="JD" color="primary"></schmancy-avatar>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| initials | string | `''` | Text initials (max 2 characters) |
+| src | string | `''` | Image URL |
+| icon | string | `''` | Material icon name |
+| size | `'xxs'\|'xs'\|'sm'\|'md'\|'lg'\|'xl'` | `'md'` | Avatar size (20-64px) |
+| color | `'primary'\|'secondary'\|'tertiary'\|'success'\|'error'\|'neutral'` | `'primary'` | Color theme |
+| shape | `'circle'\|'square'` | `'circle'` | Avatar shape |
+| bordered | boolean | `false` | Show border ring |
+| status | `'online'\|'offline'\|'busy'\|'away'\|'none'` | `'none'` | Status indicator dot |
+
+## Size Reference
+| Token | Size | Description |
+|-------|------|-------------|
+| xxs | 20px | Ultra-compact |
+| xs | 24px | Compact |
+| sm | 32px | Small |
+| md | 40px | Default |
+| lg | 48px | Large |
+| xl | 64px | Extra large |
+
+## Examples
+```html
+<!-- Image avatar with status -->
+<schmancy-avatar src="/photos/alice.jpg" size="lg" status="online"></schmancy-avatar>
+
+<!-- Icon avatar -->
+<schmancy-avatar icon="group" color="secondary" shape="square"></schmancy-avatar>
+
+<!-- Bordered initials -->
+<schmancy-avatar initials="AB" color="tertiary" bordered></schmancy-avatar>
+
+<!-- Default (person icon) -->
+<schmancy-avatar size="sm" color="neutral"></schmancy-avatar>
+```
+
+Priority: `src` (image) > `initials` > `icon` > default person icon.

package/skills/schmancy/badge.md

@@ -0,0 +1,41 @@
+# schmancy-badge
+
+> Versatile badge for status indicators, labels, and counts with color variants and shapes.
+
+## Usage
+```html
+<schmancy-badge color="success">Active</schmancy-badge>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| color | `'primary'\|'secondary'\|'tertiary'\|'success'\|'warning'\|'error'\|'neutral'\|'surface'` | `'primary'` | Color variant |
+| size | `'xs'\|'sm'\|'md'\|'lg'` | `'md'` | Badge size |
+| shape | `'rounded'\|'pill'\|'square'` | `'pill'` | Badge shape |
+| outlined | boolean | `false` | Outlined style (transparent background) |
+| icon | string | `''` | Material icon name |
+| pulse | boolean | `false` | Pulse animation for attention |
+
+## Slots
+| Slot | Description |
+|------|-------------|
+| default | Badge text content |
+| icon | Custom icon content |
+
+## Examples
+```html
+<!-- Outlined badge -->
+<schmancy-badge color="error" outlined>Overdue</schmancy-badge>
+
+<!-- With icon -->
+<schmancy-badge color="success" icon="check_circle">Verified</schmancy-badge>
+
+<!-- Pulsing notification badge -->
+<schmancy-badge color="error" size="sm" pulse>3</schmancy-badge>
+
+<!-- Square shape -->
+<schmancy-badge color="neutral" shape="square">Draft</schmancy-badge>
+```
+
+**Tag aliases:** `<sch-badge>` (backward compatible)

package/skills/schmancy/boat.md

@@ -0,0 +1,47 @@
+# schmancy-boat
+
+> Draggable floating FAB that expands into a panel. Great for persistent assistant/chat panels.
+
+> **Note:** `schmancy-window` is the evolved successor with more capabilities (resize, maximize, multi-window registry). Prefer `schmancy-window` for new code unless you want the simpler FAB-to-panel model.
+
+## Usage
+```html
+<schmancy-boat id="assistant" icon="smart_toy" label="Assistant">
+  <div slot="header">Assistant</div>
+  <div class="p-4">Panel body content</div>
+</schmancy-boat>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `id` | string | `'default'` | Unique identifier (persists drag position in localStorage) |
+| `icon` | string | — | Material icon for the FAB state |
+| `label` | string | — | Label text in FAB state |
+| `open` | boolean | `false` | Panel open/closed (reflected) |
+| `corner` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | `'bottom-right'` | Anchor corner |
+| `expandedWidth` | string | responsive | e.g. `'320px'` |
+| `lowered` | boolean | `false` | Lower shadow in FAB state |
+
+## Getter / Setter
+```typescript
+boat.state = 'expanded' | 'collapsed'   // equivalent to open = true/false
+boat.state                              // current state
+boat.expand() / boat.close()
+```
+
+## Behavior
+- Drag to reposition. Releases snap to the nearest corner.
+- Open/close uses clip-path + `SPRING_SMOOTH` for elegant reveal.
+- Position persists in `localStorage` under `schmancy-boat-{id}`.
+- Respects `prefers-reduced-motion`.
+
+## Example
+```html
+<schmancy-boat id="chat" icon="chat" label="Chat" corner="bottom-right">
+  <span slot="header">Messages</span>
+  <schmancy-list class="p-2">
+    <!-- messages -->
+  </schmancy-list>
+</schmancy-boat>
+```

package/skills/schmancy/breadcrumb.md

@@ -0,0 +1,53 @@
+# schmancy-breadcrumb
+
+> Breadcrumb navigation with auto-inserted separators and ARIA landmark semantics.
+
+## Usage
+```html
+<schmancy-breadcrumb>
+  <schmancy-breadcrumb-item href="/">Home</schmancy-breadcrumb-item>
+  <schmancy-breadcrumb-item href="/projects">Projects</schmancy-breadcrumb-item>
+  <schmancy-breadcrumb-item current>Dashboard</schmancy-breadcrumb-item>
+</schmancy-breadcrumb>
+```
+
+## schmancy-breadcrumb
+
+Container. Renders a `<nav aria-label="Breadcrumb">` and inserts a separator element between each slotted item.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| separator | string | `'/'` | Character or string rendered between items. Hidden from assistive tech via `aria-hidden="true"`. |
+
+| Part | Description |
+|------|-------------|
+| separator | Each inserted separator element. Style bulk via `schmancy-breadcrumb::part(separator)`. |
+
+The host sets `aria-label="Breadcrumb"` on connection if none was already set.
+
+## schmancy-breadcrumb-item
+
+Individual crumb. Renders as `<a>` when `href` is set, otherwise `<span>`.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| href | string | `''` | When set (and `current` is false), renders as an anchor. |
+| current | boolean | `false` | Marks this item as `aria-current="page"`. Renders as a plain `<span>` even if `href` is set. |
+
+## Examples
+```html
+<!-- Custom separator -->
+<schmancy-breadcrumb separator="›">
+  <schmancy-breadcrumb-item href="/">Home</schmancy-breadcrumb-item>
+  <schmancy-breadcrumb-item href="/docs">Docs</schmancy-breadcrumb-item>
+  <schmancy-breadcrumb-item current>API</schmancy-breadcrumb-item>
+</schmancy-breadcrumb>
+```
+
+```html
+<!-- Two-level (just two crumbs) -->
+<schmancy-breadcrumb>
+  <schmancy-breadcrumb-item href="/users">Users</schmancy-breadcrumb-item>
+  <schmancy-breadcrumb-item current>Jane Doe</schmancy-breadcrumb-item>
+</schmancy-breadcrumb>
+```

package/skills/schmancy/busy.md

@@ -0,0 +1,36 @@
+# schmancy-busy
+
+> Full-overlay busy indicator with backdrop blur. Place inside a `position: relative` container.
+
+## Usage
+```html
+<div class="relative">
+  <p>Content underneath</p>
+  ${when(loading, () => html`<schmancy-busy></schmancy-busy>`)}
+</div>
+```
+
+## Properties
+No configurable properties. Renders a centered spinner overlay.
+
+## Slots
+| Slot | Description |
+|------|-------------|
+| default | Custom loading content (defaults to `<schmancy-spinner>`) |
+
+## Examples
+```html
+<!-- Default spinner -->
+<div class="relative h-64">
+  <schmancy-busy></schmancy-busy>
+</div>
+
+<!-- Custom loading content -->
+<div class="relative">
+  <schmancy-busy>
+    <schmancy-typography type="body" token="lg">Loading data...</schmancy-typography>
+  </schmancy-busy>
+</div>
+```
+
+The component uses `position: absolute; inset: 0` with `z-index: 50` and a subtle backdrop blur.

package/skills/schmancy/button.md

@@ -0,0 +1,59 @@
+# schmancy-button / schmancy-icon-button
+
+> Buttons with embedded `magnetic` directive, glow hover shadow, and spring press animation.
+
+## Usage
+```html
+<schmancy-button variant="filled" color="primary">Save</schmancy-button>
+<schmancy-icon-button icon="add"></schmancy-icon-button>
+```
+
+## Properties (schmancy-button)
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `variant` | `'elevated' \| 'filled' \| 'filled tonal' \| 'tonal' \| 'outlined' \| 'text'` | `'text'` | Visual style |
+| `color` | `'primary' \| 'secondary' \| 'success' \| 'error' \| 'warning' \| 'info' \| 'neutral'` | Auto | Color. Defaults to `primary` (or `secondary` for tonal) |
+| `size` | `'xxs' \| 'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Height: 24/32/40/48/56px |
+| `width` | `'full' \| 'auto'` | `'auto'` | Full-width or auto |
+| `type` | `'button' \| 'reset' \| 'submit'` | `'button'` | HTML button type |
+| `href` | `string` | `undefined` | Renders as `<a>` when set |
+| `disabled` | `boolean` | `false` | Disabled state (38% opacity) |
+
+## Properties (schmancy-icon-button)
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `icon` | `string` | `undefined` | Material icon name (preferred over slot content) |
+| `size` | `'xxs' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Icon size: 12/16/20/24/24/40px |
+| `variant` | Same as button | `'text'` | Visual style |
+| `text` | `boolean` | `false` | Render slot as text label instead of icon |
+| `disabled` | `boolean` | `false` | Disabled state |
+
+## Slots
+| Slot | Description |
+|------|-------------|
+| (default) | Button label text |
+| `prefix` | Leading content (images auto-sized) |
+| `suffix` | Trailing content (images auto-sized) |
+
+## Physics
+- **magnetic** directive embedded (strength: 3, radius: 60px for button, 50px for icon-button)
+- Hover: luminous glow shadow using primary color
+- Active: spring press `scale(0.97)` / `scale(0.92)` for icon-button
+
+## Examples
+```html
+<!-- Filled primary -->
+<schmancy-button variant="filled" color="primary">Submit</schmancy-button>
+
+<!-- Outlined error with icon prefix -->
+<schmancy-button variant="outlined" color="error" size="sm">
+  <schmancy-icon slot="prefix">delete</schmancy-icon>
+  Delete
+</schmancy-button>
+
+<!-- Icon button with explicit icon prop -->
+<schmancy-icon-button icon="settings" variant="tonal" size="sm"></schmancy-icon-button>
+
+<!-- Full-width submit -->
+<schmancy-button variant="filled" width="full" type="submit">Save Changes</schmancy-button>
+```

package/skills/schmancy/card.md

@@ -0,0 +1,53 @@
+# schmancy-card
+
+> Card container with luminous hover glow and spring press animation. Interactive cards get embedded `cursorGlow` directive.
+
+## Usage
+```html
+<schmancy-card type="elevated" interactive>
+  <div class="p-4">Card content</div>
+</schmancy-card>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `type` | `'elevated' \| 'filled' \| 'outlined'` | `'elevated'` | Visual style |
+| `interactive` | `boolean` | `false` | Enables click, cursorGlow, keyboard nav, ripple |
+| `disabled` | `boolean` | `false` | Disables interaction |
+| `dragged` | `boolean` | `false` | Elevated drag state with extra glow |
+| `href` | `string` | `undefined` | URL navigation on click |
+| `target` | `string` | `undefined` | Link target (e.g. `_blank`) |
+| `role` | `string` | `'article'` | ARIA role (auto-switches to `button`/`link` when interactive) |
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `schmancy-click` | `{ value: type }` | Fired on interactive card click |
+
+## Physics
+- **cursorGlow** directive on interactive cards (radius: 200, intensity: 0.1)
+- Hover: luminous glow + lift (`translateY(-2px)` for elevated, `-1px` for others)
+- Active: spring compress `scale(0.98)` with 100ms transition
+- Dragged: enhanced glow + `translateY(-4px)`
+
+## Examples
+```html
+<!-- Elevated clickable card -->
+<schmancy-card type="elevated" interactive>
+  <div class="p-4">
+    <h3 class="text-surface-on font-medium">Title</h3>
+    <p class="text-surface-on-variant">Description</p>
+  </div>
+</schmancy-card>
+
+<!-- Outlined static card -->
+<schmancy-card type="outlined">
+  <div class="p-4">Static content</div>
+</schmancy-card>
+
+<!-- Link card -->
+<schmancy-card type="filled" interactive href="/details" target="_blank">
+  <div class="p-4">Opens in new tab</div>
+</schmancy-card>
+```