@mhmo91/schmancy 0.9.3 → 0.9.5

package/dist/skills/schmancy/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: schmancy
+description: UI patterns, component APIs, and conventions for the @mhmo91/schmancy web-component library (Lit + RxJS + Tailwind). Activate whenever the user works on any <schmancy-*> tag, routing with schmancy-area, state with createContext/@select, the $LitElement base class, theme, directives, or overlay services ($dialog, $notify, schmancyContentDrawer, sheet).
+---
+
+# Schmancy
+
+Web-component UI library on Lit + RxJS + Tailwind CSS. This skill bundles the full library reference as supporting files alongside this SKILL.md.
+
+## How to use this skill
+
+All reference files live in this directory. Read by filename.
+
+1. **Start with `INDEX.md`** for the full catalog organized by job (foundations / atoms / forms / navigation / overlays / interaction / feedback / display).
+2. **Before writing any `<schmancy-X>` tag**, read `X.md`. Example: `<schmancy-button>` → `button.md`.
+3. **Before editing foundations** (routing, state, base class, theme), read the matching foundation file below.
+4. **Apply the conventions** at the end of this file.
+
+## Foundations (the framework pieces — touch first)
+
+| Piece | Read |
+|-------|------|
+| Routing (`<schmancy-area>`, `<schmancy-route>`, `area.push()`, `lazy()`) | `area.md` |
+| State (`createContext`, `@select`, `@selectItem`) | `store.md` |
+| Base class (`$LitElement`) | `mixins.md` |
+| Theme (`<schmancy-theme>`, `theme` service) | `theme.md` |
+| Directives (`magnetic`, `cursorGlow`, `gravity`, `reveal`, `animateText`, …) | `directives.md` |
+| Spring physics presets | `animation.md` |
+
+## Overlay services (prefer over tags)
+
+For modals, toasts, sheets, side drawers — reach for the **imperative service API** first:
+
+```typescript
+import { $dialog, $notify, schmancyContentDrawer, sheet, SchmancySheetPosition } from '@mhmo91/schmancy'
+
+$dialog.component(new EditForm())                       // modal
+$dialog.component(new QuickPicker(), { position: e })    // anchored modal
+$notify.success('Saved'); $notify.error('Failed')        // toast
+schmancyContentDrawer.open({ component: new Detail() })  // side panel
+sheet.open({ component: new Picker(), position: SchmancySheetPosition.BOTTOM })  // bottom sheet
+```
+
+References: `dialog.md`, `notification.md`, `content-drawer.md`, `sheet.md`.
+
+Use component tags (`<schmancy-menu>`, `<schmancy-dropdown>`, `<schmancy-tooltip>`, `<schmancy-lightbox>`, `<schmancy-expand>`) only when the tag is the natural fit (anchored panels, tooltips, galleries).
+
+## Non-negotiable conventions
+
+**Component authoring**
+- Every component extends `$LitElement(style?)`. Never raw `LitElement`.
+- 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).
+
+**Routing**
+- Route guards are `Observable<boolean>`, never cached booleans.
+- `when="tag-name"` must exactly match `@customElement('tag-name')`.
+- Lazy-load route components: `lazy(() => import('./page'))`.
+- After auth/permission guards, use `historyStrategy: 'replace'` or `'pop'` — never `'push'`.
+
+**Templates**
+- Lists: `repeat(items, i => i.id, tpl)`. Never `.map()`.
+- View switching: `cache(...)`.
+- Expensive work: `guard([deps], () => expensive())`.
+- Conditionals: `when(...)` / `choose(...)` / `ifDefined(...)`.
+- DOM access: `ref(createRef())`.
+- `classMap(this.classMap({...}))` must be the sole expression in `class=` — never mix with string interpolation.
+
+**Styling**
+- Colors: `--schmancy-sys-color-*` CSS vars or Tailwind theme classes. Never hardcoded hex.
+- No `setTimeout` / `setInterval` / `addEventListener` — use RxJS (`timer`, `interval`, `fromEvent`).
+
+**Accessibility (combobox forms)**
+```typescript
+role="combobox"
+aria-haspopup="listbox"
+aria-expanded=${this._open}
+aria-controls="listbox-id"
+```
+Plus a live region: `<div id="live-status" role="status" aria-live="polite" class="sr-only"></div>`.
+
+## Minimal app skeleton
+
+```typescript
+<schmancy-theme root scheme="dark">
+  <schmancy-surface type="solid" fill="all">
+    <schmancy-scroll>
+      <schmancy-area
+        name="root"
+        .default=${lazy(() => import('./home.page'))}
+      >
+        <schmancy-route when="home-page"
+          .component=${lazy(() => import('./home.page'))}></schmancy-route>
+
+        <schmancy-route when="app-index"
+          .component=${lazy(() => import('./app.page'))}
+          .guard=${authState$.pipe(
+            map(u => !!u),
+            takeUntil(this.disconnecting),
+          )}
+          @redirect=${() => area.push({
+            component: 'home-page', area: 'root', historyStrategy: 'replace',
+          })}></schmancy-route>
+      </schmancy-area>
+    </schmancy-scroll>
+  </schmancy-surface>
+</schmancy-theme>
+```
+
+## Workflow
+
+1. User describes a UI task.
+2. Read `INDEX.md` to find the relevant components or foundations.
+3. Read the specific `.md` files for the APIs involved.
+4. Write code that follows the conventions above.

package/dist/skills/schmancy/area.md

@@ -0,0 +1,141 @@
+# Area — Routing
+
+Schmancy's client-side router. Three pieces:
+
+| Piece | Role |
+|-------|------|
+| `<schmancy-area name="...">` | Named region that renders one route at a time |
+| `<schmancy-route when="tag">` | Declares which component can render in an area |
+| `area.push(...)` | Imperative navigation |
+
+Areas can be nested to compose shell-plus-sub-view layouts.
+
+## Example
+
+```html
+<schmancy-area name="root" .default=${lazy(() => import('./pages/home.page'))}>
+  <schmancy-route when="home-page"
+    .component=${lazy(() => import('./pages/home.page'))}></schmancy-route>
+
+  <schmancy-route when="app-index"
+    .component=${lazy(() => import('./app/app.page'))}
+    .guard=${authState$.pipe(
+      map(u => !!u && !u.isAnonymous),
+      takeUntil(this.disconnecting),
+    )}
+    @redirect=${() => area.push({
+      component: 'home-page',
+      area: 'root',
+      historyStrategy: 'replace',
+    })}></schmancy-route>
+</schmancy-area>
+```
+
+## `schmancy-area` properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | string (required) | Area identifier used in `area.push({ area })` |
+| `default` | `RouteComponent \| string` | Fallback when no route matches |
+
+## `schmancy-route` properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `when` | string (required) | Must match a `@customElement('tag')` tag name |
+| `component` | `RouteComponent` (required) | Class, tag name, or `lazy()` wrapper |
+| `guard` | `Observable<boolean>` | When emits `false`, blocks and dispatches `redirect` event |
+| `exact` | boolean | Strict-equality matching |
+
+## `area` service
+
+```typescript
+import { area } from '@mhmo91/schmancy'
+
+area.push({
+  area: 'root',
+  component: 'app-index',
+  params?: { id: '123' },
+  historyStrategy?: 'push' | 'replace' | 'silent',
+})
+```
+
+`historyStrategy`:
+- `'push'` (default) — adds a browser-history entry
+- `'replace'` — overwrites the current entry (use after guards or redirects)
+- `'silent'` — changes the area without touching history
+
+### Subscribe to route state
+
+```typescript
+area.on('root').pipe(
+  takeUntil(this.disconnecting),
+).subscribe(route => { /* route.component, route.params */ })
+
+area.params<{ id: string }>('detail').pipe(
+  takeUntil(this.disconnecting),
+).subscribe(params => this.loadItem(params.id))
+```
+
+## Lazy loading
+
+```typescript
+import { lazy } from '@mhmo91/schmancy'
+const HomePage = lazy(() => import('./home.page'))
+
+// Optional preload
+html`<button @mouseenter=${() => HomePage.preload()}>Home</button>`
+```
+
+## Guards
+
+`guard` is an Observable<boolean>.
+
+- Emits `true` → route renders.
+- Emits `false` → route dispatches a `redirect` event. Handle it with `area.push(...)`.
+
+Auth guard:
+
+```typescript
+<schmancy-route when="app-index"
+  .component=${lazy(() => import('./app'))}
+  .guard=${authState$.pipe(
+    map(u => !!u),
+    takeUntil(this.disconnecting),
+  )}
+  @redirect=${() => area.push({
+    component: 'home-page', area: 'root', historyStrategy: 'replace',
+  })}></schmancy-route>
+```
+
+Compound guard (multiple streams):
+
+```typescript
+.guard=${combineLatest([permissions$, orgContext.$]).pipe(
+  takeUntil(this.disconnecting),
+  map(([perms, org]) => perms.includes('billing.view') && org?.billing?.configured),
+)}
+```
+
+## Nested areas
+
+Areas nest by rendering an inner `<schmancy-area>` inside a route component. A common shape is an outer area for "signed-in vs. not" and an inner area for sub-views of the signed-in shell.
+
+```html
+<!-- outer -->
+<schmancy-area name="root">
+  <schmancy-route when="app-index" .component=${AppShell}></schmancy-route>
+</schmancy-area>
+
+<!-- inner (inside AppShell.render()) -->
+<schmancy-area name="app" default="home-page">
+  <schmancy-route when="home-page" .component=${...}></schmancy-route>
+  <schmancy-route when="settings-page" .component=${...}></schmancy-route>
+</schmancy-area>
+```
+
+## Rules
+
+- `when="tag-name"` must match `@customElement('tag-name')` exactly.
+- Guards emit `false` → always use `historyStrategy: 'replace'` in the `@redirect` handler.
+- Every subscription in guards / route state uses `takeUntil(this.disconnecting)`.

package/dist/{ai → skills/schmancy}/mailbox.md

@@ -1,6 +1,6 @@
 # Schmancy Mailbox
 
-> Full email composition + campaign management system. Orchestrates recipients, templates, editor, attachments, and preview. Extracted from funkhaus-events and generalized.
+> Full email composition + campaign management system. Orchestrates recipients, templates, editor, attachments, and preview.
 
 ## Components
 

package/dist/skills/schmancy/mixins.md

@@ -0,0 +1,99 @@
+# `$LitElement`
+
+Base class for Schmancy components. Extends `LitElement` with RxJS cleanup, Tailwind support, and cross-shadow discovery.
+
+## Usage
+
+```typescript
+import { $LitElement } from '@mhmo91/schmancy/mixins'
+import { customElement } from 'lit/decorators.js'
+import { css, html } from 'lit'
+
+@customElement('my-component')
+class MyComponent extends $LitElement(css`
+  :host { display: block; }
+`) {
+  render() {
+    return html`<slot></slot>`
+  }
+}
+```
+
+`$LitElement(style?)` accepts either a Lit `css` tagged literal or a string (e.g. SCSS imported with `?inline`).
+
+## Provided members
+
+### `disconnecting: Subject<void>`
+Emits once when the element disconnects. Pair with `takeUntil` for cleanup:
+
+```typescript
+connectedCallback() {
+  super.connectedCallback()
+  someObservable$.pipe(
+    takeUntil(this.disconnecting),
+  ).subscribe()
+}
+```
+
+### `classMap(obj)`
+Wraps Lit's `classMap` so keys can be space-separated:
+
+```typescript
+html`<div class=${this.classMap({
+  'flex items-center gap-2': true,
+  'opacity-50': this.disabled,
+})}></div>`
+```
+
+Must be the only expression in `class=` — don't mix with string interpolation.
+
+### `styleMap(obj)`
+Passthrough to Lit's `styleMap`.
+
+```typescript
+html`<div style=${this.styleMap({ width: `${w}px` })}></div>`
+```
+
+### `discover<T>(tag): Observable<T | null>`
+Find another Schmancy component by tag via event-based handshake. Works across shadow DOM.
+
+```typescript
+this.discover<SchmancyDialog>('schmancy-dialog').pipe(
+  takeUntil(this.disconnecting),
+).subscribe(dialog => dialog?.setDefaultAction('confirm'))
+```
+
+### Auto-response to discovery
+Every `$LitElement` responds to `{its-tag}-where-are-you` events with `{its-tag}-here-i-am` carrying `{ detail: { component: this } }`.
+
+## Component skeleton
+
+```typescript
+@customElement('my-component')
+export class MyComponent extends $LitElement(css`:host { display: block }`) {
+  @property({ type: String, reflect: true }) variant: 'a' | 'b' = 'a'
+  @state() private _open = false
+
+  connectedCallback() {
+    super.connectedCallback()
+    // subscriptions here, with takeUntil(this.disconnecting)
+  }
+
+  render() {
+    return html`<slot></slot>`
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'my-component': MyComponent
+  }
+}
+```
+
+## Rules
+
+- Call `super.connectedCallback()` / `super.disconnectedCallback()` when overriding.
+- All RxJS subscriptions end with `.pipe(takeUntil(this.disconnecting))`.
+- Register the tag in `HTMLElementTagNameMap` for TypeScript.
+- Don't mix `classMap` with string interpolation in the same attribute.

package/dist/skills/schmancy/store.md

@@ -0,0 +1,126 @@
+# Store — Context System
+
+Reactive state management: `createContext`, `@select`, `@selectItem`.
+
+## Creating a context
+
+```typescript
+import { createContext } from '@mhmo91/schmancy'
+
+// Object
+const userContext = createContext<User>(new User(), 'local', 'user')
+
+// Map (collection)
+const itemsContext = createContext<Map<string, Item>>(new Map(), 'indexeddb', 'items')
+
+// Array
+const tagsContext = createContext<string[]>([], 'memory', 'tags')
+```
+
+Signature: `createContext(initial, storage, key)`.
+
+## Storage backends
+
+| Mode | Backing | Survives refresh | Survives tab close | Capacity |
+|------|---------|------------------|--------------------|----------|
+| `'memory'` | JS heap | ❌ | ❌ | RAM |
+| `'session'` | `sessionStorage` | ✅ | ❌ (per-tab) | ~5 MB |
+| `'local'` | `localStorage` | ✅ | ✅ | ~5 MB |
+| `'indexeddb'` | IndexedDB | ✅ | ✅ | GB |
+
+Pick by data size and lifetime:
+- User prefs, long-lived drafts → `'local'`
+- Per-tab ephemeral (cart, wizard) → `'session'`
+- Fetched from API, regenerable → `'memory'`
+- Collections with >100 entries you want cached → `'indexeddb'`
+
+## Reading with `@select`
+
+```typescript
+import { select } from '@mhmo91/schmancy'
+
+@customElement('my-component')
+class MyComponent extends $LitElement() {
+  @select(userContext) user!: User
+
+  // Selector narrows the dependency
+  @select(itemsContext, m => m.size) count!: number
+
+  @select(itemsContext) items!: Map<string, Item>
+}
+```
+
+`@select` options:
+- `required` (default `true`) — wait for `.ready` before `connectedCallback` completes.
+- `updateOnly` — call `requestUpdate` without assigning.
+- `deepClone` — `structuredClone` the value.
+- `debug` — log every emission.
+
+## `@selectItem`
+
+Pick one entry from a collection context, keyed off a component property:
+
+```typescript
+@selectItem(itemsContext, component => component.itemId)
+item!: Item | undefined
+```
+
+## Writing
+
+```typescript
+// Object
+userContext.set({ name: 'Alice' })
+userContext.set({ ...userContext.value, name: 'Bob' })
+
+// Map
+itemsContext.set('id-1', item)
+itemsContext.delete('id-1')
+itemsContext.replace(newMap)
+
+// Array
+tagsContext.push('new')
+tagsContext.replace(['a', 'b'])
+```
+
+## Observable API
+
+```typescript
+userContext.$.pipe(
+  filter(() => userContext.ready),
+  takeUntil(this.disconnecting),
+).subscribe(user => { /* ... */ })
+
+userContext.value       // synchronous snapshot
+userContext.ready       // true once the backing store has loaded
+```
+
+Gate subscriptions on `.ready` — `'local'` / `'session'` / `'indexeddb'` contexts emit their default value before the real stored value hydrates.
+
+## Dynamic contexts
+
+For per-instance state with persistence, create the context inside `connectedCallback` with an instance-scoped key:
+
+```typescript
+private draftCtx: IStore<{ text: string }> | null = null
+
+connectedCallback() {
+  super.connectedCallback()
+  if (this.draftKey) {
+    this.draftCtx = createContext<{ text: string }>(
+      { text: '' },
+      'session',
+      this.draftKey,
+    )
+  }
+}
+```
+
+## Rules
+
+- Declare contexts at module scope (except dynamic per-instance ones).
+- Name the storage key even for `'memory'` contexts — it helps debugging.
+- Keep each context single-purpose. One write shouldn't invalidate unrelated readers.
+- Only the owning component writes. Others read via `@select`.
+- Every subscription uses `takeUntil(this.disconnecting)`.
+- Gate on `.ready` before async cascading work.
+- Don't store Promises, Observables, functions, or class instances in persistent contexts.

package/dist/skills/store.md

@@ -0,0 +1,126 @@
+# Store — Context System
+
+Reactive state management: `createContext`, `@select`, `@selectItem`.
+
+## Creating a context
+
+```typescript
+import { createContext } from '@mhmo91/schmancy'
+
+// Object
+const userContext = createContext<User>(new User(), 'local', 'user')
+
+// Map (collection)
+const itemsContext = createContext<Map<string, Item>>(new Map(), 'indexeddb', 'items')
+
+// Array
+const tagsContext = createContext<string[]>([], 'memory', 'tags')
+```
+
+Signature: `createContext(initial, storage, key)`.
+
+## Storage backends
+
+| Mode | Backing | Survives refresh | Survives tab close | Capacity |
+|------|---------|------------------|--------------------|----------|
+| `'memory'` | JS heap | ❌ | ❌ | RAM |
+| `'session'` | `sessionStorage` | ✅ | ❌ (per-tab) | ~5 MB |
+| `'local'` | `localStorage` | ✅ | ✅ | ~5 MB |
+| `'indexeddb'` | IndexedDB | ✅ | ✅ | GB |
+
+Pick by data size and lifetime:
+- User prefs, long-lived drafts → `'local'`
+- Per-tab ephemeral (cart, wizard) → `'session'`
+- Fetched from API, regenerable → `'memory'`
+- Collections with >100 entries you want cached → `'indexeddb'`
+
+## Reading with `@select`
+
+```typescript
+import { select } from '@mhmo91/schmancy'
+
+@customElement('my-component')
+class MyComponent extends $LitElement() {
+  @select(userContext) user!: User
+
+  // Selector narrows the dependency
+  @select(itemsContext, m => m.size) count!: number
+
+  @select(itemsContext) items!: Map<string, Item>
+}
+```
+
+`@select` options:
+- `required` (default `true`) — wait for `.ready` before `connectedCallback` completes.
+- `updateOnly` — call `requestUpdate` without assigning.
+- `deepClone` — `structuredClone` the value.
+- `debug` — log every emission.
+
+## `@selectItem`
+
+Pick one entry from a collection context, keyed off a component property:
+
+```typescript
+@selectItem(itemsContext, component => component.itemId)
+item!: Item | undefined
+```
+
+## Writing
+
+```typescript
+// Object
+userContext.set({ name: 'Alice' })
+userContext.set({ ...userContext.value, name: 'Bob' })
+
+// Map
+itemsContext.set('id-1', item)
+itemsContext.delete('id-1')
+itemsContext.replace(newMap)
+
+// Array
+tagsContext.push('new')
+tagsContext.replace(['a', 'b'])
+```
+
+## Observable API
+
+```typescript
+userContext.$.pipe(
+  filter(() => userContext.ready),
+  takeUntil(this.disconnecting),
+).subscribe(user => { /* ... */ })
+
+userContext.value       // synchronous snapshot
+userContext.ready       // true once the backing store has loaded
+```
+
+Gate subscriptions on `.ready` — `'local'` / `'session'` / `'indexeddb'` contexts emit their default value before the real stored value hydrates.
+
+## Dynamic contexts
+
+For per-instance state with persistence, create the context inside `connectedCallback` with an instance-scoped key:
+
+```typescript
+private draftCtx: IStore<{ text: string }> | null = null
+
+connectedCallback() {
+  super.connectedCallback()
+  if (this.draftKey) {
+    this.draftCtx = createContext<{ text: string }>(
+      { text: '' },
+      'session',
+      this.draftKey,
+    )
+  }
+}
+```
+
+## Rules
+
+- Declare contexts at module scope (except dynamic per-instance ones).
+- Name the storage key even for `'memory'` contexts — it helps debugging.
+- Keep each context single-purpose. One write shouldn't invalidate unrelated readers.
+- Only the owning component writes. Others read via `@select`.
+- Every subscription uses `takeUntil(this.disconnecting)`.
+- Gate on `.ready` before async cascading work.
+- Don't store Promises, Observables, functions, or class instances in persistent contexts.

package/dist/slider.cjs

@@ -1,4 +1,4 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`}),require(`./chunk-BCfY8kxB.cjs`);const e=require(`./tailwind.mixin-DSuEu-y3.cjs`),t=require(`./litElement.mixin-BG6_-nYX.cjs`);require(`./mixins.cjs`);let n=require(`rxjs`),r=require(`rxjs/operators`),i=require(`lit/decorators.js`),a=require(`lit`),o=require(`lit/directives/cache.js`);var s=class extends t.t(a.css`
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`}),require(`./chunk-BCfY8kxB.cjs`);const e=require(`./tailwind.mixin-BF1Huas7.cjs`),t=require(`./litElement.mixin-3llHwB-8.cjs`);require(`./mixins.cjs`);let n=require(`rxjs`),r=require(`rxjs/operators`),i=require(`lit/decorators.js`),a=require(`lit`),o=require(`lit/directives/cache.js`);var s=class extends t.t(a.css`
 	:host {
 		display: block;
 		scroll-snap-align: center; /* If your slider uses scroll-snap */

package/dist/slider.js

@@ -1,5 +1,5 @@
-import { i as e } from "./tailwind.mixin-BIVhjNvD.js";
-import { t } from "./litElement.mixin-Dm-4L8zL.js";
+import { i as e } from "./tailwind.mixin-BCJOOX1_.js";
+import { t } from "./litElement.mixin-6jJYHCrZ.js";
 import "./mixins.js";
 import { fromEvent as n } from "rxjs";
 import { throttleTime as r } from "rxjs/operators";