@mhmo91/schmancy 0.10.9 → 0.10.11

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mhmo91/schmancy",
-	"version": "0.10.9",
+	"version": "0.10.11",
 	"description": "UI library build with web components",
 	"main": "./dist/index.js",
 	"customElements": "custom-elements.json",

package/skills/schmancy/INDEX.md

@@ -8,7 +8,7 @@ The framework pieces — touch before components.
 
 - [Area](./area.md) — `<schmancy-area>`, `<schmancy-route>`, `area.push()`, `lazy()` for routing.
 - [State](./state.md) — `state()` factory (memory / session / local / idb), variant write APIs (`Object` / `Map` / `Set` / `Array` / `Scalar`), `bindState`, `computed`, `stateFromObservable`.
-- [Mixins](./mixins.md) — `$LitElement` base class.
+- [Mixins](./mixins.md) — `SchmancyElement` 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`.

package/skills/schmancy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: schmancy
-description: UI patterns, component APIs, and conventions for the @mhmo91/schmancy web-component library (Lit + RxJS + Tailwind) — the exclusive UI stack in this repo's `web/` workspace. Fire this skill on ANY web-UI work, even when the user doesn't name schmancy explicitly — including adding or editing a component, building a form, showing a dialog / toast / side drawer / bottom sheet, wiring routing, reading or writing a context, styling with theme tokens, adding a drop zone / file input / date picker / autocomplete, working with `$LitElement`, or touching any `<schmancy-*>` tag. Also fire on prompts like "build a page", "add a modal", "wire a route", "save user prefs in storage", "animate this", "style with our theme", "make a notification", "how do I do X in Lit", "my drag-and-drop", "dark mode toggle".
+description: UI patterns, component APIs, and conventions for the @mhmo91/schmancy web-component library (Lit + RxJS + Tailwind) — the exclusive UI stack in this repo's `web/` workspace. Fire this skill on ANY web-UI work, even when the user doesn't name schmancy explicitly — including adding or editing a component, building a form, showing a dialog / toast / side drawer / bottom sheet, wiring routing, reading or writing a state, styling with theme tokens, adding a drop zone / file input / date picker / autocomplete, working with `SchmancyElement`, or touching any `<schmancy-*>` tag. Also fire on prompts like "build a page", "add a modal", "wire a route", "save user prefs in storage", "animate this", "style with our theme", "make a notification", "how do I do X in Lit", "my drag-and-drop", "dark mode toggle".
 ---
 
 # Schmancy
@@ -56,19 +56,20 @@ Use component tags (`<schmancy-menu>`, `<schmancy-dropdown>`, `<schmancy-tooltip
   Remediation: before reporting any file compliant, run a grep against each forbidden pattern named by the rule under audit (e.g. `grep -nE '\[(?:[^]]+)\]' <file>` for `TOKEN_FIRST_NO_ARBITRARY`; `grep -nE 'class="[^"]*\b(text-|bg-|border-|rounded-|shadow-|tracking-|leading-|p[xy]?-)' <file>` plus a manual scan for raw `<div>`/`<span>` carrying those classes for `PRIMITIVE_FIRST`). The compliance report's body is the concatenation of those grep outputs annotated with their rule name; an empty body across every pattern under every rule is the only form of "compliant". A claim of compliance unaccompanied by the grep evidence is not a compliance report and is treated as an unverified assertion that the audit loop rejects.
 - **Schmancy primitive first** (`PRIMITIVE_FIRST`). Within `web/**`, every visible UI element is a custom element exported from `packages/schmancy/src/**`, and an element absent from that export set is added there before being imported into `web/**`. The rule sits above the styling rules: a `<div class="text-xs text-surface-on-variant">…</div>` whose role is typography is a violation even when every utility resolves to a registered token, because `<schmancy-typography>` already covers that role; the styling rules apply only to whatever class strings remain after the right primitive has been selected.
   Sources: [packages/schmancy/skills/schmancy/INDEX.md](../INDEX.md) catalogues the export set by job (foundations / atoms / forms / navigation / overlays / interaction / feedback / display); each role's reference file (`typography.md`, `surface.md`, `button.md`, `overlay.md`, …) names the props, slots, and events that displace the equivalent `<div>` + utility-class pattern. The export set is the single source — a primitive that is not exported from `packages/schmancy/src/**` does not satisfy this rule even if it lives in a private file inside the schmancy tree.
-  Remediation: walk every `.ts` and `.html` file under `web/**` and list every raw HTML element whose class string carries design-system styling (typography, color, spacing-as-design-decision, surface, layout-as-design-decision, motion, overlay) — those are the violations. For each, look up the matching schmancy primitive in `INDEX.md` and rewrite the element through that primitive (`<schmancy-typography type=… token=…>` for type-scale text, `<schmancy-surface type=… fill=…>` for elevated/bounded surfaces, `<schmancy-grid>`/`<schmancy-flex>` for layout primitives with design intent, the imperative `show`/`$notify`/`schmancyContentDrawer.push` services for overlays, `<schmancy-scroll>` for scroll containers). When a needed primitive is absent from the export set, design and implement it as a new component under `packages/schmancy/src/<role>/` — extending `$LitElement(style?)`, registered in `HTMLElementTagNameMap`, exported through the package barrel, and documented with a sibling `.md` in the skill's reference set — and only then introduce the first call site in `web/**`. The audit subagent iterates the whole `web/**` tree, surfaces the violation list, applies the rewrites, runs `yarn workspace @momo/web tsc --noEmit` plus the colocated `*-view.test.ts` suites, and reports pre-existing violations that require a new schmancy primitive as a separate punch list for designer/architect approval before the implementation lands. The loop exits when every `web/**` file's visible UI elements are schmancy primitives and the typecheck plus the test suites pass.
+  Remediation: walk every `.ts` and `.html` file under `web/**` and list every raw HTML element whose class string carries design-system styling (typography, color, spacing-as-design-decision, surface, layout-as-design-decision, motion, overlay) — those are the violations. For each, look up the matching schmancy primitive in `INDEX.md` and rewrite the element through that primitive (`<schmancy-typography type=… token=…>` for type-scale text, `<schmancy-surface type=… fill=…>` for elevated/bounded surfaces, `<schmancy-grid>`/`<schmancy-flex>` for layout primitives with design intent, the imperative `show`/`$notify`/`schmancyContentDrawer.push` services for overlays, `<schmancy-scroll>` for scroll containers). When a needed primitive is absent from the export set, design and implement it as a new component under `packages/schmancy/src/<role>/` — extending `SchmancyElement` with `static styles = [css\`...\`]`, registered in `HTMLElementTagNameMap`, exported through the package barrel, and documented with a sibling `.md` in the skill's reference set — and only then introduce the first call site in `web/**`. The audit subagent iterates the whole `web/**` tree, surfaces the violation list, applies the rewrites, runs `yarn workspace @momo/web tsc --noEmit` plus the colocated `*-view.test.ts` suites, and reports pre-existing violations that require a new schmancy primitive as a separate punch list for designer/architect approval before the implementation lands. The loop exits when every `web/**` file's visible UI elements are schmancy primitives and the typecheck plus the test suites pass.
 
 ## Non-negotiable conventions
 
 **Component authoring**
-- Every component extends `SchmancyElement` and declares its component-local CSS via `static styles = [css\`...\`]`. Never raw `LitElement`. Never wrap with `SignalWatcher` — the base already includes it; double-wrapping creates two nested Computeds and panics with "Detected cycle in computations" at runtime. The deprecated `$LitElement(style?)` factory still works (it now just delegates to SchmancyElement) but should not appear in new code.
+- Every component extends `SchmancyElement` and declares its component-local CSS via `static styles = [css\`...\`]`. Never raw `LitElement`. Never wrap with `SignalWatcher` — the base already includes it; double-wrapping creates two nested Computeds and panics with "Detected cycle in computations" at runtime.
 - Every RxJS subscription ends with `.pipe(takeUntil(this.disconnecting))`.
 - Register the tag in `HTMLElementTagNameMap` for TypeScript.
 
 **State**
-- Contexts live at module scope. Many small contexts beat one monolith.
-- Gate subscriptions with `filter(() => ctx.ready)` when reading persisted contexts.
-- Storage tiers: `'memory'` (regenerable) · `'session'` (per-tab) · `'local'` (user prefs) · `'indexeddb'` (>100-entry collections).
+- States live at module scope. Many small states beat one monolith. Use `state('feature/name').{memory,session,local,idb}(initial)` from `@mhmo91/schmancy/state`.
+- Reading `state.value` inside `render()` auto-tracks via the base class's `SignalWatcher` — no decorator or binding needed for the default case.
+- `await state.ready` (or `if (state.loaded)`) before reading persisted-backend values that hydrate asynchronously.
+- Storage tiers: `.memory()` (regenerable) · `.session()` (per-tab) · `.local()` (user prefs) · `.idb()` (>100-entry collections).
 
 **Routing**
 - Route guards are `Observable<boolean>`, never cached booleans.

package/skills/schmancy/audio.md

@@ -36,7 +36,7 @@ sound.muted$.subscribe(m => {})
 ```
 
 ## Settings Persistence
-Volume, mute, and custom theme persist to `localStorage` under key `schmancy-sound-settings` (via `createContext`).
+Volume, mute, and custom theme persist to `localStorage` under key `schmancy-sound-settings` (via `state(...).local(...)` from `@mhmo91/schmancy/state`).
 
 ## AI-Generated Themes
 ```typescript

package/skills/schmancy/discovery.md

@@ -38,7 +38,7 @@ discoverAnyComponent('schmancy-navigation-rail', 'schmancy-navigation-bar')
 ```
 
 ### `discoverElement(selector, timeout = 150)`
-Finds any element by CSS selector across shadow DOM. Uses a request ID + universal `schmancy-discover` event. Every `$LitElement` responds if it finds a match in its shadow root.
+Finds any element by CSS selector across shadow DOM. Uses a request ID + universal `schmancy-discover` event. Every `SchmancyElement` responds if it finds a match in its shadow root.
 ```typescript
 discoverElement('[data-section="pricing"]').subscribe(section => section?.scrollIntoView())
 ```
@@ -51,12 +51,12 @@ discoverAllElements('.flagged').subscribe(all => console.log(all.length))
 
 ## How the Handshake Works
 1. Caller creates a unique `requestId` and broadcasts `schmancy-discover` on `window` with `{ selector, requestId }`.
-2. Every `$LitElement` listens for this event (wired up in the base class).
+2. Every `SchmancyElement` listens for this event (wired up in the base class).
 3. Any matching element dispatches `schmancy-discover-response` with `{ requestId, element }`.
 4. Caller collects responses for the timeout window and emits via RxJS.
 
 ## Pattern in Base Class
-Every `$LitElement` inherits auto-response: `discover<T>(tag)` (method on the component) and `{tagName}-where-are-you`/`{tagName}-here-i-am` events. See [mixins.md](./mixins.md).
+Every `SchmancyElement` inherits auto-response: `discover<T>(tag)` (method on the component) and `{tagName}-where-are-you`/`{tagName}-here-i-am` events. See [mixins.md](./mixins.md).
 
 ## When to Use
 - Cross-shadow coordination between unrelated components.

package/skills/schmancy/menu.md

@@ -36,4 +36,4 @@ Auto-dismisses the dialog when clicked. Renders as a `schmancy-list-item` intern
 </schmancy-menu>
 ```
 
-Uses `$dialog.component()` internally. Menu items auto-dismiss the dialog. Custom components in the default slot must call `$dialog.dismiss()` manually.
+Uses `show(overlay, { anchor })` from `@mhmo91/schmancy/overlay` internally. `<schmancy-menu-item>` auto-closes the menu by dispatching a `'close'` event on click. Custom components in the default slot dismiss the menu the same way: `this.dispatchEvent(new CustomEvent('close', { bubbles: true, composed: true }))`.

package/skills/schmancy/overlay.md

@@ -40,7 +40,7 @@ Centered is the fallback (no anchor given). Sheet is the responsive adaptation (
 
 ## Subscription IS the overlay lifecycle
 
-Inside any `$LitElement`, pipe `takeUntil(this.disconnecting)`. When the caller unmounts, the overlay auto-dismisses — no handles to track, no leaks.
+Inside any `SchmancyElement`, pipe `takeUntil(this.disconnecting)`. When the caller unmounts, the overlay auto-dismisses — no handles to track, no leaks.
 
 ```ts
 show(MyForm, { props: { id }, anchor: ev })

package/skills/schmancy/state.md

@@ -29,8 +29,8 @@ 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() {
+// Subscribe in a SchmancyElement — direct read auto-tracks via SignalWatcher
+class CartView extends SchmancyElement {
   render() { return html`Items: ${cart.value.items.length}` }
 }
 
@@ -207,18 +207,18 @@ with zero ceremony.
 
 ### (1) Default — direct read inside `render()`
 
-`$LitElement()` composes `SignalWatcher` from `@lit-labs/signals`.
+`SchmancyElement` 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 { html } from 'lit'
 import { customElement } from 'lit/decorators.js'
-import { $LitElement } from '@mixins/index'
-import { cart } from './cart.context'
+import { SchmancyElement } from '@mhmo91/schmancy/mixins'
+import { cart } from './cart.state'
 
 @customElement('cart-view')
-export class CartView extends $LitElement() {
+export class CartView extends SchmancyElement {
   render() {
     return html`<span>Items: ${cart.value.items.length}</span>`
   }
@@ -243,7 +243,7 @@ derived methods, DevTools inspection, or readability:
 import { observe } from '@mhmo91/schmancy/state'
 
 @customElement('cart-view')
-export class CartView extends $LitElement() {
+export class CartView extends SchmancyElement {
   @observe(cart) cart!: CartState
 
   onClick() {
@@ -268,12 +268,12 @@ works under the existing tsconfig with no migration.
 
 ### (3) `bindState(host, source)` — imperative form
 
-For hosts that aren't `$LitElement` subclasses (rare):
+For hosts that aren't `SchmancyElement` subclasses (rare):
 
 ```ts
 import { bindState } from '@mhmo91/schmancy/state'
 
-class CustomHost extends LitElement {   // not a $LitElement subclass
+class CustomHost extends LitElement {   // not a SchmancyElement subclass
   cart = bindState(this, cart)
   render() {
     return html`<span>Items: ${this.cart.value.items.length}</span>`
@@ -376,7 +376,7 @@ two side-by-side checkout flows, an `<iframe>`-like wizard, an
 embedded preview — wrap the subtree in `<schmancy-context>`.
 
 ```ts
-class App extends $LitElement() {
+class App extends SchmancyElement {
   render() {
     return html`
       <schmancy-context .provides=${[cart]}>
@@ -402,7 +402,7 @@ after an `await fetch(...)` — all of it auto-resolves to the right
 instance based on tree position.
 
 ```ts
-class CartView extends $LitElement() {
+class CartView extends SchmancyElement {
   render() {
     return html`
       <button @click=${() => cart.set({ total: 0 })}>Clear</button>
@@ -418,22 +418,42 @@ class CartView extends $LitElement() {
 }
 ```
 
-Coverage of the call paths is provided by `SchmancyElement`:
+Coverage of the call paths is provided by `SchmancyElement` and
+`<schmancy-context>`:
 
-- `render()` and every Lit lifecycle hook — wrapped at construction.
+- `render()` and every Lit lifecycle hook — wrapped at construction
+  via the `_activeHost.run(host, fn)` stack.
 - 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()`.
+- Explicit `.then(...)` continuations off a class-method Promise —
+  propagated via the `Promise.prototype.then` patch in
+  `state/active-host.ts`, which captures the active host at chain time
+  and restores it inside the callback.
+- Inline arrow handlers in templates (`@click=${() => …}`) and any
+  other DOM event handler attached inside a `<schmancy-context>`
+  subtree — resolved via the capture-phase event listener that
+  `<schmancy-context>` installs on itself for ~18 common event types.
+  The listener publishes the event's target as the active host through
+  the `_publishEventHost(node)` slot for the duration of the
+  synchronous handler chain (slot self-clears in the next microtask).
+
+**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 the `Promise.then`
+patch does not see the resumption. Class methods that mutate state
+across an `await` boundary 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 chain explicitly 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.
 
 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.
+`setInterval` with no triggering user event — also fall through to
+the module-scoped global. That is the correct semantic: those
+callbacks have no tree position to resolve to.
 
 ### Lifecycle