@mhmo91/schmancy 0.9.28 → 0.10.2

package/src/range/range.ts

@@ -1,4 +1,4 @@
-import { TailwindElement } from '@mixins/index'
+import { SchmancyElement } from '@mixins/index'
 import { css, html } from 'lit'
 import { customElement, property } from 'lit/decorators.js'
 import { when } from 'lit/directives/when.js'
@@ -11,7 +11,8 @@ export type SchmancyRangeChangeEvent = CustomEvent<{ value: number }>
  * @fires change - Fires on value change with { value: number }
  */
 @customElement('schmancy-range')
-export class SchmancyRange extends TailwindElement(css`
+export class SchmancyRange extends SchmancyElement {
+	static styles = [css`
 	input[type='range'] {
 		-webkit-appearance: none;
 		appearance: none;
@@ -53,7 +54,7 @@ export class SchmancyRange extends TailwindElement(css`
 		background: var(--color-primary, #6750a4);
 		cursor: pointer;
 	}
-`) {
+`];
 	@property({ type: Number }) min = 0
 	@property({ type: Number }) max = 1
 	@property({ type: Number }) step = 0.01

package/src/rxjs-utils/waitForElements.ts

@@ -8,7 +8,7 @@ import observeOnMutation from './mutation-observer'
  * @example waitForElements(['button', 'input']).subscribe(([button, input]) => button.click())
  * @returns
  */
-export default function waitForElements<T extends Array<T>>(
+export default function waitForElements(
   /**
    * @param selectors The selectors to use to find the elements
    * @type { string[] }

package/src/rxjs-utils/waitForElementsAll.ts

@@ -8,7 +8,7 @@ import observeOnMutation from './mutation-observer'
  * @example waitForElements(['button', 'input']).subscribe(([button, input]) => button.click())
  * @returns
  */
-export default function waitForElementsAll<T extends Array<T>>(
+export default function waitForElementsAll(
   /**
    * @param selectors The selectors to use to find the elements
    * @type { string[] }

package/src/select/select.ts

@@ -1,5 +1,5 @@
 import { autoUpdate, computePosition, flip, offset, shift } from '@floating-ui/dom'
-import { $LitElement } from '@mixins/index'
+import { SchmancyElement } from '@mixins/index'
 import { color } from '@schmancy/directives'
 import SchmancyInput from '@schmancy/input/input'
 import SchmancyOption from '@schmancy/option/option'
@@ -7,6 +7,7 @@ import { SchmancyTheme } from '@schmancy/theme/theme.interface'
 import { css, html, PropertyValues, TemplateResult } from 'lit'
 import { customElement, property, query, queryAssignedElements, state } from 'lit/decorators.js'
 import { classMap } from 'lit/directives/class-map.js'
+import { ifDefined } from 'lit/directives/if-defined.js'
 import { BehaviorSubject, combineLatest, fromEvent, Subject, takeUntil } from 'rxjs'
 import { tap, withLatestFrom } from 'rxjs/operators'
 
@@ -15,18 +16,7 @@ export type SchmancySelectChangeEvent = CustomEvent<{
 }>
 
 /**
- * Dropdown selector — single or multi-select from a list of `<schmancy-option>` children. Form-associated.
- *
- * @element schmancy-select
- * @summary Material Design dropdown with type-to-filter, keyboard nav, single or multi-select. Options are declared as `<schmancy-option>` children; value / values props sync with selection.
- * @example
- * <schmancy-select name="priority" label="Priority" value="medium">
- *   <schmancy-option value="low">Low</schmancy-option>
- *   <schmancy-option value="medium">Medium</schmancy-option>
- *   <schmancy-option value="high">High</schmancy-option>
- * </schmancy-select>
- * @platform select change - Floating-UI-positioned listbox. Degrades to native `<select>` styled via Tailwind if the tag never registers, though multi-select UX is lost.
- * @fires change - `SchmancySelectChangeEvent` with `{ value }` (single) or `{ value: string[] }` (multi).
+ * Select dropdown component with single and multi-select support.
  *
  * @prop {string} name - Name attribute for form submission
  * @prop {string} label - Label text displayed above the select
@@ -37,7 +27,8 @@ export type SchmancySelectChangeEvent = CustomEvent<{
  * @prop {string[]} values - Selected values (multi-select mode)
  */
 @customElement('schmancy-select')
-export class SchmancySelect extends $LitElement(css`
+export class SchmancySelect extends SchmancyElement {
+	static styles = [css`
 	:host {
 		display: block;
 		position: relative;
@@ -47,7 +38,8 @@ export class SchmancySelect extends $LitElement(css`
 		overflow-y: auto;
 		outline: none;
 	}
-`) {
+`]
+
 	// Form association setup
 	static formAssociated = true
 	private internals?: ElementInternals
@@ -692,7 +684,7 @@ export class SchmancySelect extends $LitElement(css`
 		return html`
 			<div class="relative ${this.disabled ? 'opacity-60 cursor-not-allowed' : ''}">
 				<sch-input
-					.name=${this.name}
+					.name=${this.name ?? ''}
 					tabIndex=${this.disabled ? '-1' : '0'}
 					class="trigger"
 					role="combobox"
@@ -701,7 +693,7 @@ export class SchmancySelect extends $LitElement(css`
 					aria-controls="options"
 					aria-autocomplete="none"
 					aria-required=${this.required}
-					aria-activedescendant=${this._focusedOptionId || undefined}
+					aria-activedescendant=${ifDefined(this._focusedOptionId || undefined)}
 					aria-disabled=${this.disabled}
 					.label=${this.label}
 					.placeholder=${this.placeholder}
@@ -712,7 +704,7 @@ export class SchmancySelect extends $LitElement(css`
 					.error=${showErrors}
 					.validateOn=${this.validateOn}
 					.size=${this.size}
-					readonly
+					.readonly=${true}
 					clickable
 					@click=${(e: MouseEvent) => {
 						// Don't process clicks if disabled

package/src/sheet/hook.ts

@@ -31,7 +31,7 @@ export function on(propName: string, options?: WatchOptions) {
 
 				if (oldValue !== newValue) {
 					if (!options?.waitUntilFirstUpdate || this.hasUpdated) {
-						this[name].call(this, oldValue, newValue)
+						this[name](oldValue, newValue)
 					}
 				}
 			}

package/src/sheet/sheet.ts

@@ -1,4 +1,4 @@
-import { $LitElement } from '@mixins/index'
+import { SchmancyElement } from '@mixins/index'
 import { area } from '../area'
 import { html, css } from 'lit'
 import { customElement, property, query } from 'lit/decorators.js'
@@ -7,25 +7,9 @@ import { on } from './hook'
 import { SchmancySheetPosition, sheet } from './sheet.service'
 import { BLACKBIRD_EASING, DURATION_ENTER, DURATION_EXIT, DURATION_BACKDROP, EASE_OUT, EASE_IN } from '../utils/animation'
 
-/**
- * Side-docked or bottom-docked panel — a dialog variant that slides in from an edge. Driven imperatively by the `sheet` service; rarely instantiated directly.
- *
- * @element schmancy-sheet
- * @summary Prefer `sheet.open({ component, position })` over placing this element declaratively — the service handles stacking, focus, close on outside-click, ESC, and router integration.
- * @example
- * import { sheet, SchmancySheetPosition } from '@mhmo91/schmancy'
- * sheet.open({
- *   component: new MyEditorElement(),
- *   position: SchmancySheetPosition.Side,
- *   title: 'Edit item',
- * })
- * @platform dialog close - Positioned-fixed panel with backdrop. Degrades to a `<dialog>` if the tag never registers — loses slide animation, keeps focus trap + dismiss.
- * @attr position - `'side' | 'bottom'`. Which edge the sheet docks to.
- * @attr open - Boolean; sheet is visible when true.
- * @fires close - When the sheet is dismissed (backdrop click, close button, ESC).
- */
 @customElement('schmancy-sheet')
-export default class SchmancySheet extends $LitElement(css`
+export default class SchmancySheet extends SchmancyElement {
+	static styles = [css`
 	:host {
 		position: fixed;
 		inset: 0;
@@ -48,7 +32,8 @@ export default class SchmancySheet extends $LitElement(css`
 	@media (prefers-reduced-motion: reduce) {
 		.content { box-shadow: var(--schmancy-sys-elevation-3); }
 	}
-`) {
+`]
+
 	// uid is inherited from $LitElement mixin - auto-generated or set via attribute
 	@property({ type: Boolean, reflect: true }) open = false
 	@property({ type: String, reflect: true }) position: SchmancySheetPosition = SchmancySheetPosition.Side

package/src/skeleton/skeleton.ts

@@ -1,4 +1,4 @@
-import { TailwindElement } from '@mixins/index'
+import { SchmancyElement } from '@mixins/index'
 import { css, html } from 'lit'
 import { customElement, property } from 'lit/decorators.js'
 
@@ -14,7 +14,8 @@ import { customElement, property } from 'lit/decorators.js'
  * @csspart surface - The shimmering surface element.
  */
 @customElement('schmancy-skeleton')
-export class SchmancySkeleton extends TailwindElement(css`
+export class SchmancySkeleton extends SchmancyElement {
+	static styles = [css`
 	:host {
 		display: block;
 		width: var(--_sw, 100%);
@@ -46,7 +47,7 @@ export class SchmancySkeleton extends TailwindElement(css`
 			background: var(--schmancy-sys-color-surface-containerHighest, #e6e6e6);
 		}
 	}
-`) {
+`];
 	@property({ type: String, reflect: true }) shape: 'rect' | 'circle' | 'text' = 'rect'
 	@property({ type: String }) width = ''
 	@property({ type: String }) height = ''

package/src/slider/slide.ts

@@ -1,4 +1,4 @@
-import { $LitElement } from '@mixins/index'
+import { SchmancyElement } from '@mixins/index'
 import { css, html } from 'lit'
 import { customElement, property } from 'lit/decorators.js'
 import { cache } from 'lit/directives/cache.js'
@@ -18,7 +18,8 @@ type SlideType = 'image' | 'video' | 'content'
 type ObjectFit = 'cover' | 'contain' | 'fill' | 'scale-down' | 'none'
 
 @customElement('schmancy-slide')
-export class SchmancySlide extends $LitElement(css`
+export class SchmancySlide extends SchmancyElement {
+	static styles = [css`
 	:host {
 		display: block;
 		scroll-snap-align: center; /* If your slider uses scroll-snap */
@@ -30,7 +31,8 @@ export class SchmancySlide extends $LitElement(css`
 		height: auto;
 		object-fit: var(--object-fit, cover);
 	}
-`) {
+`]
+
 	/**
 	 * Determines how this slide should be rendered.
 	 * Defaults to 'content' if not provided.

package/src/slider/slider.ts

@@ -1,11 +1,12 @@
-import { $LitElement } from '@mixins/index'
+import { SchmancyElement } from '@mixins/index'
 import { css, html } from 'lit'
 import { customElement, property, query, state } from 'lit/decorators.js'
 import { fromEvent } from 'rxjs'
 import { throttleTime } from 'rxjs/operators'
 
 @customElement('schmancy-slider')
-export class SchmancySlider extends $LitElement(css`
+export class SchmancySlider extends SchmancyElement {
+	static styles = [css`
 	.slider {
 		/* Lay out slides horizontally, one after another */
 		display: flex;
@@ -30,7 +31,8 @@ export class SchmancySlider extends $LitElement(css`
 		flex: 0 0 100%;
 		box-sizing: border-box;
 	}
-`) {
+`]
+
 	/**
 	 * Currently centered slide index
 	 */

package/src/splash-screen/splash-screen.ts

@@ -1,4 +1,4 @@
-import { $LitElement } from '@mixins/litElement.mixin'
+import { SchmancyElement } from '@mixins/index'
 import { css, html } from 'lit'
 import { customElement, property, state } from 'lit/decorators.js'
 import { styleMap } from 'lit/directives/style-map.js'
@@ -30,7 +30,8 @@ export type SchmancySplashScreenDoneEvent = CustomEvent<void>
  * ```
  */
 @customElement('schmancy-splash-screen')
-export default class SchmancySplashScreen extends $LitElement(css`
+export default class SchmancySplashScreen extends SchmancyElement {
+	static styles = [css`
 	:host {
 		display: block;
 		position: relative;
@@ -56,7 +57,8 @@ export default class SchmancySplashScreen extends $LitElement(css`
 		width: 100%;
 		transition: opacity var(--schmancy-splash-transition, 500ms) ease-in-out;
 	}
-`) {
+`]
+
 	/**
 	 * Minimum duration (ms) the splash layer stays visible. Prevents a flash
 	 * when the app loads faster than expected.

package/src/state/CLAUDE.md

@@ -0,0 +1,161 @@
+# Agent brief — `@mhmo91/schmancy/state`
+
+When you're touching anything in this directory or anything that imports
+from `@mhmo91/schmancy/state`, read this first.
+
+## What this module is
+
+A reactive state primitive for the schmancy library:
+
+- `state(namespace).memory(initial)` / `.local()` / `.session()` / `.idb()`
+  → returns a module-scoped singleton with a TC39 signal, an RxJS
+  Observable, sync getter, microtask-debounced persistence, and a
+  Disposable + (for `idb`) AsyncDisposable lifecycle.
+- `computed(fn)` — re-export of `@lit-labs/signals/computed`.
+- `effect(fn)` — runs `fn` whenever any signal it reads changes;
+  returns a `Disposable` for cleanup.
+- `observe(source)` — legacy property decorator. One-way binds a class
+  field to a state for the host's lifetime. Use only when the value is
+  needed AS a class field (event handlers, derived methods, DevTools).
+- `bindState(host, source)` — `ReactiveController` helper. Same
+  guarantees as `@observe`, no decorator. Use when the host isn't a
+  `$LitElement` subclass.
+- `stateFromObservable(observable, namespace, initial)` — bridges an
+  RxJS source into a `state()`.
+
+The module ships `Signal` (TC39 polyfill) and `StorageBackend` as named
+type exports.
+
+## Default subscription pattern
+
+`$LitElement()` already composes `SignalWatcher` over its mixin chain.
+Every signal read inside `render()` auto-tracks. **The default consumer
+needs zero binding code:**
+
+```ts
+@customElement('cart-view')
+class CartView extends $LitElement() {
+  render() { return html`Items: ${cart.value.items.length}` }
+}
+```
+
+The imported `cart` singleton IS the binding. Only reach for `@observe`
+or `bindState` when you need the value as a class field.
+
+## Scoping (`<schmancy-context provides>`)
+
+The default state is a module-scoped singleton. `<schmancy-context>` is
+the **only** way to scope a state per subtree. Reads and writes inside
+the element auto-resolve to a per-element isolated copy via the
+`@lit/context` request protocol; outside, they read the global.
+
+```ts
+<schmancy-context .provides=${[cart]}>
+  <cart-view></cart-view>   <!-- isolated -->
+</schmancy-context>
+<cart-summary></cart-summary>   <!-- module-scoped global -->
+```
+
+Two infrastructure files own the mechanics:
+
+- `state/active-host.ts` — `_activeHost` Variable + `Promise.then`
+  patch + `resolveActiveHost()` 4-tier fallback (stack →
+  `window.event` → `document.activeElement` → undefined). Hand-rolled
+  TC39 AsyncContext.Variable polyfill (~30 lines). The patch is
+  idempotent and uses `_origThen.call(this, …)` so Promise subclassing
+  / `Symbol.species` are untouched. Decommissions the day a real
+  polyfill or native AsyncContext lands — drop the file, swap the
+  `_activeHost` export.
+- `state/schmancy-context.ts` — the `<schmancy-context>` element. One
+  `ContextProvider` per state in `provides`; all destroyed on
+  disconnect.
+
+`mixins/SchmancyElement.ts` carries the integration points: prototype-
+chain wrap of every concrete subclass at first construction (caches in
+a `WeakSet`), and `addEventListener` / `removeEventListener` overrides
+that wrap host listeners.
+
+Inline arrow handlers in templates (`@click=${() => …}`) are not
+wrapped — they attach to child elements, not the host. They resolve
+via the `window.event.composedPath()` fallback.
+
+## Rules for code in this directory
+
+- **One file by default.** `state/index.ts` holds the factory, types,
+  variant write APIs, persistence-debouncing wrapper, RxJS interop,
+  decorator, and helpers. `persist.ts`, `active-host.ts`, and
+  `schmancy-context.ts` are the only siblings — they own storage
+  adapters / the JSON tunnel, the host tracker / `Promise.then` patch,
+  and the scoping element respectively. Do not split further until a
+  second consumer of an internal helper emerges.
+- **Every read and write on a global instance routes through
+  `resolveContextual`.** Don't add a fast path that bypasses it — the
+  whole point of the scoping primitive is that consumer code is
+  unchanged whether or not a `<schmancy-context>` ancestor exists.
+- **Isolated copies are direct-access.** They serve as resolution
+  targets and must not themselves call `resolveContextual` (would
+  recurse). The `{ isolated: true }` branch in `createInstance`
+  preserves this invariant.
+- **Don't extend the `Promise.prototype.then` patch.** It is the
+  minimum surface needed for await propagation. New schedulers
+  (custom queueMicrotask wrappers, etc.) should be solved by routing
+  through Promise, not by adding more patches.
+- **No tsconfig flip.** Schmancy stays on `experimentalDecorators: true`.
+  Any new decorator in this module is a legacy property/method
+  decorator, same shape as `@property`/`@state`/`@query`.
+- **No `accessor` keyword.** Implied by the line above — but call it
+  out so a reviewer doesn't miss it. The schmancy codebase doesn't use
+  `accessor`; this module follows the same convention.
+- **Brand symbols are plain `Symbol(...)` constants** (`stateBrand`,
+  `namespaceBrand`). They are private to the module and not exported.
+  Do not export them; consumers use the `State<>` type for nominal
+  identity.
+- **Microtask-coalesced writes.** Every persistent backend wraps writes
+  in a per-instance microtask debouncer. Multiple `set`/`update`/
+  `replace` calls in the same task collapse to one `save()`. Do not
+  bypass — write through the variant API.
+- **`signal-polyfill` is the runtime contract.** `@lit-labs/signals` is
+  the canonical import; it re-exports the polyfill plus
+  `SignalWatcher`. Do not import `signal-polyfill` directly.
+
+## Rules for tests
+
+- **Vitest browser mode (Chromium via Playwright).** Real DOM, real
+  IndexedDB, real localStorage. Imported via the schmancy
+  `vitest.config.ts`.
+- **Static namespaces in tests.** The factory's `${string}/${string}`
+  template literal rejects dynamic strings. Use literal namespaces like
+  `'test/foo'` so type inference works without casts.
+- **`using` for test-scoped state.** `using cart = state(...).memory(...)`
+  disposes on scope exit, including failure cases. Use plain `const`
+  for module-scope state in production.
+- **Microtask draining.** Signal-to-Observable emission and write
+  coalescing both use `queueMicrotask`. After `state.set(...)`, call
+  `await settle()` (two microtask drains) before asserting derived
+  state, then `await el.updateComplete` for any host re-render.
+
+## Rules for behaviour changes
+
+- **Public surface is committed.** `value`, `signal`, `$`, `ready`,
+  `loaded`, `defaultValue`, `namespace`, `storage`, `destroy`,
+  `[Symbol.dispose]`, `[Symbol.asyncDispose]` (idb only), variant
+  write methods. Don't rename, don't shape-shift. Add new things;
+  don't change existing ones.
+- **Variant API dispatch is `Kind<T>`-driven.** Don't add separate
+  `mapState()` / `setState()` factories. If a new shape comes up,
+  extend the `Kind<T>` classifier and add a matching variant API
+  interface.
+- **Storage keys are namespace strings.** `state('hannah/cart').local(...)`
+  uses `'hannah/cart'` as the storage key. Don't expose a separate
+  key parameter; the namespace IS the key.
+
+## Pointers
+
+- **State plan and Phase 0 findings:** the original implementation plan
+  lives in `~/.claude/plans/indexed-twirling-stroustrup.md`; spike
+  artifacts and findings are at
+  `packages/schmancy/_scratch/spikes/findings.md` (gitignored).
+- **Skill doc for downstream consumers:**
+  `packages/schmancy/skills/schmancy/state.md`.
+- **Migration cheatsheet** for moving off the v1 `createContext`:
+  `packages/schmancy/src/state/MIGRATION.md`.