@mhmo91/schmancy 0.10.9 → 0.10.11

package/src/CLAUDE.md

@@ -1,20 +1,36 @@
-# Schmancy Library Source Patterns
+# Schmancy library source — agent brief
 
-## Component Architecture
+This file lives in the source tree. It tells you what's specific to
+**authoring schmancy components**. For the public surface (every tag,
+every service, every convention downstream consumers see), the
+authoritative docs are in `skills/schmancy/`. Cross-link rather than
+duplicate — those docs are checked into the npm tarball and rendered
+by the Claude Code plugin. Drift here means drift everywhere.
 
-### Base Mixin Pattern
-All components extend `$LitElement(style?)` which provides:
-- `disconnecting` Subject for RxJS cleanup via `takeUntil(this.disconnecting)`
-- `classMap()` - enhanced to split space-separated keys
-- `styleMap()` - direct passthrough to Lit directive
-- `discover<T>(tag: string)` - event-based component discovery
-- Auto-response to `{tagName}-where-are-you` events
+## Where to read first
+
+- `skills/schmancy/INDEX.md` — full catalog of public tags and services.
+- `skills/schmancy/SKILL.md` — non-negotiable conventions every consumer follows.
+- `skills/schmancy/mixins.md` — `SchmancyElement` base class (what every component extends).
+- `skills/schmancy/state.md` — `state()` factory + `<schmancy-context>` scoping.
+- `skills/schmancy/overlay.md` — `show()` + `confirm()` + `prompt()`; the only overlay primitives.
+- `skills/schmancy/directives.md` — Lit + schmancy directives.
+
+## Source-author rules (not in the consumer docs)
+
+### Component skeleton
+
+Every concrete component:
 
-### Component Registration
 ```typescript
+import { SchmancyElement } from '@mixins/index'
+import { customElement } from 'lit/decorators.js'
+import { css, html } from 'lit'
+
 @customElement('schmancy-{name}')
-export class Schmancy{Name} extends $LitElement(style) {
-  // Component implementation
+export class Schmancy{Name} extends SchmancyElement {
+  static styles = [css`:host { display: block }`]
+  render() { return html`<slot></slot>` }
 }
 
 declare global {
@@ -24,396 +40,132 @@ declare global {
 }
 ```
 
-## Styling Approach
+- Never extend raw `LitElement`.
+- Never wrap with `SignalWatcher` — `SchmancyElement` already does. Double-wrapping panics with "Detected cycle in computations" at runtime; the `NO_SIGNAL_WATCHER_WRAP` pre-edit lint rule blocks it.
+- The `$LitElement(style?)` factory in `mixins/litElement.mixin.ts` is a deprecated alias kept for the migration window. **Do not use it in new files.** The `PREFER_SCHMANCY_ELEMENT` pre-edit lint rule flags new uses; the migration section in `skills/schmancy/mixins.md` documents the rewrite.
+- Register the tag in `HTMLElementTagNameMap` so consumers get TypeScript completion on `<schmancy-{name}>`.
+- Export through `src/{name}/index.ts` and surface from `src/index.ts`.
 
-### Inline SCSS Import
-```typescript
-import style from './component.scss?inline'
-export class Component extends $LitElement(style) {}
-```
-- Components with complex styling use `.scss` files
-- Simple components use inline CSS template literals
-- All Tailwind classes work via TailwindMixin in base
+### Styling
 
-### Tailwind Integration
-- Theme CSS variables: `--schmancy-sys-color-{path}`
-- Tailwind config maps to theme tokens
-- Use Tailwind utility classes directly in templates
+Two patterns, both end up in `static styles`:
 
-## State Management
-
-### RxJS Patterns
 ```typescript
-// Subject for internal state
-private _value$ = new BehaviorSubject<T>(initial)
+// Simple: inline css template literal
+static styles = [css`:host { display: block }`]
 
-// Combine streams and auto-cleanup
-combineLatest([stream1$, stream2$])
-  .pipe(takeUntil(this.disconnecting))
-  .subscribe(...)
+// Complex: external SCSS via Vite ?inline import
+import style from './component.scss?inline'
+static styles = [unsafeCSS(style)]   // unsafeCSS converts the string → CSSResult
 ```
 
-### Property Binding with Display Sync
-For form components (select, autocomplete, chips):
-1. Track explicit property setting with flags: `_valueSet`, `_valuesSet`
-2. Implement `_updateInputDisplay()` to sync label with value
-3. Call in `firstUpdated()` for initial sync
-4. Call when value changes programmatically
+Tailwind utilities work in templates without import — `SchmancyElement`
+injects the project Tailwind sheet into every shadow root. `static
+styles` only carries component-local CSS.
 
-### Context/Store Pattern
-```typescript
-// Create typed context
-const Context = createContext<T>(initial, 'local|memory|indexeddb', 'key')
-
-// Use in component
-@select(Context)
-property!: T
-
-// Or create compound selectors
-const selector = createCompoundSelector(
-  [Context1, Context2],
-  [a => a.field, b => b.field],
-  (val1, val2) => ({ combined: val1 + val2 })
-)
-```
+### Slot content processing
 
-## Event Patterns
+Components that consume slotted children (select, autocomplete, chips,
+menu) use `@queryAssignedElements` and wire handlers in `firstUpdated`:
 
-### Custom Event Types
 ```typescript
-export type ComponentChangeEvent = CustomEvent<{
-  value: string
-  additionalData?: any
-}>
+@queryAssignedElements({ flatten: true })
+private _options!: SchmancyOption[]
 
-// Dispatch
-this.dispatchEvent(
-  new CustomEvent<ComponentChangeEvent['detail']>('change', {
-    detail: { value: this.value },
-    bubbles: true,
-    composed: true,
+firstUpdated() {
+  this._options.forEach((option, index) => {
+    option.tabIndex = -1
+    if (!option.id) option.id = `${this.id}-option-${index}`
   })
-)
-```
-
-### Discovery Events
-Components respond to `{tag}-where-are-you` by emitting `{tag}-here-i-am` with self reference.
-
-## Accessibility Patterns
-
-### Form Components
-```typescript
-// ARIA attributes
-role="combobox"
-aria-haspopup="listbox"
-aria-expanded=${this._open}
-aria-controls="listbox-id"
-
-// Screen reader announcements
-private _announceToScreenReader(message: string) {
-  const liveRegion = this.shadowRoot?.querySelector('#live-status')
-  if (liveRegion) liveRegion.textContent = message
 }
-
-// Live region in template
-<div id="live-status" role="status" aria-live="polite" class="sr-only"></div>
-```
-
-### Focus Management
-```typescript
-protected static shadowRootOptions = {
-  ...LitElement.shadowRootOptions,
-  mode: 'open',
-  delegatesFocus: true, // Auto-focus first focusable element
-}
-```
-
-## Lit Directives - Complete Reference
-
-### Core Principles
-- Import only directives you use (modular design prevents bundle bloat)
-- Directives are functions that customize rendering behavior
-- Each directive is a separate module from `lit/directives/`
-
-### Conditional Rendering Directives
-
-**`when(condition, trueCase, falseCase?)`** - Best for clean inline conditionals
-```typescript
-import { when } from 'lit/directives/when.js'
-${when(this.isExpanded, () => html`<div>Content</div>`, () => html`<div>Summary</div>`)}
-```
-- Cleaner than ternary operators
-- Lazy evaluation of templates
-- Use when readability matters
-
-**`choose(value, cases, default?)`** - Template-level switch statement
-```typescript
-import { choose } from 'lit/directives/choose.js'
-${choose(this.state, [
-  ['loading', () => html`<spinner></spinner>`],
-  ['error', () => html`<error-msg></error-msg>`],
-  ['success', () => html`<content></content>`]
-])}
-```
-- Strict equality matching
-- Better than nested ternaries
-
-**`ifDefined(value)`** - Conditional attributes
-```typescript
-import { ifDefined } from 'lit/directives/if-defined.js'
-<img src=${ifDefined(this.imageUrl)}>
-```
-- Sets attribute only when value is defined
-- Essential for URL attributes where undefined should prevent rendering
-
-### List Rendering Directives
-
-**`repeat(items, keyFn?, templateFn)`** - **USE THIS FOR ALL LISTS**
-```typescript
-import { repeat } from 'lit/directives/repeat.js'
-${repeat(
-  this.items,
-  (item) => item.id,  // Key function for DOM stability
-  (item, index) => html`<div>${item.name}</div>`
-)}
-```
-- **MANDATORY for Schmancy**: Enables DOM diffing and stability
-- Maintains DOM node association during list updates
-- Most efficient for insertions/removals/reordering
-- Prevents unnecessary re-renders
-
-**`map(items, templateFn)`** - Simple iteration (use sparingly)
-```typescript
-import { map } from 'lit/directives/map.js'
-${map(this.items, (item) => html`<div>${item}</div>`)}
-```
-- Smaller and faster than repeat, but NO keying
-- Use ONLY when list never changes order
-- Prefer `repeat` in 99% of cases
-
-**`join(items, joiner)`** - Interleave with separator
-```typescript
-import { join } from 'lit/directives/join.js'
-${join(this.tags.map(t => html`<span>${t}</span>`), html`, `)}
-```
-
-**`range(start, end?, step?)`** - Sequential integers
-```typescript
-import { range } from 'lit/directives/range.js'
-${map(range(5), i => html`<item>${i}</item>`)}
-```
-
-### Performance Optimization Directives
-
-**`cache(value)`** - **CRITICAL FOR TEMPLATE SWITCHING**
-```typescript
-import { cache } from 'lit/directives/cache.js'
-${cache(
-  this.view === 'detail'
-    ? html`<detail-view>${content}</detail-view>`
-    : html`<summary-view>${summary}</summary-view>`
-)}
-```
-- Preserves DOM nodes when switching between templates
-- Avoids re-creation costs for large, complex templates
-- **USE WHEN:** Frequently toggling between views
-- **AVOID WHEN:** Templates are simple or rarely toggle
-- **PITFALL:** Cached DOM retains internal state (form values, scroll position)
-- **WITH REFS:** Refs remain valid across switches since DOM is preserved
-- **MEMORY:** Trades memory for rendering speed
-
-**`guard(dependencies, valueFn)`** - Prevents unnecessary computation
-```typescript
-import { guard } from 'lit/directives/guard.js'
-${guard([this.data], () => this.expensiveCalculation(this.data))}
-```
-- Only re-runs when dependency **identity** changes
-- Perfect for immutable data patterns
-- Implements memoization at template level
-- Use for expensive calculations, transformations, hashing
-
-**`keyed(key, value)`** - Forces DOM recreation on key change
-```typescript
-import { keyed } from 'lit/directives/keyed.js'
-${keyed(this.userId, html`<user-profile .user=${this.user}></user-profile>`)}
-```
-- Removes old DOM before rendering new value
-- Useful for clearing element state or resetting animations
-- Opposite of cache - forces fresh DOM
-
-### DOM Reference Directives
-
-**`ref(refObject)`** - Access rendered elements
-```typescript
-import { createRef, ref, Ref } from 'lit/directives/ref.js'
-private containerRef: Ref<HTMLDivElement> = createRef()
-
-// In template
-<div ${ref(this.containerRef)}></div>
-
-// Access via
-this.containerRef.value?.focus()
 ```
-- Enables imperative DOM manipulation
-- Use for focus management, third-party library integration
-- Callback form available: `ref((el) => { /* use el */ })`
-
-### State Synchronization Directives
 
-**`live(value)`** - Compares against live DOM value
-```typescript
-import { live } from 'lit/directives/live.js'
-<input .value=${live(this.value)}>
-```
-- Critical for input elements that modify their own state
-- Compares against actual DOM value, not last-rendered value
-- Use with strict equality checks
-- Essential for contenteditable or custom elements with external state
+### RxJS internals
 
-### Asynchronous Rendering Directives
+Long-lived component state is a `BehaviorSubject` plus a derived stream:
 
-**`until(...values)`** - Renders while promises resolve
 ```typescript
-import { until } from 'lit/directives/until.js'
-${until(
-  fetch('/api/data').then(r => r.json()),
-  html`<spinner></spinner>` // Placeholder
-)}
-```
-- Highest-priority promises render on resolution
-- Lower-priority values show during pending states
+private _value$ = new BehaviorSubject<T>(initial)
 
-**`asyncAppend(asyncIterable)`** - Append values as they yield
-```typescript
-import { asyncAppend } from 'lit/directives/async-append.js'
-${asyncAppend(this.streamData(), (item) => html`<div>${item}</div>`)}
+connectedCallback() {
+  super.connectedCallback()
+  combineLatest([this._value$, this._open$])
+    .pipe(takeUntil(this.disconnecting))
+    .subscribe(([value, open]) => { /* … */ })
+}
 ```
 
-**`asyncReplace(asyncIterable)`** - Replace with each new value
-```typescript
-import { asyncReplace } from 'lit/directives/async-replace.js'
-${asyncReplace(this.counter(), (count) => html`<div>${count}</div>`)}
-```
+- Every subscription ends with `.pipe(takeUntil(this.disconnecting))`.
+- Form components (`select`, `autocomplete`, `chips`) track explicit
+  property assignment with flags (`_valueSet`, `_valuesSet`) and
+  resync the visible label via `_updateInputDisplay()` in
+  `firstUpdated()` and on every programmatic value change.
 
-### Unsafe Content Directives (Use with Caution)
+### Custom events
 
-**`unsafeHTML(string)`** - Render trusted HTML strings
-```typescript
-import { unsafeHTML } from 'lit/directives/unsafe-html.js'
-${unsafeHTML(this.trustedContent)}
-```
-- **ONLY for developer-controlled content**
-- Enables XSS, CSS injection if misused
-- Use for database-stored HTML from trusted sources
+Type the detail and dispatch with `bubbles: true, composed: true`:
 
-**`unsafeSVG(string)`** - Render trusted SVG strings
 ```typescript
-import { unsafeSVG } from 'lit/directives/unsafe-svg.js'
-${unsafeSVG(this.svgContent)}
-```
-- Same security constraints as unsafeHTML
+export type SchmancyChangeEvent = CustomEvent<{ value: string }>
 
-**`templateContent(templateElement)`** - Clone from template elements
-```typescript
-import { templateContent } from 'lit/directives/template-content.js'
-${templateContent(this.shadowRoot.querySelector('template'))}
+this.dispatchEvent(
+  new CustomEvent<SchmancyChangeEvent['detail']>('change', {
+    detail: { value: this.value },
+    bubbles: true,
+    composed: true,
+  }),
+)
 ```
 
-### Schmancy Best Practices
+### Accessibility
 
-1. **Always use `repeat` with key functions** for lists - prevents bugs and improves performance
-2. **Use `cache` for view switching** (expanded/minimized, tabs, modals)
-3. **Apply `guard` with immutable data** for expensive transformations
-4. **Use `when` over ternaries** for readability
-5. **Use `ref` for animations** and imperative DOM access
-6. **Combine `cache` + `ref` carefully** - refs stay valid, but ensure proper lifecycle
-7. **Use `live` for form inputs** that modify themselves
-8. **Avoid `map`** unless you're certain list order never changes
-
-### Common Patterns in Schmancy
-
-**List with stable DOM:**
-```typescript
-${repeat(
-  this.employees,
-  (e) => e.id,
-  (e, i) => html`<employee-card .employee=${e}></employee-card>`
-)}
-```
+Form components carry the ARIA combobox pattern (`role="combobox"`,
+`aria-haspopup="listbox"`, `aria-expanded`, `aria-controls`) and a
+visually-hidden live region for status announcements:
 
-**Expensive calculation with caching:**
-```typescript
-${guard([this.data], () => this.calculateComplexStats(this.data))}
+```html
+<div id="live-status" role="status" aria-live="polite" class="sr-only"></div>
 ```
 
-**View switching with cache:**
-```typescript
-${cache(
-  this.isExpanded
-    ? html`<expanded-content ${ref(this.contentRef)}></expanded-content>`
-    : html``
-)}
-```
+Use `delegatesFocus: true` in `shadowRootOptions` for components whose
+internal first-focusable element should receive focus when the host
+does:
 
-**Animation target with ref:**
 ```typescript
-private iconRef: Ref<HTMLElement> = createRef()
-<schmancy-icon ${ref(this.iconRef)}>close</schmancy-icon>
-// Later: this.iconRef.value?.animate(...)
+protected static shadowRootOptions = {
+  ...LitElement.shadowRootOptions,
+  mode: 'open',
+  delegatesFocus: true,
+}
 ```
 
-## Common Utilities
+### State within a component
 
-### Slot Content Processing
-```typescript
-@queryAssignedElements({ flatten: true })
-private _options!: SchmancyOption[]
+Module-scoped reactive state lives on `state(...)` from
+`@mhmo91/schmancy/state` — see `skills/schmancy/state.md`. Inside a
+component instance, use `@state` (Lit) for private template-driving
+fields and `@property` for public attributes. There is no
+`createContext` / `@select` / `createCompoundSelector`; those v1 APIs
+were removed and replaced wholesale by `state()` / `@observe` /
+`computed`. The migration cheatsheet is `src/state/MIGRATION.md`.
 
-// Setup handlers in firstUpdated()
-this._options.forEach((option, index) => {
-  option.tabIndex = -1
-  if (!option.id) option.id = `${this.id}-option-${index}`
-  // Add event listeners
-})
-```
-
-### Debouncing & Filtering
-```typescript
-this._inputValue$.pipe(
-  distinctUntilChanged(),
-  debounceTime(this.debounceMs),
-  tap(value => this._handleChange(value)),
-  takeUntil(this.disconnecting)
-).subscribe()
-```
+### Theme consumption
 
-## Theme Integration
+Components that need theme tokens consume the Lit context:
 
-Components consuming theme:
 ```typescript
 @consume({ context: themeContext })
 theme!: Partial<TSchmancyTheme>
 ```
 
-Theme CSS custom properties are auto-generated from theme object structure as `--schmancy-{path}`.
+Theme CSS variables are auto-generated as `--schmancy-{path}`. Prefer
+the Tailwind shortcut utilities (`bg-surface-default`,
+`text-error-default`, `border-outline-variant`) over raw
+`var(--schmancy-sys-color-X)` references — the token map lives in
+`skills/schmancy/theme.md § Tailwind utilities`.
 
-## Area Router (Navigation)
+## Validation patterns (form components)
 
-```typescript
-// Navigate programmatically
-area.push({
-  area: 'main',
-  component: MyComponent,
-  params?: { id: '123' }
-})
-
-// Lazy load
-const LazyComponent = lazy(() => import('./component'))
-```
-
-## Testing Helpers
-
-### Value Validation
 ```typescript
 public checkValidity(): boolean {
   if (!this.required) return true
@@ -426,3 +178,9 @@ public reportValidity(): boolean {
   return this._inputElementRef.value?.reportValidity() ?? this.checkValidity()
 }
 ```
+
+## Pointers
+
+- **State module brief:** `src/state/CLAUDE.md` — invariants for code under `src/state/`.
+- **Migration off v1 contexts:** `src/state/MIGRATION.md`.
+- **Lab acceptance criterion:** `lab/README.md` — what does and doesn't belong in `@mhmo91/schmancy-lab`.

package/src/state/CLAUDE.md

@@ -19,7 +19,7 @@ A reactive state primitive for the schmancy library:
   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.
+  `SchmancyElement` subclass.
 - `stateFromObservable(observable, namespace, initial)` — bridges an
   RxJS source into a `state()`.
 
@@ -28,13 +28,13 @@ type exports.
 
 ## Default subscription pattern
 
-`$LitElement()` already composes `SignalWatcher` over its mixin chain.
+`SchmancyElement` 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() {
+class CartView extends SchmancyElement {
   render() { return html`Items: ${cart.value.items.length}` }
 }
 ```
@@ -59,25 +59,33 @@ the element auto-resolve to a per-element isolated copy via the
 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
+  patch + `_publishEventHost(node)` slot + `resolveActiveHost()`
+  4-tier fallback (stack → event-host slot → `document.activeElement`
+  → undefined). Hand-rolled TC39 AsyncContext.Variable polyfill
+  (~30 lines for the Promise patch alone). 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.
+  disconnect. Also installs capture-phase listeners on itself for
+  ~18 common event types and calls `_publishEventHost(target)` from
+  each — that's how inline arrow handlers attached to descendants
+  resolve to the closest enclosing context.
+
+`mixins/SchmancyElement.ts` carries the host-side integration points:
+prototype-chain wrap of every concrete subclass at first construction
+(caches in a `WeakSet`), and `addEventListener` / `removeEventListener`
+overrides that wrap host listeners.
+
+**Known limitation — native `await`.** 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 of an
+`await` on a native Promise. Class methods that mutate state across an
+`await` boundary fall back to the module-scoped global. To preserve
+the host across awaits, keep the mutation in the synchronous prelude
+before the first `await`, or chain explicitly with `.then(...)`.
 
 ## Rules for code in this directory