@mhmo91/schmancy 0.9.27 → 0.10.1

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,156 @@
+// `_`-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).
+//
+// resolveActiveHost() fallback chain:
+//   1. Stack value set by `_activeHost.run(host, fn)` — covers render(),
+//      Lit lifecycle methods, class-method handlers (all wrapped by
+//      $LitElement), and async-after-await via the Promise patch.
+//   2. window.event.composedPath() — sync event-handler fallback for
+//      template-bound inline arrow handlers when the EventPart patch is
+//      unavailable (feature-gated upgrade).
+//   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]
+	},
+}
+
+export function resolveActiveHost(): HTMLElement | undefined {
+	// 1. Stack (set by _activeHost.run, propagated across await via the
+	//    Promise patch above).
+	const fromStack = _activeHost.get()
+	if (fromStack !== undefined) return fromStack
+
+	// 2. window.event — sync event-handler fallback. Covers inline arrow
+	//    template bindings whose handlers run before any _activeHost.run
+	//    frame has been pushed.
+	if (typeof window !== 'undefined') {
+		const evt = (window as Window & { event?: Event }).event
+		if (evt) {
+			const path = evt.composedPath()
+			for (const node of path) {
+				if (node instanceof HTMLElement) return node
+			}
+		}
+	}
+
+	// 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}`)
+}