@mhmo91/schmancy 0.9.28 → 0.10.2

package/src/state/MIGRATION.md

@@ -0,0 +1,258 @@
+# Migrating from `createContext` to `state()`
+
+Cheatsheet for moving call sites off the v1 `createContext` /
+`@select` / `createCompoundSelector` / `selectItem` family to
+`@mhmo91/schmancy/state`.
+
+The v1 surface has been deleted from `@mhmo91/schmancy`. There is no
+parallel API; every consumer needs to switch.
+
+## Imports
+
+```ts
+// Before
+import { createContext, select, selectItem, createCompoundSelector } from '@mhmo91/schmancy'
+
+// After
+import { state, computed, observe, bindState, stateFromObservable } from '@mhmo91/schmancy/state'
+```
+
+## Defining a state
+
+| v1 | v2 |
+|---|---|
+| `createContext<T>(initial, 'memory', 'foo')` | `state<T>('feature/foo').memory(initial)` |
+| `createContext<T>(initial, 'session', 'foo')` | `state<T>('feature/foo').session(initial)` |
+| `createContext<T>(initial, 'local', 'foo')` | `state<T>('feature/foo').local(initial)` |
+| `createContext<T>(initial, 'indexeddb', 'foo')` | `state<T>('feature/foo').idb(initial)` |
+
+The string namespace replaces the v1 third-argument storage key. It
+must contain a `/` (compile-time enforced via the
+`${string}/${string}` template literal). Storage is keyed off the
+namespace string.
+
+If your file already declares the initial value in a typed const, drop
+the type arg:
+
+```ts
+const initial: CartState = { items: [], total: 0 }
+const cart = state('hannah/cart').session(initial)   // T inferred from `initial`
+```
+
+## Reading
+
+| v1 | v2 |
+|---|---|
+| `cart.value` | `cart.value` (unchanged) |
+| `cart.$.subscribe(...)` | `cart.$.subscribe(...)` (unchanged) |
+| `cart.ready` (boolean) | `cart.loaded` (boolean) + `await cart.ready` (Promise<void>) |
+
+`cart.ready` is now a Promise that resolves when initial load completes
+(success or fallback). `cart.loaded` is the boolean runtime flag. Use
+whichever fits the call site.
+
+## Writing
+
+| v1 | v2 |
+|---|---|
+| `cart.set({ total: 12 })` | `cart.set({ total: 12 })` (unchanged) |
+| `cart.set({ items: [] }, false)` | `cart.set({ items: [] }, false)` (unchanged) |
+| `cart.replace(next)` | `cart.replace(next)` (unchanged) |
+| `cart.delete('total')` | `cart.delete('total')` (unchanged) |
+| Manual `replace({ ...current, ...patch })` cascade | `cart.update(d => { … })` — immer recipe, single notification |
+
+For `Map<K, V>` shapes:
+
+| v1 | v2 |
+|---|---|
+| `docs.set('id', doc)` | `docs.set('id', doc)` (unchanged — MapAPI dispatch) |
+
+For `Set<U>`:
+
+| v1 | v2 |
+|---|---|
+| Manual `replace(new Set([...current, item]))` | `sel.add('item')` |
+| Manual replace-without-item | `sel.delete('item')` (returns boolean) |
+|  | `sel.toggle('item')` (new) |
+
+For arrays:
+
+| v1 | v2 |
+|---|---|
+| `array.push(...items)` | `array.push(...items)` (unchanged) |
+| Manual `replace(current.filter(...))` | `array.update(d => d.splice(...))` (immer) |
+
+For nullable references and primitives:
+
+| v1 | v2 |
+|---|---|
+| `editing.set({ id: 'x' })` then `editing.set(null)` | Same (ScalarAPI accepts the union directly) |
+
+## Subscribing in a component
+
+The v1 `@select` decorator is gone. Three options in v2, in order of
+preference:
+
+### (1) Default — direct read in render (zero ceremony)
+
+`$LitElement()` composes `SignalWatcher`, so signal reads in `render()`
+auto-track. Just import the state and use it inline:
+
+```ts
+@customElement('cart-view')
+class CartView extends $LitElement() {
+  render() { return html`Items: ${cart.value.items.length}` }
+}
+```
+
+No decorator, no field, no binding code. The imported `cart` singleton
+IS the binding.
+
+### (2) `@observe(source)` — when you need a class field
+
+```ts
+class CartView extends $LitElement() {
+  @observe(cart) cart!: CartState
+
+  onClick() {
+    console.log(this.cart)   // event handler needs `this.cart`
+  }
+
+  render() {
+    return html`Items: ${this.cart.items.length}`
+  }
+}
+```
+
+Reads return the latest value. Caller writes are dropped with a dev
+warning. Same decorator shape as `@property` — works under the existing
+tsconfig.
+
+### (3) `bindState(host, source)` — for hosts that aren't `$LitElement`
+
+```ts
+class CustomHost extends LitElement {
+  cart = bindState(this, cart)
+  render() { return html`Items: ${this.cart.value.items.length}` }
+}
+```
+
+## Compound selectors → `computed`
+
+```ts
+// Before
+const cartItemCount = createCompoundSelector(
+  [cartContext],
+  [cart => cart.items.length],
+  count => count,
+)
+
+// After
+import { computed } from '@mhmo91/schmancy/state'
+const cartItemCount = computed(() => cart.value.items.length)
+```
+
+Cross-state composition just works:
+
+```ts
+const orderTotal = computed(() => cart.value.subtotal + tip.value.amount)
+```
+
+Reading any `state.value` inside `computed(fn)` auto-tracks. No
+explicit dependency array.
+
+## Side effects → `effect`
+
+```ts
+import { effect } from '@mhmo91/schmancy/state'
+
+const stop = effect(() => {
+  document.title = `${cart.value.items.length} items`
+})
+
+// later, when no longer needed:
+stop[Symbol.dispose]()
+```
+
+Eager run + microtask-coalesced re-runs. Returns a `Disposable`.
+
+## Observable bridges
+
+```ts
+// Before
+const userPresence$ = new BehaviorSubject({ online: false, since: 0 })
+// (read with .value, subscribe with .$, no persistence story)
+
+// After
+import { stateFromObservable } from '@mhmo91/schmancy/state'
+
+const userPresence = stateFromObservable(
+  presence$,                    // Observable<PresenceState>
+  'app/presence',
+  { online: false, since: 0 },
+)
+// userPresence has .value, .$, all variant API methods, lifecycle.
+```
+
+## Lifecycle / disposal
+
+```ts
+// Module scope — same as v1
+export const cart = state('hannah/cart').session(initial)
+
+// Test scope — using
+it('cart updates total on add', () => {
+  using cart = state('test/cart').memory(initial)
+  cart.update(d => { d.items.push(item) })
+  expect(cart.value.total).toBe(item.price)
+})  // [Symbol.dispose] runs here, even on assertion failure
+
+// IDB-backed in tests — await using flushes pending writes
+it('persists across reloads', async () => {
+  await using cart = state('test/cart').idb(initial)
+  // ...
+})
+
+// Imperative cleanup (samwa back-compat alias)
+cart.destroy()
+```
+
+## Things that went away
+
+- **`createCompoundSelector`** — use `computed()`.
+- **`@select` and `@selectItem` decorators** — use direct render reads
+  via `$LitElement` (default), `@observe` (field-level), or `bindState`
+  (non-Lit hosts).
+- **`IStore` / `ICollectionStore` / `IArrayStore` interfaces** — no
+  longer needed. The variant write API dispatch is type-level.
+- **`error$` per-store Subject** — errors flow through console + the
+  `StateStorageError` thrown from `save()` for IDB write failures.
+- **Tree-scoped `<state-provider>`** — replaced by
+  `<schmancy-context provides={[…]}>`. Same intent (per-subtree
+  isolation of a state), different API: in v1 the provider was a
+  primitive; in v2 the state surface stays unchanged and the
+  `<schmancy-context>` element is what scopes a subtree. Consumer
+  code (`cart.value`, `cart.set(...)`) is identical inside and
+  outside the element. See `SCOPING.md` for the details.
+
+## Footguns
+
+- **Don't use `using` at module scope.** It disposes on module GC,
+  which is roughly never until the tab closes. Plain `const` for
+  module singletons, `using` for test/function scope only.
+- **Namespaces always contain `/`.** `state('cart')` is a TypeError;
+  use `state('feature/cart')`.
+- **Don't `state.signal.set(...)` directly.** Go through the variant
+  API so write-coalescing and persistence stay coherent.
+- **Inline literals without a typed const narrow T.**
+  `state('app/x').memory({ items: [], total: 0 })` infers
+  `{ items: never[]; total: number }`. Either use a typed const first
+  or pass the type arg: `state<CartState>('app/x').memory({...})`.
+
+## Pointers
+
+- Skill / API reference: `packages/schmancy/skills/schmancy/state.md`
+- Agent brief: `packages/schmancy/src/state/CLAUDE.md`
+- Tree-scoping reference: `packages/schmancy/src/state/SCOPING.md`
+- Original plan: `~/.claude/plans/indexed-twirling-stroustrup.md`
+- Scoping plan: `~/.claude/plans/federated-petting-penguin.md`

package/src/state/SCOPING.md

@@ -0,0 +1,134 @@
+# Scoping a state per subtree — `<schmancy-context provides>`
+
+The `state()` factory returns a module-scoped singleton. `cart` is the
+same instance everywhere it is imported. That is the right default —
+"the cart" is a single thing.
+
+When you need *more than one* of something at the same time — two
+side-by-side checkout flows, a comparison view of two records, an
+embedded preview that shouldn't trample the parent's draft —
+`<schmancy-context>` scopes a state to a subtree.
+
+```ts
+import { state } from '@mhmo91/schmancy/state'
+
+const cart = state<CartState>('hannah/cart').session({ items: [], total: 0 })
+
+class App extends $LitElement() {
+  render() {
+    return html`
+      <schmancy-context .provides=${[cart]}>
+        <cart-view></cart-view>      <!-- isolated copy of cart -->
+      </schmancy-context>
+      <cart-summary></cart-summary>  <!-- module-scoped global cart -->
+    `
+  }
+}
+```
+
+Inside `<schmancy-context>`, every read and write of `cart` resolves to
+a per-element isolated copy. Outside, it stays the global. **Consumer
+code does not change.** `cart.value`, `cart.set(...)`,
+`cart.update(d => …)` — same calls, tree-aware result.
+
+## Resolution rules
+
+- Inside `<schmancy-context provides={[cart]}>` → reads/writes go to
+  that element's isolated copy.
+- Inside two nested `<schmancy-context provides={[cart]}>` → the
+  **closest** provider wins.
+- Inside a `<schmancy-context>` whose `provides` does **not** include
+  `cart` → falls through to the module-scoped global.
+- Outside any `<schmancy-context>` → module-scoped global.
+
+## What's covered
+
+The scoping primitive is supposed to "just work" for the call paths a
+component naturally writes. It handles:
+
+| Code path | Mechanism |
+|---|---|
+| `render()` | `SchmancyElement` prototype-wrap pushes the host onto the active-host stack for the duration of `render()`. |
+| Lit lifecycle (`connectedCallback`, `update`, `updated`, `firstUpdated`, `willUpdate`) | Same prototype-wrap. |
+| Class methods called from event handlers (sync) | Same prototype-wrap. |
+| `await` continuations inside class methods | A `Promise.prototype.then` patch in `state/active-host.ts` propagates the host across each `.then` boundary. |
+| `addEventListener(type, fn)` on the host | Wrapped at the `SchmancyElement` layer; `removeEventListener` re-finds the wrapped listener via a `WeakMap`. |
+| Inline arrow handlers attached via Lit templates (`@click=${() => …}`) | Resolved through the `window.event.composedPath()` fallback in `resolveActiveHost()`. |
+
+Pure async callbacks with no DOM origin — a websocket `onmessage`
+unrelated to any user gesture, a `setInterval` body running on its own
+schedule — 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 when `<schmancy-context>` connects, and
+  is **seeded with the current global value** at that moment. The
+  subtree starts from "what the rest of the app sees right now," then
+  diverges.
+- It is destroyed when `<schmancy-context>` disconnects. Pending
+  microtask-coalesced writes flush; the storage adapter's `close()`
+  runs.
+- The isolated copy uses **memory** storage regardless of the global's
+  backend. It shares lifetime with the element, not with
+  `localStorage` / `sessionStorage` / IndexedDB. The global continues
+  to persist on whichever backend it was created with.
+
+## Multiple states per element
+
+```ts
+<schmancy-context .provides=${[cart, menu, draft]}>
+  <wizard></wizard>
+</schmancy-context>
+```
+
+Each is isolated independently. States not listed in `provides`
+fall through to the global from inside the element — useful when only
+some namespaces need scoping in a particular subtree.
+
+## Two pitfalls
+
+### Don't cache `state.signal` or `state.$` across tree boundaries
+
+Every read goes through context resolution. The signal (and Observable)
+returned by the getter is the *currently resolved* instance. Stash a
+reference to `cart.signal` and the host later moves into a different
+`<schmancy-context>` subtree, and your reference lags.
+
+```ts
+// ✗ Don't
+const sig = cart.signal
+class Foo extends $LitElement() {
+  render() { return html`${sig.get().n}` }   // never re-resolves
+}
+
+// ✓ Do
+class Foo extends $LitElement() {
+  render() { return html`${cart.value.n}` }   // resolves fresh each render
+}
+```
+
+### Don't expect persistence per subtree
+
+Isolated copies are memory-backed. If your scoping use case requires
+persisting per-subtree state across reloads, that is a different design
+— derive a fresh `state()` per logical scope (with a unique namespace)
+and use the persistent backend on that.
+
+## Implementation primer (for contributors)
+
+- `state/active-host.ts` — `_activeHost` Variable (stack) +
+  one-time `Promise.prototype.then` patch + 4-tier `resolveActiveHost`
+  fallback. ~120 lines. Hand-rolled because no official, supported
+  TC39 AsyncContext.Variable polyfill exists today; the patch
+  decommissions cleanly when one ships.
+- `state/schmancy-context.ts` — the element. One `ContextProvider`
+  (`@lit/context`) per state in `provides`. Destroys on disconnect.
+- `state/index.ts` — every read (`value` / `signal` / `$`) and every
+  write on a global instance routes through `resolveContextual`,
+  which dispatches a `context-request` event from the active host and
+  caches the result per-host-per-namespace in a `WeakMap`. Isolated
+  copies are direct-access (skip resolveContextual, no recursion).
+- `mixins/SchmancyElement.ts` — prototype-chain wrap at first
+  construction (cached in a `WeakSet` of prototypes); `addEventListener`
+  / `removeEventListener` overrides; wrapped listener cache.

package/src/state/active-host.ts

@@ -0,0 +1,190 @@
+// `_`-prefixed identifiers below are an intentional naming convention for
+// module-private infrastructure. `_activeHost` is exported only so the
+// $LitElement mixin can wrap render/lifecycle in `_activeHost.run`; the
+// underscore signals "not part of the public state API."
+/* oxlint-disable no-underscore-dangle */
+
+// Active-host tracker for context-aware state resolution.
+//
+// Polyfills the TC39 `AsyncContext.Variable` propagation primitive using a
+// stack + a one-time `Promise.prototype.then` patch. The stack value carries
+// across `await`, `queueMicrotask`, RxJS subscription callbacks, and any
+// other code path that ultimately routes through `Promise.then`. This is the
+// same capture-and-restore technique zone.js, async-hooks, and the various
+// AsyncContext userland polyfills use.
+//
+// Why we own this:
+//   - The TC39 proposal is at stage 2; no official polyfill ships from TC39.
+//   - The `async-context@1.0.0` package on npm is unrelated (a 2014 Node
+//     callback helper), and the available userland polyfills either depend
+//     on zone.js (~50 KB) or are Node-only / hobby quality.
+//   - The patch surface is ~30 lines, idempotent, preserves Promise
+//     semantics (delegates to the original `then`, so `Symbol.species` and
+//     subclassing work unchanged), and decommissions cleanly the day a real
+//     polyfill or native AsyncContext lands (drop the file, swap the
+//     `_activeHost` export for the standard primitive).
+//
+// Known limitation — native await on a native Promise: V8's await
+// optimization (since 7.x) skips the spec-prescribed
+// `Promise.resolve(x).then(continuation)` step, so userland `then`
+// patches don't intercept the resumption. Class methods that mutate
+// state across an `await` boundary will fall back to the
+// module-scoped global, not the active-host's isolated copy. To
+// preserve the host across awaits, either keep the mutation in the
+// synchronous prelude before the first `await`, or explicitly chain
+// with `.then()` (which still routes through the patched method).
+// A real fix requires either a build-time async-function transform
+// or native AsyncContext.Variable in the runtime.
+//
+// resolveActiveHost() fallback chain:
+//   1. Stack value set by `_activeHost.run(host, fn)` — covers render(),
+//      Lit lifecycle methods, and class-method handlers (all wrapped by
+//      SchmancyElement's prototype-chain wrap).
+//   2. The closest `<schmancy-context>` whose subtree currently has an
+//      in-flight DOM event. The element installs capture-phase listeners
+//      that publish itself as the event-host while the synchronous
+//      handler chain runs; the slot clears via microtask. Covers
+//      template-bound inline arrow handlers attached to descendants.
+//   3. document.activeElement — keyboard handlers in focus.
+//   4. undefined → caller falls back to the module-scoped global instance.
+
+// Singleton across any number of schmancy module copies (source + dist, ESM
+// + CJS, hoisted vs. nested node_modules) via the runtime-global symbol
+// registry. The first copy to load creates the slot; later copies reuse it.
+// Without this, two stacks → mixins push to one, state reads from the other,
+// and active-host context is lost across the boundary.
+const STACK_KEY = Symbol.for('schmancy.state.activeHost.stack')
+type StackSlot = { stack: Array<HTMLElement | undefined> }
+const _g = globalThis as { [STACK_KEY]?: StackSlot }
+_g[STACK_KEY] ??= { stack: [undefined] }
+const _stack = _g[STACK_KEY].stack
+
+// One-time Promise.prototype.then patch at module init. Each .then() call
+// captures the stack head at chain time; firing the callback restores that
+// captured value for the duration of the callback. The guard property
+// prevents double-patching across HMR / duplicate module loads.
+declare global {
+	interface Promise<T> {
+		// Marker symbol so we can detect (and skip) re-patching.
+		readonly __schmancyActiveHostPatched?: true
+	}
+}
+
+// Patching Promise.prototype is the entire mechanism this module exists to
+// provide — the lint rules below intentionally do not apply.
+/* oxlint-disable no-extend-native, unicorn/no-thenable */
+if (typeof Promise !== 'undefined' && !('__schmancyActiveHostPatched' in Promise.prototype)) {
+	Object.defineProperty(Promise.prototype, '__schmancyActiveHostPatched', {
+		value: true,
+		configurable: false,
+		enumerable: false,
+		writable: false,
+	})
+	const _origThen = Promise.prototype.then
+	// Replace with our wrapper. We delegate to the original `then` via
+	// `_origThen.call(this, …)` so Promise subclassing / Symbol.species behave
+	// exactly as before — the only added work is the stack push/pop around
+	// each user callback.
+	Promise.prototype.then = function schmancyThen<T, R1, R2>(
+		this: Promise<T>,
+		onfulfilled?: ((value: T) => R1 | PromiseLike<R1>) | null,
+		onrejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null,
+	): Promise<R1 | R2> {
+		const captured = _stack[_stack.length - 1]
+		const wrapFulfilled = onfulfilled
+			? (v: T): R1 | PromiseLike<R1> => {
+					_stack.push(captured)
+					try {
+						return onfulfilled(v)
+					} finally {
+						_stack.pop()
+					}
+				}
+			: onfulfilled
+		const wrapRejected = onrejected
+			? (r: unknown): R2 | PromiseLike<R2> => {
+					_stack.push(captured)
+					try {
+						return onrejected(r)
+					} finally {
+						_stack.pop()
+					}
+				}
+			: onrejected
+		return _origThen.call(this, wrapFulfilled, wrapRejected) as Promise<R1 | R2>
+	}
+}
+/* oxlint-enable no-extend-native, unicorn/no-thenable */
+
+export const _activeHost = {
+	/** Run `fn` with `host` as the active host for the duration of `fn` and
+	 *  any awaits / microtasks / Promise chains that descend from it. */
+	run<R>(host: HTMLElement | undefined, fn: () => R): R {
+		_stack.push(host)
+		try {
+			return fn()
+		} finally {
+			_stack.pop()
+		}
+	},
+	/** The current active host, or undefined if no `run()` is on the stack. */
+	get(): HTMLElement | undefined {
+		return _stack[_stack.length - 1]
+	},
+}
+
+// Tier 2 of the resolveActiveHost() fallback chain. A `<schmancy-context>`
+// publishes itself here from a capture-phase event listener attached to
+// itself; the slot clears in the next microtask, after the synchronous
+// event-handler chain has run. `window.event` is unreliable across both
+// engines and time (it can outlive its event — a stale `message` event
+// from postMessage can leak BODY for arbitrary later resolution calls), so
+// we own this slot rather than read the legacy global.
+//
+// Singleton across module copies for the same reason as `_stack` above.
+const EVENT_HOST_KEY = Symbol.for('schmancy.state.activeHost.eventHost')
+type EventHostSlot = { host: HTMLElement | undefined; scheduled: boolean }
+const _eventHostSlot: EventHostSlot =
+	((globalThis as { [EVENT_HOST_KEY]?: EventHostSlot })[EVENT_HOST_KEY] ??= {
+		host: undefined,
+		scheduled: false,
+	})
+
+/** Publish `host` as the active event-host. The slot self-clears at the
+ *  end of the current microtask checkpoint — long enough for the entire
+ *  synchronous event-handler chain to read it, short enough that no
+ *  later, unrelated microtask sees a stale value. */
+export function _publishEventHost(host: HTMLElement): void {
+	_eventHostSlot.host = host
+	if (_eventHostSlot.scheduled) return
+	_eventHostSlot.scheduled = true
+	queueMicrotask(() => {
+		_eventHostSlot.scheduled = false
+		_eventHostSlot.host = undefined
+	})
+}
+
+export function resolveActiveHost(): HTMLElement | undefined {
+	// 1. Stack (set by _activeHost.run).
+	const fromStack = _activeHost.get()
+	if (fromStack !== undefined) return fromStack
+
+	// 2. Closest <schmancy-context> with an in-flight event in its subtree.
+	if (_eventHostSlot.host !== undefined) return _eventHostSlot.host
+
+	// 3. document.activeElement — keyboard / focus handlers.
+	if (typeof document !== 'undefined' && document.activeElement instanceof HTMLElement) {
+		return document.activeElement
+	}
+
+	// 4. undefined — caller falls back to module-scoped.
+	return undefined
+}
+
+/** Stable context key for a state namespace. `Symbol.for(...)` so the same
+ *  namespace string yields the same symbol across module boundaries — the
+ *  ContextProvider on `<schmancy-context>` and the ContextRequestEvent
+ *  dispatched by a state read must agree on identity. */
+export function stateContextKey(namespace: string): symbol {
+	return Symbol.for(`schmancy.state:${namespace}`)
+}