@mhmo91/schmancy 0.9.2 → 0.9.4

package/ai/mixins.md

@@ -1,70 +1,99 @@
-# Schmancy Mixins
+# `$LitElement`
 
-> Base classes and utilities: `$LitElement`, `disconnecting`, `classMap`, `styleMap`.
+Base class for Schmancy components. Extends `LitElement` with RxJS cleanup, Tailwind support, and cross-shadow discovery.
 
-## $LitElement
-
-The base class for all Schmancy components. Extends LitElement with Tailwind support and RxJS cleanup.
+## Usage
 
 ```typescript
-import { $LitElement } from '@mhmo91/schmancy/dist/mixins'
-import { css } from 'lit'
+import { $LitElement } from '@mhmo91/schmancy/mixins'
+import { customElement } from 'lit/decorators.js'
+import { css, html } from 'lit'
 
 @customElement('my-component')
-class MyComponent extends $LitElement(css`:host { display: block }`) {
-  // ...
+class MyComponent extends $LitElement(css`
+  :host { display: block; }
+`) {
+  render() {
+    return html`<slot></slot>`
+  }
 }
 ```
 
-## Provided Features
+`$LitElement(style?)` accepts either a Lit `css` tagged literal or a string (e.g. SCSS imported with `?inline`).
+
+## Provided members
 
-### disconnecting (Subject)
-RxJS Subject that emits when the component is disconnected. Use with `takeUntil` for automatic cleanup.
+### `disconnecting: Subject<void>`
+Emits once when the element disconnects. Pair with `takeUntil` for cleanup:
 
 ```typescript
 connectedCallback() {
   super.connectedCallback()
   someObservable$.pipe(
-    takeUntil(this.disconnecting)
+    takeUntil(this.disconnecting),
   ).subscribe()
 }
 ```
 
-### classMap(classes)
-Enhanced version of Lit's `classMap` that splits space-separated keys.
+### `classMap(obj)`
+Wraps Lit's `classMap` so keys can be space-separated:
 
 ```typescript
-// Supports space-separated class keys (unlike standard classMap)
-class=${this.classMap({
+html`<div class=${this.classMap({
   'flex items-center gap-2': true,
-  'bg-primary-default': this.active,
-})}
+  'opacity-50': this.disabled,
+})}></div>`
 ```
 
-**Critical:** Must be the SOLE expression in `class=`. Never mix with string interpolation.
+Must be the only expression in `class=` — don't mix with string interpolation.
 
-### styleMap(styles)
-Direct passthrough to Lit's `styleMap` directive.
+### `styleMap(obj)`
+Passthrough to Lit's `styleMap`.
 
 ```typescript
-style=${this.styleMap({ width: '100px', opacity: this.visible ? 1 : 0 })}
+html`<div style=${this.styleMap({ width: `${w}px` })}></div>`
 ```
 
-### discover(tag)
-Find components by tag name via event-based discovery.
+### `discover<T>(tag): Observable<T | null>`
+Find another Schmancy component by tag via event-based handshake. Works across shadow DOM.
 
 ```typescript
-this.discover<MyOtherComponent>('my-other-component').pipe(
-  takeUntil(this.disconnecting)
-).subscribe(component => { ... })
+this.discover<SchmancyDialog>('schmancy-dialog').pipe(
+  takeUntil(this.disconnecting),
+).subscribe(dialog => dialog?.setDefaultAction('confirm'))
 ```
 
-### stableId / uid
-- `stableId`: Deterministic ID based on DOM path (stable across renders)
-- `uid`: Unique instance ID (auto-generated or set via attribute)
+### Auto-response to discovery
+Every `$LitElement` responds to `{its-tag}-where-are-you` events with `{its-tag}-here-i-am` carrying `{ detail: { component: this } }`.
+
+## Component skeleton
+
+```typescript
+@customElement('my-component')
+export class MyComponent extends $LitElement(css`:host { display: block }`) {
+  @property({ type: String, reflect: true }) variant: 'a' | 'b' = 'a'
+  @state() private _open = false
+
+  connectedCallback() {
+    super.connectedCallback()
+    // subscriptions here, with takeUntil(this.disconnecting)
+  }
+
+  render() {
+    return html`<slot></slot>`
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'my-component': MyComponent
+  }
+}
+```
 
-### dispatchScopedEvent(name, detail, options)
-Dispatches both a scoped event (`name::uid`) and generic event for backward compatibility.
+## Rules
 
-### locale
-Current locale from theme context, falls back to `navigator.language`.
+- Call `super.connectedCallback()` / `super.disconnectedCallback()` when overriding.
+- All RxJS subscriptions end with `.pipe(takeUntil(this.disconnecting))`.
+- Register the tag in `HTMLElementTagNameMap` for TypeScript.
+- Don't mix `classMap` with string interpolation in the same attribute.

package/ai/option.md

@@ -0,0 +1,43 @@
+# schmancy-option
+
+> Selectable item for `schmancy-select`, `schmancy-autocomplete`, and `schmancy-menu`. Lightweight and a11y-ready.
+
+## Usage
+```html
+<schmancy-select label="Country">
+  <schmancy-option value="us">United States</schmancy-option>
+  <schmancy-option value="de">Germany</schmancy-option>
+  <schmancy-option value="jp" disabled>Japan</schmancy-option>
+</schmancy-select>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `value` | string | `''` | Value reported when this option is selected |
+| `label` | string | auto | Display label (falls back to text content) |
+| `selected` | boolean | `false` | Reflects selected state |
+| `disabled` | boolean | `false` | Disables interaction |
+| `group` | string | `''` | Grouping identifier for grouped lists |
+| `icon` | string | `''` | Material icon name before the label |
+
+## Events
+| Event | Payload | When |
+|-------|---------|------|
+| `click` | — | Standard click event |
+| `option-select` | `CustomEvent<{ value, label }>` | Dispatched on activation |
+
+## Behavior
+- Auto-generates `id` for ARIA wiring if not set.
+- Infers `label` from text content when omitted.
+- Keyboard focusable with a visible focus ring via `:focus-visible`.
+- Parent select/autocomplete coordinates selection state via slot query.
+
+## Example — grouped options
+```html
+<schmancy-select label="Framework">
+  <schmancy-option value="lit" group="web" icon="bolt">Lit</schmancy-option>
+  <schmancy-option value="react" group="web">React</schmancy-option>
+  <schmancy-option value="swift" group="mobile">Swift</schmancy-option>
+</schmancy-select>
+```

package/ai/page.md

@@ -0,0 +1,42 @@
+# schmancy-page
+
+> Native mobile-like page container. Fills remaining viewport height, prevents rubber-banding, pull-to-refresh, and double-tap zoom.
+
+## Usage
+```html
+<schmancy-page rows="auto_1fr_auto">
+  <header>App bar</header>
+  <main>Scrollable content</main>
+  <footer>Bottom nav</footer>
+</schmancy-page>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `rows` | string | `'auto_1fr_auto'` | Grid template rows — underscores become spaces (e.g. `'1fr_2fr_auto'`) |
+| `show-scrollbar` | boolean | `false` | Display scrollbar on scrollable area |
+| `no-select` | boolean | `false` | Disable text selection |
+
+## Behavior
+- Listens to `visualViewport` resize/scroll + `orientationchange` + keyboard focus events to recompute height.
+- Accounts for theme bottom offset (iOS safe area, home indicator).
+- Auto-assigns semantic elements (`header`, `main`, `footer`) to slots.
+- Inner scroll area uses `schmancy-scroll` for momentum-preserving scroll.
+
+## When to Use
+- Root of a mobile view or panel that should feel like a native page.
+- Any container where viewport-aware height + scroll containment matters.
+
+## Example — 3-row app shell
+```html
+<schmancy-page rows="auto_1fr_auto">
+  <schmancy-surface type="solid" rounded="none">
+    <schmancy-typography type="title">My App</schmancy-typography>
+  </schmancy-surface>
+
+  <div class="p-4">…scrollable content…</div>
+
+  <schmancy-navigation-bar></schmancy-navigation-bar>
+</schmancy-page>
+```

package/ai/qr-scanner.md

@@ -0,0 +1,51 @@
+# schmancy-qr-scanner
+
+> Camera-based QR code scanner using `jsQR`. Requests rear-camera access, decodes frames in real time, deduplicates reads.
+
+## Usage
+```html
+<schmancy-qr-scanner
+  continuous
+  @scan-result=${e => this.handleScan(e.detail.data)}
+></schmancy-qr-scanner>
+```
+
+```typescript
+handleScan(data: string) {
+  console.log('QR decoded:', data)
+}
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `continuous` | boolean | `true` | Keep scanning after a successful read (dedupe repeated reads) |
+
+## Events
+| Event | Detail | When |
+|-------|--------|------|
+| `scan-result` | `{ data: string, timestamp: number }` | QR code successfully decoded |
+
+## Behavior
+- Requests `getUserMedia` with `facingMode: 'environment'` (rear camera) at 1280×720.
+- Decodes via `jsQR` on `animationFrames` stream with `throttleTime` to avoid CPU thrashing.
+- `distinctUntilChanged` prevents duplicate emissions for the same code.
+- Brief success flash on each valid read.
+- Stops camera + tears down subscriptions on disconnect.
+- Displays an error state if camera permission is denied.
+
+## Requires
+- HTTPS (or `localhost`) for camera access.
+- User permission to the camera.
+
+## Example
+```html
+<schmancy-surface type="glass" rounded="all">
+  <schmancy-qr-scanner
+    @scan-result=${(e: CustomEvent<{ data: string }>) => {
+      $notify.success(`Scanned: ${e.detail.data}`)
+      this.scannedCode = e.detail.data
+    }}
+  ></schmancy-qr-scanner>
+</schmancy-surface>
+```

package/ai/range.md

@@ -0,0 +1,47 @@
+# schmancy-range
+
+> Numeric slider input with theme-driven track gradient and focus halo.
+
+## Usage
+```html
+<schmancy-range
+  label="Volume"
+  min="0"
+  max="100"
+  step="1"
+  .value=${50}
+  @change=${e => this.volume = e.detail.value}
+></schmancy-range>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `min` | number | `0` | Minimum value |
+| `max` | number | `1` | Maximum value |
+| `step` | number | `0.01` | Increment per tick |
+| `value` | number | `0` | Current value |
+| `label` | string | — | Optional label (current value displays on the right) |
+| `disabled` | boolean | `false` | Disabled state (38% opacity) |
+
+## Events
+| Event | Payload | When |
+|-------|---------|------|
+| `change` | `{ value: number }` | On input change |
+
+## Visual
+- Primary-colored track gradient (filled portion = primary, empty = 30% primary).
+- Circular thumb with hover halo (8px primary glow at 12% opacity).
+- Disabled state: 38% opacity, not-allowed cursor.
+
+## Example — precise float control
+```html
+<schmancy-range
+  label="Mass"
+  min="0.5"
+  max="2.0"
+  step="0.05"
+  .value=${this.mass}
+  @change=${(e: CustomEvent<{ value: number }>) => this.mass = e.detail.value}
+></schmancy-range>
+```

package/ai/rxjs-utils.md

@@ -0,0 +1,60 @@
+# Schmancy RxJS Utils
+
+> RxJS-wrapped DOM observation helpers. Use when you need to react to elements appearing, disappearing, or changing across the document.
+
+## Imports
+```typescript
+import {
+  mutationObserver,
+  waitForElement,
+  waitForElementAll,
+  waitForElements,
+  waitForElementsAll,
+  waitUntil,
+} from '@mhmo91/schmancy'
+```
+
+## `mutationObserver(target, options?)`
+RxJS wrapper around `MutationObserver`.
+```typescript
+mutationObserver(document.body, { childList: true, subtree: true })
+  .pipe(takeUntil(this.disconnecting))
+  .subscribe(mutations => { /* react */ })
+```
+
+## `waitForElement(selector, timeout = 5000)`
+Emits the first matching element once it exists in the DOM. Throws on timeout. Pass `undefined` to wait forever.
+```typescript
+waitForElement('#auth-banner').subscribe(el => el.focus())
+waitForElement('.lazy-panel', 10000).subscribe(el => el.click())
+```
+
+## `waitForElementAll(selector, timeout?)`
+Emits whenever the matching set changes (all current matches).
+```typescript
+waitForElementAll('.live-tile').subscribe(tiles => {
+  tiles.forEach(t => observe(t))
+})
+```
+
+## `waitForElements([sel1, sel2, ...], timeout?)` / `waitForElementsAll`
+Multi-selector variants — resolve once *any*/`every` selector is present.
+
+## `waitUntil([selectors], timeout = 5000)`
+Emits once when **all** selectors have matches. Throws on timeout.
+```typescript
+waitUntil(['header', 'main', 'footer'])
+  .subscribe(() => console.log('Page shell ready'))
+```
+
+## How It Works
+All helpers share `mutationObserver(document.body)` with `childList: true, subtree: true` and `.startWith(document.body)` so they check once immediately and re-check on every DOM mutation.
+
+## When to Use
+- Integrating third-party scripts that inject DOM late.
+- Coordinating with slot-projected children that may mount asynchronously.
+- Awaiting app-shell elements before attaching shortcuts.
+
+## When NOT to Use
+- Inside your own component — use `firstUpdated()` or `queryAssignedElements`.
+- For cross-shadow discovery — use [discovery](./discovery.md) instead.

package/ai/slider.md

@@ -0,0 +1,43 @@
+# schmancy-slider / schmancy-slide
+
+> Horizontal snap-scrolling carousel with optional arrow controls.
+
+## Usage
+```html
+<schmancy-slider show-arrows>
+  <schmancy-slide>
+    <img src="a.jpg" />
+  </schmancy-slide>
+  <schmancy-slide>
+    <div class="p-8">Second slide</div>
+  </schmancy-slide>
+  <schmancy-slide>
+    <div class="p-8">Third slide</div>
+  </schmancy-slide>
+</schmancy-slider>
+```
+
+## schmancy-slider Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `showArrows` | boolean | `true` | Render prev/next navigation buttons |
+
+## Events
+| Event | Payload | When |
+|-------|---------|------|
+| `slide-changed` | `{ index: number }` | Centered slide changes after scroll settles |
+
+## Behavior
+- Each `schmancy-slide` is sized to `flex: 0 0 100%` of the slider.
+- `scroll-snap-type: x mandatory` — scroll always lands on a slide.
+- Scrollbars hidden across browsers.
+- Scroll events throttled to 100ms for stable index tracking.
+- Arrow buttons scroll to previous/next slide when `show-arrows` is true.
+
+## Example — programmatic control
+```typescript
+const slider = this.renderRoot.querySelector('schmancy-slider')
+slider?.addEventListener('slide-changed', (e: CustomEvent<{ index: number }>) => {
+  this.activeIndex = e.detail.index
+})
+```

package/ai/store.md

@@ -1,83 +1,126 @@
-# Schmancy Store (Context System)
+# Store — Context System
 
-> Reactive state management with `createContext`, `@select` decorator, and persistent storage.
+Reactive state management: `createContext`, `@select`, `@selectItem`.
+
+## Creating a context
 
-## Creating a Context
 ```typescript
 import { createContext } from '@mhmo91/schmancy'
 
-// Object store
-const userContext = createContext({ name: '', email: '' }, 'local', 'user')
+// Object
+const userContext = createContext<User>(new User(), 'local', 'user')
 
-// Collection store (Map-based)
-const itemsContext = createContext(new Map<string, Item>(), 'indexeddb', 'items')
+// Map (collection)
+const itemsContext = createContext<Map<string, Item>>(new Map(), 'indexeddb', 'items')
 
-// Array store
-const tagsContext = createContext<string>([], 'memory', 'tags')
+// Array
+const tagsContext = createContext<string[]>([], 'memory', 'tags')
 ```
 
-## Storage Types
-| Type | Description |
-|------|-------------|
-| `'memory'` | In-memory only (lost on refresh) |
-| `'local'` | localStorage (persistent) |
-| `'session'` | sessionStorage (per tab) |
-| `'indexeddb'` | IndexedDB (large data, persistent) |
+Signature: `createContext(initial, storage, key)`.
+
+## 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 |
+
+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`
 
-## Reading State with @select
 ```typescript
 import { select } from '@mhmo91/schmancy'
 
 @customElement('my-component')
 class MyComponent extends $LitElement() {
-  // Auto-subscribes to context changes, triggers re-render
-  @select(userContext)
-  user!: { name: string; email: string }
+  @select(userContext) user!: User
 
-  // With selector function
-  @select(itemsContext, (items) => items.size)
-  itemCount!: number
+  // Selector narrows the dependency
+  @select(itemsContext, m => m.size) count!: number
 
-  // Collection as Map
-  @select(itemsContext)
-  items!: Map<string, Item>
+  @select(itemsContext) items!: Map<string, Item>
 }
 ```
 
-## Writing State
+`@select` options:
+- `required` (default `true`) — wait for `.ready` before `connectedCallback` completes.
+- `updateOnly` — call `requestUpdate` without assigning.
+- `deepClone` — `structuredClone` the value.
+- `debug` — log every emission.
+
+## `@selectItem`
+
+Pick one entry from a collection context, keyed off a component property:
+
 ```typescript
-// Object store
-userContext.set({ name: 'Alice', email: 'alice@test.com' })
+@selectItem(itemsContext, component => component.itemId)
+item!: Item | undefined
+```
 
-// Collection store
-itemsContext.set('item-1', { name: 'Widget' })
-itemsContext.delete('item-1')
-itemsContext.replace(new Map([...]))
+## Writing
 
-// Array store
-tagsContext.push('new-tag')
-tagsContext.replace(['a', 'b', 'c'])
+```typescript
+// 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
-// Subscribe to changes
 userContext.$.pipe(
-  takeUntil(this.disconnecting)
-).subscribe(user => { ... })
+  filter(() => userContext.ready),
+  takeUntil(this.disconnecting),
+).subscribe(user => { /* ... */ })
 
-// Current value (synchronous)
-const current = userContext.value
-
-// Ready state
-if (userContext.ready) { ... }
+userContext.value       // synchronous snapshot
+userContext.ready       // true once the backing store has loaded
 ```
 
-## @select Options
-`required` (default true): wait for value before connectedCallback. `updateOnly`: only requestUpdate. `deepClone`: structuredClone. `debug`: log activity.
+Gate subscriptions on `.ready` — `'local'` / `'session'` / `'indexeddb'` contexts emit their default value before the real stored value hydrates.
+
+## Dynamic contexts
+
+For per-instance state with persistence, create the context inside `connectedCallback` with an instance-scoped key:
 
-## selectItem (Collection Helper)
 ```typescript
-@selectItem(itemsContext, (component) => component.itemId)
-selectedItem!: Item | undefined
+private draftCtx: IStore<{ text: string }> | null = null
+
+connectedCallback() {
+  super.connectedCallback()
+  if (this.draftKey) {
+    this.draftCtx = createContext<{ text: string }>(
+      { text: '' },
+      'session',
+      this.draftKey,
+    )
+  }
+}
 ```
+
+## Rules
+
+- 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/ai/teleport.md

@@ -0,0 +1,55 @@
+# schmancy-teleport
+
+> Move DOM between locations with a FLIP-animated transition. Two instances sharing an `id` handshake via broadcast events — when one mounts, it finds the other and flies the content between them.
+
+## Usage
+```html
+<!-- Start position -->
+<schmancy-teleport id="hero-image">
+  <img src="portrait.jpg" alt="" />
+</schmancy-teleport>
+
+<!-- Later, in a different view -->
+<schmancy-teleport id="hero-image"></schmancy-teleport>
+```
+
+When the second instance mounts, the image smoothly animates from its old bounding rect to the new one.
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `id` | string | **required** | Shared identifier between source and target |
+| `uuid` | number | auto | Instance UUID for disambiguation (read-only) |
+| `delay` | number | `0` | Delay before teleporting (ms) |
+
+## Discovery Events
+The service broadcasts on `window`:
+- `FINDING_MORTIES` — "is anyone mounted with id X?"
+- `HERE_RICKY` — instances reply with self reference
+- `WhereAreYouRicky` / `HereMorty` — instance-to-instance handshake
+
+Uses RxJS with a race/throwIfEmpty pattern to handle missing counterparts gracefully.
+
+## Typical Pattern — route transitions
+```html
+<!-- List view -->
+${repeat(items, item => item.id, item => html`
+  <schmancy-teleport id=${`card-${item.id}`}>
+    <schmancy-card @click=${() => router.push(`/item/${item.id}`)}>
+      <img src=${item.thumbnail} />
+    </schmancy-card>
+  </schmancy-teleport>
+`)}
+
+<!-- Detail view -->
+<schmancy-teleport id=${`card-${this.params.id}`}></schmancy-teleport>
+```
+
+## Notes
+- Uses `watchElementRect` (ResizeObserver + scroll tracking) to keep source/target in sync.
+- Animation uses the FLIP technique: capture first rect, invert on mount, play to final.
+- All subscriptions clean up via `takeUntil(this.disconnecting)`.
+- Each teleport pair must share a unique `id` string.
+
+## See Also
+- For programmatic teleportation from JS: import `teleportationService` from `@mhmo91/schmancy/teleport`.