@mhmo91/schmancy 0.9.28 → 0.10.2

package/dist/skills/schmancy/state.md

@@ -0,0 +1,501 @@
+# State — `@mhmo91/schmancy/state`
+
+Reactive state primitive. Module-scoped singletons keyed by namespace.
+Every state exposes a TC39 signal, an RxJS Observable, a sync getter,
+and a hydration promise — pick the surface that fits the call site.
+
+This module replaced the v1 `createContext` / `@select` /
+`createCompoundSelector` system. There is no parallel API; use `state()`
+for everything.
+
+## Quick reference
+
+```ts
+import { state, computed, bindState, stateFromObservable } from '@mhmo91/schmancy/state'
+
+// Define
+const cart = state<CartState>('hannah/cart').session({ items: [], total: 0 })
+
+// Read
+cart.value          // CartState — sync getter
+cart.signal.get()   // CartState — raw TC39 signal
+cart.$              // Observable<CartState> — RxJS, microtask-coalesced
+await cart.ready    // resolves when initial load completes
+cart.loaded         // boolean — true after first load
+
+// Write (ObjectAPI dispatch — see "Variant write APIs" below)
+cart.set({ total: 12 })          // partial merge
+cart.replace({ items: [], total: 0 })
+cart.update(d => { d.items.push(item) })   // immer
+cart.delete('total')
+
+// Subscribe in a $LitElement — direct read auto-tracks via SignalWatcher
+class CartView extends $LitElement() {
+  render() { return html`Items: ${cart.value.items.length}` }
+}
+
+// Derived
+const lineCount = computed(() => cart.value.items.length)
+```
+
+## Three call shapes
+
+The factory has three overloads. Pick the shape that fits the file.
+
+### (1) Typed-const — recommended default
+
+```ts
+const initial: CartState = { items: [], total: 0 }
+export const cart = state('hannah/cart').session(initial)
+```
+
+Type comes from the typed const. No type-arg, no registry augmentation.
+Three lines, no casts. Use this for most modules.
+
+**Note:** an inline literal without a typed const narrows T to the literal's
+exact type (`{ items: never[]; total: number }`). For inline literals use
+form (2) or (3).
+
+### (2) Inline — explicit type-arg
+
+```ts
+export const cart = state<CartState>('hannah/cart').session({ items: [], total: 0 })
+```
+
+For inline declarations or one-off namespaces. The literal is contextually
+typed against `CartState`; `[]` widens to `CartItem[]` correctly.
+
+### (3) Registry-augmented — typo-safe, no type-arg
+
+```ts
+declare module '@mhmo91/schmancy/state' {
+  interface SchmancyStateRegistry {
+    'hannah/cart': CartState
+  }
+}
+
+export const cart = state('hannah/cart').session({ items: [], total: 0 })
+```
+
+What the augmentation buys per namespace:
+
+- **Typo prevention** at the type level for that exact namespace string
+- **Autocomplete** — typing `state('` suggests every registered namespace
+- **Catalog** — `SchmancyStateRegistry` is the index of registered states
+- **Duplicate detection** — TS interface-merging fails on conflicting
+  `'hannah/cart': X` / `'hannah/cart': Y` declarations across files
+
+Per-namespace opt-in. Files that augment get the strict path; files that
+don't keep using forms (1) or (2). No global on/off switch.
+
+## Namespace convention
+
+Every namespace MUST contain a `/`. The factory enforces this at compile
+time via the `${string}/${string}` template.
+
+```ts
+state('cart')              // ❌ TypeError at runtime + compile error
+state('hannah/cart')       // ✅
+state('pam/payouts/docs')  // ✅ — multiple slashes are fine
+```
+
+Convention: `<feature>/<name>`. The feature prefix groups related states.
+
+## Storage backends
+
+| Method | Backing | Survives refresh | Survives close | Lifecycle |
+|--------|---------|------------------|----------------|-----------|
+| `.memory(initial)` | JS heap | ❌ | ❌ | `Disposable` |
+| `.session(initial)` | `sessionStorage` | ✅ | ❌ (per-tab) | `Disposable` |
+| `.local(initial)` | `localStorage` | ✅ | ✅ | `Disposable` |
+| `.idb(initial)` | IndexedDB | ✅ | ✅ | `Disposable & AsyncDisposable` |
+
+Web-storage backends round-trip `Map` and `Set` through a JSON tunnel
+(serialized as `{ $kind: 'Map' | 'Set', … }`). IDB stores native objects
+and skips the tunnel.
+
+All persistent backends batch writes through a microtask-coalesced queue
+per state — multiple `set` / `replace` / `update` calls in the same task
+collapse to one `save()` invocation with the latest value.
+
+## Variant write APIs (`Kind<T>` dispatch)
+
+The write surface is determined by `T` automatically — no separate
+`mapState()` / `setState()` factories.
+
+### `ObjectAPI<T>` — plain objects
+
+```ts
+const cart = state<CartState>('hannah/cart').session(initial)
+cart.set({ total: 12 })                    // partial merge (default)
+cart.set({ items: [] }, false)             // replace (no merge)
+cart.replace({ items: [], total: 0 })      // full replace
+cart.update(d => { d.items.push(item) })   // immer recipe
+cart.delete('total')                        // typed: K extends keyof T
+```
+
+### `MapAPI<T>` — `Map<K, V>`
+
+```ts
+const docs = state<Map<string, Doc>>('pam/payouts/docs').idb(new Map())
+docs.set('doc-1', doc)         // (key, value) — not partial
+docs.delete('doc-1')
+docs.replace(new Map(entries))
+docs.clear()
+```
+
+### `SetAPI<T>` — `Set<U>`
+
+```ts
+const sel = state<Set<string>>('pam/payouts/sel').memory(new Set())
+sel.add('id')
+sel.toggle('id')               // add if absent, remove if present
+sel.delete('id')               // returns boolean (was-present)
+sel.replace(new Set(initial))
+sel.clear()
+```
+
+### `ArrayAPI<T>` — arrays
+
+```ts
+const items = state<Item[]>('feature/items').memory([])
+items.push(a, b, c)
+items.update(d => { d.push(x) })   // immer
+items.replace(next)
+items.clear()
+```
+
+### `ScalarAPI<T>` — primitives + nullable references
+
+```ts
+const editing = state<Doc | null>('pam/edit').memory(null)
+editing.set(doc)               // single-arg setter (Partial<T|null> → T|null)
+editing.set(null)
+editing.replace(doc)
+
+const flag = state<boolean>('pam/footer').memory(false)
+flag.set(true)
+```
+
+The `Kind<T>` classifier routes:
+
+- `Map<K, V>` → `MapAPI`
+- `Set<U>` → `SetAPI`
+- `T[]` / `readonly T[]` → `ArrayAPI`
+- `string | number | boolean | bigint | symbol` → `ScalarAPI`
+- Any union containing `null` or `undefined` → `ScalarAPI`
+- All other objects → `ObjectAPI`
+
+## Reading state
+
+```ts
+cart.value           // T — current value, sync getter
+cart.signal.get()    // T — same value via the raw TC39 signal
+cart.signal          // Signal.State<T> — for use inside computed()
+cart.$               // Observable<T> — emits initial + on every change
+cart.ready           // Promise<void> — resolves once load completes
+cart.loaded          // boolean — true after first load attempt
+cart.namespace       // 'hannah/cart' (literal type preserved)
+cart.storage         // 'session' (literal type preserved)
+cart.defaultValue    // the initial passed to the factory
+```
+
+## Subscribing in a component
+
+Three options, in order of preference. The first covers the 80% case
+with zero ceremony.
+
+### (1) Default — direct read inside `render()`
+
+`$LitElement()` composes `SignalWatcher` from `@lit-labs/signals`.
+Every signal read inside `render()` auto-tracks; the host re-renders
+on change. No decorator, no field, no binding code.
+
+```ts
+import { LitElement, html } from 'lit'
+import { customElement } from 'lit/decorators.js'
+import { $LitElement } from '@mixins/index'
+import { cart } from './cart.context'
+
+@customElement('cart-view')
+export class CartView extends $LitElement() {
+  render() {
+    return html`<span>Items: ${cart.value.items.length}</span>`
+  }
+}
+```
+
+The imported `cart` singleton IS the binding. Reading `cart.value`
+(or `cart.signal.get()` directly) inside render registers the
+component as a subscriber for the host's lifetime. On `cart.set(...)`,
+the host re-renders.
+
+Use this for:
+- Any component that just renders state into the template.
+- Computed expressions over multiple states: `${cart.value.total + tip.value.amount}`.
+
+### (2) `@observe(source) field!: T` — field-level binding
+
+When the value needs to be a class field — for event handlers,
+derived methods, DevTools inspection, or readability:
+
+```ts
+import { observe } from '@mhmo91/schmancy/state'
+
+@customElement('cart-view')
+export class CartView extends $LitElement() {
+  @observe(cart) cart!: CartState
+
+  onClick() {
+    console.log('current cart:', this.cart)   // field access in handlers
+  }
+
+  render() {
+    return html`<span>Items: ${this.cart.items.length}</span>`
+  }
+}
+```
+
+Reads return the latest emitted value (falls back to `source.value`
+before the first emission lands). Caller writes are dropped with a
+dev-mode warning — the source is the single source of truth.
+
+Wiring uses Lit's static `addInitializer` to install a
+`ReactiveController` per instance. Multiple `@observe` decorators on
+the same class register independent controllers; they compose without
+ordering concerns. Same decorator shape as `@property`/`@state`/`@query` —
+works under the existing tsconfig with no migration.
+
+### (3) `bindState(host, source)` — imperative form
+
+For hosts that aren't `$LitElement` subclasses (rare):
+
+```ts
+import { bindState } from '@mhmo91/schmancy/state'
+
+class CustomHost extends LitElement {   // not a $LitElement subclass
+  cart = bindState(this, cart)
+  render() {
+    return html`<span>Items: ${this.cart.value.items.length}</span>`
+  }
+}
+```
+
+Same lifecycle guarantees as `@observe`, no decorator. Returned
+`BoundState<T>` exposes `.value` and `.$`.
+
+## Derived state — `computed()`
+
+`computed(fn)` is re-exported directly from `@lit-labs/signals`. Reading
+any `state.value` or `signal.get()` inside the callback auto-tracks it
+as a dependency.
+
+```ts
+import { computed } from '@mhmo91/schmancy/state'
+
+const cartItemCount = computed(() => cart.value.items.length)
+const orderTotal = computed(() => cart.value.total + tip.value.amount)
+
+// Read with .get() — auto-tracks if called from within another computed
+cartItemCount.get()
+```
+
+`computed()` defaults to reference-equality dedup. Pass a custom `equals`
+through `Signal.Options<T>` if you need value-equality.
+
+## Observable → state — `stateFromObservable`
+
+Lift an RxJS source into a state.
+
+```ts
+import { stateFromObservable } from '@mhmo91/schmancy/state'
+
+const userPresence = stateFromObservable(
+  presence$,                    // Observable<PresenceState>
+  'app/presence',                // namespace
+  { online: false, since: 0 },   // initial
+)
+```
+
+The returned state is `'memory'`-backed by default (override via
+`{ storage: 'session' | 'local' | 'indexeddb' }`). Subscription is
+created once; cleanup on dispose unsubscribes the source.
+
+## Lifecycle
+
+### Module-scope singleton (most common)
+
+```ts
+// frontend/src/cart/cart.context.ts
+export const cart = state<CartState>('hannah/cart').session(initial)
+```
+
+Plain `const`. Lives for app lifetime.
+
+**Footgun:** do **not** use `using` at module scope — it disposes when
+the module record is GC'd, which is roughly never until the tab closes.
+Reserve `using` / `await using` for test or function scope.
+
+### Test-scoped — `using` / `await using`
+
+```ts
+import { it, expect } from 'vitest'
+
+it('cart updates total on add', () => {
+  using cart = state<CartState>('test/cart').memory(initial)
+  cart.update(d => { d.items.push(item) })
+  expect(cart.value.total).toBe(item.price)
+}) // [Symbol.dispose] runs here automatically — even on assertion failure.
+
+it('persists across reloads', async () => {
+  await using cart = state<CartState>('test/cart').idb(initial)
+  // ... awaits IDB flush + close before the next test.
+})
+```
+
+### `destroy()` — imperative alias
+
+`state.destroy()` is the imperative form (alias for `[Symbol.dispose]()`).
+Use when working in a context where `using` isn't available. For IDB
+states, `destroy()` fires `[Symbol.asyncDispose]` without awaiting —
+fire-and-forget cleanup.
+
+### What disposal does
+
+- Drains pending writes (microtask-coalesced queue)
+- Unsubscribes any `stateFromObservable` source
+- Closes the IDB connection (for IDB-backed states)
+- Releases the namespace claim — the same `'feature/name'` can be
+  re-registered after disposal
+
+## Scoping — `<schmancy-context provides>`
+
+The default state is a module-scoped singleton: `cart` is the same
+instance everywhere. To **isolate** the same `cart` for a subtree —
+two side-by-side checkout flows, an `<iframe>`-like wizard, an
+embedded preview — wrap the subtree in `<schmancy-context>`.
+
+```ts
+class App extends $LitElement() {
+  render() {
+    return html`
+      <schmancy-context .provides=${[cart]}>
+        <cart-view></cart-view>      <!-- isolated copy -->
+      </schmancy-context>
+      <cart-summary></cart-summary>  <!-- module-scoped global -->
+    `
+  }
+}
+```
+
+Inside the element, `cart.value`, `cart.set(...)`, `cart.update(...)`,
+and every other read/write resolve to a per-element isolated copy.
+Outside, they continue to read the global. Nested
+`<schmancy-context>` resolves to the **closest** provider per
+namespace.
+
+### What you write is unchanged
+
+Consumers don't change. The same `cart.value` inside `render()`, the
+same `cart.set(...)` in a click handler, the same `cart.update(...)`
+after an `await fetch(...)` — all of it auto-resolves to the right
+instance based on tree position.
+
+```ts
+class CartView extends $LitElement() {
+  render() {
+    return html`
+      <button @click=${() => cart.set({ total: 0 })}>Clear</button>
+      <button @click=${this.handleAdd}>Add</button>
+      Items: ${cart.value.items.length}
+    `
+  }
+  handleAdd() { cart.update(d => { d.items.push({}) }) }
+  async handleSubmit() {
+    const data = await fetch('/items').then(r => r.json())
+    cart.update(d => { d.items = data })   // resolves correctly after await
+  }
+}
+```
+
+Coverage of the call paths is provided by `SchmancyElement`:
+
+- `render()` and every Lit lifecycle hook — wrapped at construction.
+- Class methods (`handleAdd`, `handleSubmit`) — wrapped at construction.
+- `await` continuations inside class methods — propagated via the
+  `Promise.then` patch in `state/active-host.ts`.
+- `addEventListener(type, fn)` on the host — wrapped (and unwrapped on
+  `removeEventListener`).
+- Inline arrow handlers in templates (`@click=${() => …}`) — resolve
+  via the `window.event.composedPath()` fallback in
+  `resolveActiveHost()`.
+
+Pure async callbacks with no DOM origin — a websocket `onmessage`,
+`setInterval` with no triggering user event — fall through to the
+module-scoped global. That is the correct semantic: those callbacks
+have no tree position to resolve to.
+
+### Lifecycle
+
+- The isolated copy is created at `<schmancy-context>` connect and
+  seeded with the **current global value** at that moment.
+- It is destroyed on `<schmancy-context>` disconnect (pending writes
+  flush, adapters close).
+- Storage backend is always **memory** for isolated copies — they
+  share lifetime with the element, not with `localStorage` /
+  `sessionStorage` / IndexedDB. The global continues to persist on
+  whichever backend it was created with.
+
+### `provides` shape
+
+`provides` accepts the same state instances you import. Pass several:
+
+```ts
+<schmancy-context .provides=${[cart, menu, draft]}>...</schmancy-context>
+```
+
+States not listed in `provides` fall through to the global from inside
+the element — useful when only one or two namespaces need scoping.
+
+## Migration from v1 `createContext`
+
+```ts
+// v1
+const cart = createContext<CartState>(initial, 'session', 'hannah_cart')
+class CartView extends LitElement {
+  @select(cart) accessor cart!: CartState
+}
+const total = createCompoundSelector([cart], [c => c.total], t => t)
+
+// v2
+const cart = state<CartState>('hannah/cart').session(initial)
+class CartView extends LitElement {
+  @observe(cart) cart!: CartState   // or: cart = bindState(this, cart)
+}
+const total = computed(() => cart.value.total)
+```
+
+Surface-equivalent: `.value`, `.set(partial)`, `.replace(next)`, `.$`,
+`.delete(key)` all map directly. Storage keys move from arbitrary
+strings (`'hannah_cart'`) to namespace strings (`'hannah/cart'`).
+
+## Rules
+
+- **One state per namespace.** The factory throws on a duplicate
+  `state('hannah/cart')` until the first instance is disposed. Module-
+  scoped singletons are the assumption.
+- **Namespaces always contain `/`.** Compile-time enforced.
+- **No `using` at module scope.** Disposes never; use plain `const`.
+- **No regex-parsing of LLM output**, no hand-written "please return
+  JSON" — same project rules as elsewhere. State surface only validates
+  types it constructed itself.
+- **Treat `state.signal` as read access.** Don't `state.signal.set(…)`
+  directly — go through the variant API so write-through-persist and
+  observable emission stay coherent.
+- **Don't cache `state.signal` / `state.$` across tree boundaries.**
+  Every read goes through context resolution; the underlying signal
+  (and Observable) returned by the getter is the *currently resolved*
+  instance. If you store `cart.signal` in a variable and the host
+  later moves into a different `<schmancy-context>` subtree, the
+  cached reference lags. Read inline (`cart.value`, `cart.$`) instead
+  of caching.

package/dist/skills/schmancy/theme.md

@@ -131,6 +131,21 @@ surface-inverse (inverse-surface) · surface-inverseOn (inverse-on-surface)
 
 Only reach for `bg-[var(--schmancy-sys-color-X)]` when the token isn't aliased — e.g. a custom `--schmancy-*` property you've registered yourself.
 
+## Typography override
+
+`<schmancy-theme>` ships no font attribute. To swap the app's typeface, override `--schmancy-font-family` on `:root` in a consumer stylesheet. Schmancy's theme stylesheet reads it with a `sans-serif` fallback and fans it out to `--md-ref-typeface-brand`, `--md-ref-typeface-plain`, and `--default-font-family`, so every `<schmancy-*>` component picks it up via the cascade:
+
+```css
+:root {
+  --schmancy-font-family: 'Space Grotesk', sans-serif;
+  font-family: var(--schmancy-font-family);
+}
+```
+
+The second line (`font-family: var(...)`) makes the typeface inherit by non-schmancy elements inside your app too — without it, plain `<div>`s use the browser default.
+
+There is currently **no `--schmancy-font-mono` equivalent**. `--font-mono` in [theme.style.css](../../src/theme/theme.style.css) hardcodes Tailwind's default `ui-monospace, SFMono-Regular, …` stack. Consumers that want a custom monospace typeface either (a) use Tailwind's `font-mono` utility with the default stack and accept it, or (b) override `--font-mono` directly on `:root` with the same cascade pattern as the sans hook. Option (b) is a local escape hatch, not a schmancy-blessed API — expect future schmancy versions to add a proper `--schmancy-font-mono` hook instead.
+
 ## Notes
 - Color and scheme persist to `sessionStorage` per instance
 - Generates success/warning/info/error semantic color tokens automatically

package/dist/skills/schmancy/timeline-tile.md

@@ -0,0 +1,95 @@
+# schmancy-timeline-tile
+
+> One cell in a procurement-stage timeline rail. Renders an empty / filled / stacked paper-card tile with a 2-letter glyph label, optional tooltip + caption, and a built-in fan-on-hover orchestration for stacked variants.
+
+## Usage
+
+```html
+<!-- Empty cell (placeholder for a missing stage doc) -->
+<schmancy-timeline-tile state="empty" glyph="PO"></schmancy-timeline-tile>
+
+<!-- Single filled cell with tooltip + caption -->
+<schmancy-timeline-tile
+  state="filled"
+  glyph="IN"
+  tooltip="INV-2025-0001"
+  caption="EUR 12,400"
+  @tile-click=${(e) => openInspect(e.detail)}
+></schmancy-timeline-tile>
+
+<!-- Stack of N revisions: wrapper carries `data-stack-id` + `--fan-count`,
+     stack-top sits on top with the ×N badge, siblings reveal on hover.
+     The wrapper toggles `data-fanned` automatically — no consumer
+     pointer wiring required. -->
+<div
+  data-stack-id="po-123"
+  style="position: relative; width: 32px; height: 40px; --fan-count: 3;"
+>
+  <schmancy-timeline-tile state="stack-sibling" glyph="PO" .index=${0}></schmancy-timeline-tile>
+  <schmancy-timeline-tile state="stack-sibling" glyph="PO" .index=${1}></schmancy-timeline-tile>
+  <schmancy-timeline-tile
+    state="stack-top"
+    glyph="PO"
+    .index=${2}
+    .stackCount=${3}
+    tooltip="PO-2025-0007 · rev 3"
+    caption="EUR 12,400"
+  ></schmancy-timeline-tile>
+</div>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `state` | `'empty' \| 'filled' \| 'stack-top' \| 'stack-sibling'` | `'empty'` | Render mode (reflected) |
+| `glyph` | `string` | `''` | 2-letter stage label (e.g. `RQ`, `PO`, `OC`, `DN`, `IN`) |
+| `stackCount` | `number?` | `undefined` | When `state="stack-top"` and > 1, renders the ×N badge |
+| `index` | `number?` | `undefined` | Sibling position in the stack (drives `--i` for fan offset; reflected) |
+| `tooltip` | `string?` | `undefined` | Tooltip text shown on hover / focus |
+| `caption` | `string?` | `undefined` | Caption rendered below the tile (hidden on `stack-sibling`) |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `tile-click` | `{ glyph, state }` | Fires on click for any non-`empty` state. Bubbles + composed. |
+
+## Stack fan orchestration
+
+When `state="stack-top"`, the component subscribes a `pointerover` pipe to its parent element (the stack wrapper). The pipe is hover-intent: `pointerover` events with a target that closest-matches `[data-stack-id]` immediately set `data-fanned` on the wrapper; leaving the wrapper waits 800 ms before clearing the attribute, so the cursor can cross the gap between fanned siblings without collapsing the stack. The attribute lifetime IS the fanned state — sibling tiles read it via the `:host-context([data-fanned])` selector and translate edge-to-edge.
+
+The consumer's wrapper element MUST carry:
+- `data-stack-id="<unique>"` so the pointerover pipe can match the target
+- `position: relative` so the absolutely-positioned tiles align to it
+- `width` + `height` matching `--schmancy-tile-w` / `--schmancy-tile-h` (default `32px` / `40px`)
+- `--fan-count: <N>` so each tile knows the total stack size
+
+`stack-sibling` tiles set `pointer-events: none` until the wrapper is fanned, then re-enable so the user can click any revision.
+
+## Slots
+
+None. Glyph and caption are props, not slot content — keeps the tile self-contained and addressable from a `repeat()` template.
+
+## Accessibility
+
+- Filled / stack tiles render a native `<button type="button">` with `tabindex="0"` and `role="button"`.
+- `aria-label` is composed from `glyph`, `caption`, and `tooltip`.
+- Empty tiles set `tabindex="-1"` and `aria-label="<glyph> · empty"`.
+- Focus shows a 2px ring in `--schmancy-sys-color-primary-default` with a 3px offset.
+
+## Tokens consumed
+
+| Custom property | Source |
+|-----------------|--------|
+| `--schmancy-sys-color-outline` | dashed border, paper-card lines, sibling outline |
+| `--schmancy-sys-color-surface-containerLowest` | filled-card background, tooltip background |
+| `--schmancy-sys-color-surface-on` | tooltip + caption text |
+| `--schmancy-sys-color-surface-onVariant` | empty-state glyph |
+| `--schmancy-sys-color-primary-default` | hover border, focus ring, top-edge tint, ×N badge background |
+| `--schmancy-sys-color-primary-on` | ×N badge text |
+| `--schmancy-sys-color-primary-onContainer` | filled-state glyph color |
+| `--schmancy-tile-w`, `--schmancy-tile-h` | host width / height (defaults `32px` / `40px`) |
+| `--fan-count`, `--i` | wrapper-driven fan layout (consumer or component-set) |
+
+Theme overrides cascade from any ancestor `<schmancy-theme>` — wrap the timeline in a tinted theme block to recolor the rail without touching the component.