@mhmo91/schmancy 0.9.3 → 0.9.4

package/ai/store.md

@@ -1,192 +1,126 @@
-# Store — State Foundation
+# Store — Context System
 
-> **Not a utility. The state backbone of a Schmancy app.**
-> `createContext` + `@select` replaces Redux, Zustand, and a route-scoped cache without ceremony.
-
-A real app runs *many* small contexts — not one monolith. Typical production apps sit around 8–10:
-
-```
-userContext          ('local')      — signed-in user (persists across sessions)
-organizationContext  ('local')      — current org
-appStateContext      ('local')      — core app state (lists, selections, flags)
-agentsContext        ('memory')     — fetched data (re-fetched on reload)
-contactsContext      ('memory')     — Map<id, Contact> — mass data
-templatesContext     ('memory')     — list fetched from server
-currentTemplateIdCtx ('local')      — small pointer ref that persists
-composeContext       ('local')      — draft form state
-draftCtx             ('session')    — per-thread chat input (tab-scoped)
-strictCtx            ('session')    — per-thread toggles (tab-scoped)
-```
-
-**Split by persistence tier + lifetime**, not by feature area. Per-component ephemeral state → `session`. Cached fetches → `memory`. User-saved preferences → `local`. Large cached data → `indexeddb`.
+Reactive state management: `createContext`, `@select`, `@selectItem`.
 
 ## Creating a context
 
 ```typescript
 import { createContext } from '@mhmo91/schmancy'
 
-// Object store — persisted to localStorage
-export const userContext = createContext<User>(new User(), 'local', 'user')
-
-// Collection store — Map keyed by id
-export const contactsContext = createContext<Map<string, Contact>>(new Map(), 'memory', 'contacts')
+// Object
+const userContext = createContext<User>(new User(), 'local', 'user')
 
-// Array store — ordered list
-export const tagsContext = createContext<string[]>([], 'memory', 'tags')
+// Map (collection)
+const itemsContext = createContext<Map<string, Item>>(new Map(), 'indexeddb', 'items')
 
-// Session-scoped (per browser tab)
-export const draftContext = createContext<{ text: string }>({ text: '' }, 'session', 'compose-draft')
+// Array
+const tagsContext = createContext<string[]>([], 'memory', 'tags')
 ```
 
-### Storage tiers
+Signature: `createContext(initial, storage, key)`.
 
-| Mode | Backing | Survives refresh? | Survives tab close? | Size |
-|------|---------|-------------------|---------------------|------|
-| `'memory'` | JS heap | ❌ | ❌ | small |
+## Storage backends
+
+| Mode | Backing | Survives refresh | Survives tab close | Capacity |
+|------|---------|------------------|--------------------|----------|
+| `'memory'` | JS heap | ❌ | ❌ | RAM |
 | `'session'` | `sessionStorage` | ✅ | ❌ (per-tab) | ~5 MB |
 | `'local'` | `localStorage` | ✅ | ✅ | ~5 MB |
 | `'indexeddb'` | IndexedDB | ✅ | ✅ | GB |
 
-Rule of thumb:
-- **User session data, prefs, drafts meant to persist** → `'local'`
-- **Per-tab ephemeral data** (wizard progress, per-thread drafts) → `'session'`
-- **Fetched from API, regenerable** → `'memory'`
-- **Large arrays, file-like data, offline-first** → `'indexeddb'`
+Pick by data size and lifetime:
+- User prefs, long-lived drafts → `'local'`
+- Per-tab ephemeral (cart, wizard) → `'session'`
+- Fetched from API, regenerable → `'memory'`
+- Collections with >100 entries you want cached → `'indexeddb'`
 
 ## Reading with `@select`
 
 ```typescript
 import { select } from '@mhmo91/schmancy'
 
-@customElement('user-card')
-class UserCard extends $LitElement() {
-  // Auto-subscribes, re-renders on change
+@customElement('my-component')
+class MyComponent extends $LitElement() {
   @select(userContext) user!: User
 
-  // Selector function narrows the dependency
-  @select(contactsContext, m => m.size) contactCount!: number
+  // Selector narrows the dependency
+  @select(itemsContext, m => m.size) count!: number
 
-  // Collection → stays as Map
-  @select(contactsContext) contacts!: Map<string, Contact>
+  @select(itemsContext) items!: Map<string, Item>
 }
 ```
 
 `@select` options:
-- `required` (default `true`) — wait for context `.ready` before `connectedCallback` completes.
-- `updateOnly` — only call `requestUpdate`, don't assign. Use when you read the value imperatively.
-- `deepClone` — `structuredClone` the value to prevent accidental mutation.
+- `required` (default `true`) — wait for `.ready` before `connectedCallback` completes.
+- `updateOnly` — call `requestUpdate` without assigning.
+- `deepClone` — `structuredClone` the value.
 - `debug` — log every emission.
 
-### Pick one item from a collection
-```typescript
-@selectItem(contactsContext, component => component.contactId)
-contact!: Contact | undefined
-```
-
-Use this on components that carry the key as a property (e.g. `this.contactId`) — avoids reading the whole map.
+## `@selectItem`
 
-## Writing state
+Pick one entry from a collection context, keyed off a component property:
 
-### Object store
 ```typescript
-userContext.set({ name: 'Alice', email: 'alice@test.com' })
-userContext.set({ ...userContext.value, name: 'Bob' })  // partial update pattern
+@selectItem(itemsContext, component => component.itemId)
+item!: Item | undefined
 ```
 
-### Collection (Map) store
-```typescript
-contactsContext.set('id-1', { id: 'id-1', name: 'Alice' })
-contactsContext.delete('id-1')
-contactsContext.replace(new Map([/* fresh batch */]))
-```
+## Writing
 
-### Array store
 ```typescript
-tagsContext.push('new-tag')
-tagsContext.replace(['a', 'b', 'c'])
+// Object
+userContext.set({ name: 'Alice' })
+userContext.set({ ...userContext.value, name: 'Bob' })
+
+// Map
+itemsContext.set('id-1', item)
+itemsContext.delete('id-1')
+itemsContext.replace(newMap)
+
+// Array
+tagsContext.push('new')
+tagsContext.replace(['a', 'b'])
 ```
 
 ## Observable API
 
 ```typescript
-connectedCallback() {
-  super.connectedCallback()
+userContext.$.pipe(
+  filter(() => userContext.ready),
+  takeUntil(this.disconnecting),
+).subscribe(user => { /* ... */ })
 
-  userContext.$.pipe(
-    filter(() => userContext.ready),               // gate on initialization
-    distinctUntilChanged((a, b) => a.id === b.id), // ignore unrelated writes
-    switchMap(user => this.loadForUser(user)),     // cascade load
-    takeUntil(this.disconnecting),                 // cleanup
-  ).subscribe(data => this.data = data)
-}
+userContext.value       // synchronous snapshot
+userContext.ready       // true once the backing store has loaded
 ```
 
-- **`ctx.$`** — a `BehaviorSubject`. Use for chained transforms.
-- **`ctx.value`** — synchronous snapshot.
-- **`ctx.ready`** — boolean; becomes `true` after the backing store has loaded.
+Gate subscriptions on `.ready` — `'local'` / `'session'` / `'indexeddb'` contexts emit their default value before the real stored value hydrates.
 
-### The gating pattern
-Every non-trivial subscription starts with `filter(() => ctx.ready)`. When your context is backed by `indexeddb` or re-hydrated from `localStorage`, the initial default value is emitted before the real stored value lands. Gate on `.ready` to skip the default.
+## Dynamic contexts
 
-## Dynamic contexts (per-instance)
-
-For per-component ephemeral state that still benefits from persistence, instantiate the context **inside** `connectedCallback` with an instance-specific key:
+For per-instance state with persistence, create the context inside `connectedCallback` with an instance-scoped key:
 
 ```typescript
-import { createContext, IStore } from '@mhmo91/schmancy'
-
-@customElement('chat-input')
-class ChatInput extends $LitElement() {
-  @property() draftKey?: string
-
-  private draftCtx: IStore<{ text: string }> | null = null
-
-  connectedCallback() {
-    super.connectedCallback()
-
-    if (this.draftKey) {
-      this.draftCtx = createContext<{ text: string }>(
-        { text: '' },
-        'session',
-        this.draftKey,          // e.g. `chat-draft-${threadId}`
-      )
-
-      // Hydrate once
-      this.draftCtx.$.pipe(
-        filter(() => this.draftCtx!.ready),
-        take(1),
-        tap(v => { this.text = v.text }),
-      ).subscribe()
-    }
-  }
+private draftCtx: IStore<{ text: string }> | null = null
 
-  private onInput(v: string) {
-    this.text = v
-    this.draftCtx?.set({ text: v })
+connectedCallback() {
+  super.connectedCallback()
+  if (this.draftKey) {
+    this.draftCtx = createContext<{ text: string }>(
+      { text: '' },
+      'session',
+      this.draftKey,
+    )
   }
 }
 ```
 
-This is the pattern for *every* "draft that persists until sent" input.
-
-## Architectural rules
-
-1. **Declare contexts at module scope**, not inside classes — except dynamic per-instance ones.
-2. **Name the storage key** even for `'memory'` contexts — it helps debugging.
-3. **Keep each context small and single-purpose**. 9 small contexts beat 1 god context.
-4. **Subscribe with `takeUntil(this.disconnecting)`** — every time, no exceptions.
-5. **Gate on `.ready`** before any async cascading work.
-6. **Only the owning component writes**. Everyone else reads via `@select`.
-7. **Don't put functions, observables, or class instances into context** — only plain serializable data (for `'local'` / `'session'` / `'indexeddb'`).
-
-## Anti-patterns
-
-- ❌ Storing Promises in context. Use `memory` contexts for cached fetch *results*, not the in-flight Promise.
-- ❌ Cross-writing: component A writes to context X which is "owned" by component B. Centralize writes.
-- ❌ One monolithic `appContext` holding everything. You lose `distinctUntilChanged` granularity.
-- ❌ Forgetting `.ready` — causes double-fires on load with stale default values.
-- ❌ Using `'local'` for large blobs — hits quota, blocks the main thread on stringify/parse.
+## Rules
 
-## See also
-- [mixins](./mixins.md) — `$LitElement` provides `disconnecting` for every subscription.
-- [area](./area.md) — routing + contexts compose naturally (guards read context state).
+- Declare contexts at module scope (except dynamic per-instance ones).
+- Name the storage key even for `'memory'` contexts — it helps debugging.
+- Keep each context single-purpose. One write shouldn't invalidate unrelated readers.
+- Only the owning component writes. Others read via `@select`.
+- Every subscription uses `takeUntil(this.disconnecting)`.
+- Gate on `.ready` before async cascading work.
+- Don't store Promises, Observables, functions, or class instances in persistent contexts.

package/dist/ai/INDEX.md

@@ -1,321 +1,72 @@
-# Schmancy AI Index
+# Schmancy — Documentation Index
 
-> Single-file navigation for AI agents. Foundations first, then components sorted by **what job they do**.
+A Web Component UI library on Lit + RxJS + Tailwind CSS.
 
-Schmancy is not just a component library. It's four concentric layers:
+## Foundations
 
-```
-┌─ FOUNDATIONS ──────────────────────────────────────┐
-│   Routing · State · Base class · Theme · Directives │
-│   (Not components. The framework your app runs on.) │
-├─ ATOMS ────────────────────────────────────────────┤
-│   Typography · Icons · Surfaces · Buttons · Scroll  │
-│   (The vocabulary every screen repeats.)            │
-├─ COMPOSITES ───────────────────────────────────────┤
-│   Forms · Navigation · Overlays · Feedback · Data   │
-│   (Job-specific components.)                        │
-└─ UTILITIES ────────────────────────────────────────┘
-    Discovery · RxJS helpers · Search · Numbers · etc.
-```
+The framework pieces — touch before components.
 
-**Most of a Schmancy app is foundations + atoms + services.** Composites are reached for when a real user-facing job needs them. Start in that order.
+- [Area](./area.md) — `<schmancy-area>`, `<schmancy-route>`, `area.push()`, `lazy()` for routing.
+- [Store](./store.md) — `createContext`, `@select`, `@selectItem`, storage backends.
+- [Mixins](./mixins.md) — `$LitElement` base class.
+- [Theme](./theme.md) — `<schmancy-theme>`, color scheme, CSS variables.
+- [Directives](./directives.md) — Lit directives for physics, effects, text, visibility, interaction.
+- [Animation](./animation.md) — Spring presets (`SPRING_SMOOTH`, etc.), `createAnimation`.
 
----
+## Components by job
 
-# Layer 1 — Foundations
+### Display
+[Typography](./typography.md) · [Icons](./icons.md) · [Avatar](./avatar.md) · [Divider](./divider.md) · [Badge](./badge.md) · [Code Highlight](./code-highlight.md) · [Typewriter](./typewriter.md) · [JSON](./json.md) · [Iframe](./iframe.md) · [Map](./map.md) · [Charts](./charts.md)
 
-These are the load-bearing pieces. Touch them wrong and everything above breaks.
+### Surfaces & layout
+[Surface](./surface.md) · [Card](./card.md) · [Scroll / Grid / Flex](./layout.md) · [Page](./page.md) · [Content Drawer](./content-drawer.md) · [Window](./window.md) · [Boat](./boat.md) · [Float](./float.md)
 
-## 1.1 Routing — `area` + `schmancy-area` + `schmancy-route`
-**Job:** Control which component occupies a region of the screen, with browser history, guards, params, and lazy loading.
+### Forms
+[Form](./form.md) · [Input](./input.md) · [Textarea](./textarea.md) · [Select](./select.md) · [Autocomplete](./autocomplete.md) · [Option](./option.md) · [Checkbox](./checkbox.md) · [Radio Group](./radio-group.md) · [Chips](./chips.md) · [Date Range](./date-range.md) · [Date Range Inline](./date-range-inline.md) · [Range](./range.md) · [Extra (Country/Timezone)](./extra.md)
 
-```typescript
-import { area, lazy } from '@mhmo91/schmancy'
-```
+### Navigation
+[Nav Drawer](./nav-drawer.md) · [Tabs](./tabs.md) · [Navigation Bar](./navigation-bar.md) · [Navigation Rail](./navigation-rail.md) · [Steps](./steps.md) · [Teleport](./teleport.md) · [Theme Button](./theme-button.md)
 
-```html
-<schmancy-area name="root" .default=${lazy(() => import('./home.page'))}>
-  <schmancy-route when="home-page" .component=${lazy(() => import('./home.page'))} />
-  <schmancy-route when="dashboard"
-    .component=${lazy(() => import('./dashboard.page'))}
-    .guard=${firebaseAuth$.pipe(map(u => !!u), takeUntil(this.disconnecting))}
-    @redirect=${() => area.push({ area: 'root', component: 'home-page', historyStrategy: 'replace' })}
-  />
-</schmancy-area>
-```
+### Overlays
+[Dialog](./dialog.md) · [Sheet](./sheet.md) · [Notification](./notification.md) · [Menu](./menu.md) · [Dropdown](./dropdown.md) · [Tooltip](./tooltip.md) · [Lightbox](./lightbox.md) · [Expand](./expand.md)
 
-- **Named areas**: multiple independent regions, 2-level nesting common (`name="root"` + `name="aria"` inside the outer shell).
-- **Guards are Observables**: subscribe, emit `boolean`; when `false` a `redirect` event fires.
-- **Lazy is mandatory** for route components — `lazy(() => import('...'))` returns a preloadable reference.
-- **`when="tag-name"` must exactly match** `@customElement('tag-name')`.
-- **Programmatic navigation**: `area.push({ area, component, params?, historyStrategy? })`.
-- **Subscribe to route state**: `area.on('root').pipe(takeUntil(this.disconnecting)).subscribe(...)`.
+### Interactive
+[Button](./button.md) · [List](./list.md) · [Details](./details.md) · [Table](./table.md) · [Tree](./tree.md) · [Slider](./slider.md) · [QR Scanner](./qr-scanner.md)
 
-→ Full doc: [area.md](./area.md)
+### Feedback
+[Progress](./progress.md) · [Busy](./busy.md) · [Connectivity](./connectivity.md) · [Delay](./delay.md)
 
-## 1.2 State — `createContext` + `@select`
-**Job:** App-wide reactive state with storage, without Redux boilerplate.
+### Domain
+[Mailbox](./mailbox.md)
 
-```typescript
-import { createContext, select } from '@mhmo91/schmancy'
+## Services (imperative APIs)
 
-// Declare once at module scope
-export const userContext = createContext<User>(new User(), 'local', 'user')
-export const sessionContext = createContext<Session>({}, 'session', 'session')
-export const cacheContext = createContext<Map<string, Item>>(new Map(), 'memory', 'cache')
+| Service | Purpose |
+|---------|---------|
+| `area` | Route navigation (see [area](./area.md)) |
+| `$dialog` | Open dialogs (see [dialog](./dialog.md)) |
+| `$notify` | Toast notifications (see [notification](./notification.md)) |
+| `schmancyContentDrawer` | Side panel (see [content-drawer](./content-drawer.md)) |
+| `theme` | Theme state, `fullscreen$` (see [theme](./theme.md)) |
+| `sound` | Audio feedback (see [audio](./audio.md)) |
+| `overlayStack` | Z-index coordinator (see [utils](./utils.md)) |
+| `windowManager` | Window registry (see [window](./window.md)) |
 
-// Consume in a component — auto-subscribes and re-renders
-@customElement('my-component')
-class MyComponent extends $LitElement() {
-  @select(userContext) user!: User
+## Utilities
 
-  firstUpdated() {
-    // Gate on readiness; chain with RxJS; clean up on disconnect
-    userContext.$.pipe(
-      filter(() => userContext.ready),
-      distinctUntilChanged((a, b) => a.id === b.id),
-      switchMap(u => this.loadForUser(u)),
-      takeUntil(this.disconnecting),
-    ).subscribe()
-  }
-}
-```
+[Discovery](./discovery.md) — cross-shadow component lookup.
+[RxJS Utils](./rxjs-utils.md) — `waitForElement`, `waitUntil`, `mutationObserver`.
+[Utils](./utils.md) — `similarity`, `numbers`, `overlayStack`, `intersection$`, `hashContent`.
+[Audio](./audio.md) — synthesized feedback sounds.
 
-- **Storage modes**: `'memory'` · `'local'` · `'session'` · `'indexeddb'`.
-- **Collection-aware**: `Map` and `Array` contexts get `.set(k,v)`, `.delete(k)`, `.push(v)`, `.replace(...)` helpers.
-- **`.ready`** is a boolean — gate async work behind `filter(() => ctx.ready)`.
-- **`.$`** is a BehaviorSubject — compose with RxJS.
-- **`.value`** is the synchronous snapshot.
-- **`@selectItem`** for picking one entry from a collection context.
+## Conventions
 
-**Real architectures use many small contexts** (aria runs 9: user, organization, app state, templates, contacts, agents, compose, draft, strict) — not one monolith.
-
-→ Full doc: [store.md](./store.md)
-
-## 1.3 Base class — `$LitElement`
-**Job:** Every Schmancy component extends this. It wires RxJS cleanup, Tailwind, and cross-shadow discovery into every element.
-
-```typescript
-import { $LitElement } from '@mhmo91/schmancy/mixins'
-
-@customElement('my-component')
-class MyComponent extends $LitElement(css`:host { display: block }`) {
-  connectedCallback() {
-    super.connectedCallback()
-    // The `disconnecting` Subject emits once on disconnect
-    myObservable$.pipe(takeUntil(this.disconnecting)).subscribe()
-  }
-}
-```
-
-Provides: `disconnecting` (RxJS Subject) · `classMap()` (space-splitting) · `styleMap()` · `discover<T>(tag)` · Tailwind support · auto-response to discovery events.
-
-**Rule of thumb:** if you're writing a Lit component inside a Schmancy app, extend `$LitElement`. No exceptions.
-
-→ Full doc: [mixins.md](./mixins.md)
-
-## 1.4 Theme — `schmancy-theme` + `theme` service
-**Job:** Provide color scheme (dark/light), brand color, and CSS custom properties to everything below it.
-
-```html
-<schmancy-theme root scheme="dark" color="#6366F1">
-  <!-- entire app -->
-</schmancy-theme>
-```
-
-- One `root` theme per app, typically wrapping `schmancy-surface type="solid" fill="all"`.
-- Nested `<schmancy-theme>` can re-scope color/scheme for a subtree.
-- CSS vars auto-generated: `--schmancy-sys-color-{role}-{variant}`.
-- `theme.fullscreen$` — observable of viewport fullscreen state.
-
-→ Full doc: [theme.md](./theme.md)
-
-## 1.5 Directives — behavior without components
-**Job:** Attach physics, effects, visibility, and interactions to *any* element via Lit directive syntax. 19 directives, modular imports.
-
-```typescript
-import { magnetic, cursorGlow, gravity, reveal, animateText, tooltip, drag, drop } from '@mhmo91/schmancy/directives'
-```
-
-```html
-<schmancy-card ${cursorGlow()} ${gravity({ stagger: 100 })}>...</schmancy-card>
-<div ${reveal(this.expanded, { preset: 'smooth' })}>expandable content</div>
-<span ${animateText({ animation: 'blur-reveal' })}>Hello</span>
-<button ${tooltip('Save your changes')}>Save</button>
-```
-
-Categories:
-- **Physics**: `magnetic`, `cursorGlow`, `livingBorder`, `gravity`, `depthOfField`, `longPress`
-- **Effects**: `nebula`, `liquid`, `ripple`
-- **Text**: `animateText`, `cycleText`, `typewriter`
-- **Visibility**: `reveal`, `intersect`
-- **Interaction**: `drag`, `drop`, `color`, `tooltip`
-
-→ Full doc: [directives.md](./directives.md)
-
----
-
-# Layer 2 — Atoms
-
-The display vocabulary. You'll use these on nearly every screen.
-
-| Job | Tag | Doc |
-|-----|-----|-----|
-| **Text** | `schmancy-typography` | [typography](./typography.md) |
-| **Iconography** | `schmancy-icon`, `schmancy-icon-button` | [icons](./icons.md), [button](./button.md) |
-| **Primary actions** | `schmancy-button` | [button](./button.md) |
-| **Glass depth container** | `schmancy-surface` | [surface](./surface.md) |
-| **Scroll region** | `schmancy-scroll` | [layout](./layout.md) |
-| **Visual separation** | `schmancy-divider` | [divider](./divider.md) |
-| **Profile image** | `schmancy-avatar` | [avatar](./avatar.md) |
-
----
-
-# Layer 3 — Composites (sorted by job)
-
-## Forms — collect input
-| Job | Tag | Doc |
-|-----|-----|-----|
-| Validation container | `schmancy-form` | [form](./form.md) |
-| Single-line text | `schmancy-input` | [input](./input.md) |
-| Multi-line text | `schmancy-textarea` | [textarea](./textarea.md) |
-| Single-choice dropdown | `schmancy-select` + `schmancy-option` | [select](./select.md), [option](./option.md) |
-| Searchable dropdown | `schmancy-autocomplete` | [autocomplete](./autocomplete.md) |
-| Boolean | `schmancy-checkbox` | [checkbox](./checkbox.md) |
-| One-of-many | `schmancy-radio-group` | [radio-group](./radio-group.md) |
-| Multi-select tags / filters | `schmancy-chips` | [chips](./chips.md) |
-| Date / date range | `schmancy-date-range`, `schmancy-date-range-inline` | [date-range](./date-range.md), [date-range-inline](./date-range-inline.md) |
-| Numeric slider | `schmancy-range` | [range](./range.md) |
-| Country / timezone | `schmancy-select-countries`, `schmancy-select-timezones` | [extra](./extra.md) |
-
-## Navigation — structural layout
-| Job | Tag | Doc |
-|-----|-----|-----|
-| App shell with side drawer | `schmancy-nav-drawer` (+ navbar, content) | [nav-drawer](./nav-drawer.md) |
-| Tabbed sub-views | `schmancy-tabs` | [tabs](./tabs.md) |
-| Mobile bottom nav | `schmancy-navigation-bar` | [navigation-bar](./navigation-bar.md) |
-| Desktop side rail | `schmancy-navigation-rail` | [navigation-rail](./navigation-rail.md) |
-| Multi-step flow | `schmancy-steps` | [steps](./steps.md) |
-| Master-detail split | `schmancy-content-drawer` | [content-drawer](./content-drawer.md) |
-| Viewport-aware page root | `schmancy-page` | [page](./page.md) |
-| Floating draggable panel | `schmancy-window`, `schmancy-boat`, `schmancy-float` | [window](./window.md), [boat](./boat.md), [float](./float.md) |
-| FLIP transition between views | `schmancy-teleport` | [teleport](./teleport.md) |
-
-## Overlays — temporarily above everything (services preferred)
-| Job | API | Fallback tag | Doc |
-|-----|-----|--------------|-----|
-| Modal / confirm | **`$dialog()` service** | `schmancy-dialog` | [dialog](./dialog.md) |
-| Toast / banner | **`$notify()` service** | `schmancy-notification` | [notification](./notification.md) |
-| Side/bottom panel | **`schmancyContentDrawer.open()`** | `schmancy-sheet` | [sheet](./sheet.md) |
-| Context menu | `schmancy-menu` | — | [menu](./menu.md) |
-| Floating panel | `schmancy-dropdown` | — | [dropdown](./dropdown.md) |
-| Hover hint | `tooltip` directive | `schmancy-tooltip` | [tooltip](./tooltip.md), [directives](./directives.md) |
-| Image gallery | `schmancy-lightbox` | — | [lightbox](./lightbox.md) |
-| Accordion | `schmancy-expand` | `schmancy-details` | [expand](./expand.md), [details](./details.md) |
-
-**Service > component for overlays.** Real apps call `$dialog()` / `$notify()` / `schmancyContentDrawer.open()` hundreds of times — managing overlay lifecycle imperatively keeps templates clean.
-
-## Interaction — actionable content
-| Job | Tag | Doc |
-|-----|-----|-----|
-| Clickable container | `schmancy-card` | [card](./card.md) |
-| Selectable list | `schmancy-list` + `schmancy-list-item` | [list](./list.md) |
-| Expandable row | `schmancy-details` | [details](./details.md) |
-| Tabular data | `schmancy-table` | [table](./table.md) |
-| Hierarchical data | `schmancy-tree` | [tree](./tree.md) |
-| Carousel | `schmancy-slider` + `schmancy-slide` | [slider](./slider.md) |
-| Camera QR scan | `schmancy-qr-scanner` | [qr-scanner](./qr-scanner.md) |
-
-## Feedback — status / progress
-| Job | Tag | Doc |
-|-----|-----|-----|
-| Linear progress | `schmancy-progress` | [progress](./progress.md) |
-| Spinner / skeleton overlay | `schmancy-busy` | [busy](./busy.md) |
-| Status indicator | `schmancy-badge` | [badge](./badge.md) |
-| Online/offline banner | `schmancy-connectivity-status` | [connectivity](./connectivity.md) |
-| Deferred render with stagger | `schmancy-delay` | [delay](./delay.md) |
-
-## Rich display — specialized rendering
-| Job | Tag | Doc |
-|-----|-----|-----|
-| Syntax-highlighted code | `schmancy-code-highlight` | [code-highlight](./code-highlight.md) |
-| Typewriter reveal | `schmancy-typewriter` | [typewriter](./typewriter.md) |
-| JSON viewer (debug) | `schmancy-json` | [json](./json.md) |
-| Sandboxed iframe | `schmancy-iframe` | [iframe](./iframe.md) |
-| Google Maps | `schmancy-map` | [map](./map.md) |
-| Area chart | `schmancy-area-chart` | [charts](./charts.md) |
-| Horizontal pills chart | `schmancy-pills` | [charts](./charts.md) |
-| Theme toggle button | `schmancy-theme-button` | [theme-button](./theme-button.md) |
-
-## Domain — specific to a workflow
-| Job | Tag | Doc |
-|-----|-----|-----|
-| Email composition | `schmancy-mailbox` (+ 5 sub-tags) | [mailbox](./mailbox.md) |
-
-## Layout primitives (prefer Tailwind for new code)
-| Job | Tag | Doc |
-|-----|-----|-----|
-| Grid / flex / scroll | `schmancy-grid`, `schmancy-flex`, `schmancy-scroll`, `sch-grid`, `sch-flex` | [layout](./layout.md) |
-
----
-
-# Layer 4 — Utilities (non-component)
-
-| Module | Purpose | Doc |
-|--------|---------|-----|
-| Audio | Synthesized emotional sounds (`sound.play('joyful')`) | [audio](./audio.md) |
-| Discovery | Cross-shadow-DOM component lookup | [discovery](./discovery.md) |
-| RxJS utils | `waitForElement`, `waitUntil`, `mutationObserver` | [rxjs-utils](./rxjs-utils.md) |
-| Utils | `similarity`, `numbers`, `overlayStack`, `intersection$`, `hashContent` | [utils](./utils.md) |
-| Animation | Spring presets, `createAnimation`, Tailwind integration | [animation](./animation.md) |
-
----
-
-# The 80/20 cheat sheet
-
-If you're new to Schmancy and shipping a screen today, reach for these in this order:
-
-1. **Wrap the app** in `<schmancy-theme root>` + `<schmancy-surface type="solid" fill="all">` + `<schmancy-scroll>`.
-2. **Route** with `<schmancy-area name="root">` + `<schmancy-route>` + `lazy()`.
-3. **Store** state in `createContext(..., 'local')` + `@select` in components.
-4. **Extend** `$LitElement` in every component. Use `takeUntil(this.disconnecting)` for every subscription.
-5. **Compose screens** from atoms: `schmancy-typography`, `schmancy-icon`, `schmancy-button`, `schmancy-surface`, `schmancy-divider`.
-6. **Forms**: `schmancy-input` + `schmancy-chips` + `schmancy-checkbox` + `schmancy-form`. Reach for `schmancy-select` / `schmancy-autocomplete` only when needed.
-7. **Overlays**: `$dialog()` + `$notify()` + `schmancyContentDrawer.open()` — service APIs, not template tags.
-8. **Effects**: reach for `cursorGlow`, `magnetic`, `reveal`, `animateText` directives before writing CSS animations.
-
-Everything else is demand-driven.
-
----
-
-# Conventions (enforce these)
-
-- **Lists use `repeat(items, item => item.id, tpl)`** — never `.map()` in templates.
-- **View switching uses `cache(...)`** — preserves DOM and state.
-- **Expensive work uses `guard([deps], fn)`** — memoizes against identity changes.
-- **DOM access uses `ref(createRef())`** — never `querySelector` for own shadow tree if a ref will do.
-- **Conditionals use `when(...)` / `choose(...)` / `ifDefined(...)`** — cleaner than ternaries.
-- **All subscriptions use `.pipe(takeUntil(this.disconnecting))`** — no manual unsubscribe.
-- **No `setTimeout` / `setInterval` / `addEventListener`** — use RxJS (`timer`, `interval`, `fromEvent`).
-- **No hardcoded colors** — use `--schmancy-sys-color-*` CSS vars or Tailwind theme classes.
-- **No mixing `classMap` with string interpolation** — it must be the sole expression in `class=`.
-- **ARIA wiring on combobox forms**: `role="combobox"` + `aria-haspopup="listbox"` + `aria-expanded` + `aria-controls` + a `#live-status` live region.
-- **Overlay z-index**: always go through `overlayStack` (dialogs/sheets/windows already do).
-
----
-
-# Services reference (import these by name)
-
-| Service | From | Purpose |
-|---------|------|---------|
-| `area` | `@mhmo91/schmancy` | Router imperative API |
-| `$dialog` | `@mhmo91/schmancy` | Modal/confirm dialogs |
-| `$notify` | `@mhmo91/schmancy` | Toast notifications |
-| `schmancyContentDrawer` | `@mhmo91/schmancy` | Side panel |
-| `theme` | `@mhmo91/schmancy` | Theme state + fullscreen$ |
-| `sound` | `@mhmo91/schmancy` | Emotional sounds |
-| `overlayStack` | `@mhmo91/schmancy` | Z-index coordinator |
-| `windowManager` | `@mhmo91/schmancy/window` | Window registry |
-| `teleportationService` | `@mhmo91/schmancy/teleport` | Teleport coordination |
-| `reducedMotion$` | `@mhmo91/schmancy/directives` | Reactive reduced-motion preference |
-| `fromResizeObserver` | `@mhmo91/schmancy/directives` | RxJS ResizeObserver |
+- Lists use `repeat(items, item => item.id, tpl)`.
+- View switching uses `cache(...)`.
+- Expensive work uses `guard([deps], fn)`.
+- DOM access uses `ref(createRef())`.
+- Conditionals use `when(...)`, `choose(...)`, `ifDefined(...)`.
+- All RxJS subscriptions end with `.pipe(takeUntil(this.disconnecting))`.
+- Don't use `setTimeout` / `setInterval` / `addEventListener` — use RxJS (`timer`, `interval`, `fromEvent`).
+- Colors come from `--schmancy-sys-color-*` CSS vars or Tailwind theme classes.
+- `classMap(...)` must be the sole expression in `class=`; never mix with string interpolation.