@mhmo91/schmancy 0.9.3 → 0.9.5

package/ai/mixins.md

@@ -1,201 +0,0 @@
-# $LitElement — Base Class Foundation
-
-> **Every Schmancy component extends `$LitElement`. No exceptions.**
-> It wires RxJS cleanup, Tailwind, cross-shadow discovery, and a few quality-of-life helpers into every element — so you never write that plumbing yourself.
-
-## The minimal component
-
-```typescript
-import { $LitElement } from '@mhmo91/schmancy/mixins'
-import { customElement } from 'lit/decorators.js'
-import { css, html } from 'lit'
-
-@customElement('my-card')
-class MyCard extends $LitElement(css`
-  :host { display: block; }
-`) {
-  render() {
-    return html`<slot></slot>`
-  }
-}
-```
-
-That's it. You now get the five things below for free.
-
-## What `$LitElement` gives you
-
-### 1. `disconnecting` — automatic RxJS cleanup
-```typescript
-connectedCallback() {
-  super.connectedCallback()
-
-  userContext.$.pipe(
-    takeUntil(this.disconnecting),
-  ).subscribe(user => this.user = user)
-}
-```
-
-`disconnecting` is a `Subject<void>` that emits once when the element is detached from the DOM. Paired with `takeUntil`, it makes the entire Schmancy codebase manual-unsubscribe-free.
-
-**This is the single most-used line in a Schmancy app.** If you see an RxJS pipe without `takeUntil(this.disconnecting)` — it's a leak.
-
-### 2. `classMap(obj)` — space-splitting enhanced
-```typescript
-render() {
-  return html`
-    <div class=${this.classMap({
-      'flex items-center gap-2': true,
-      'bg-primary-default': this.active,
-      'opacity-50 pointer-events-none': this.disabled,
-    })}>
-      …
-    </div>
-  `
-}
-```
-
-Unlike standard Lit `classMap`, keys can be **space-separated** ("flex items-center gap-2"). Combined with Tailwind, you write natural class strings instead of one-class-per-key.
-
-**Hard rule:** `class=${this.classMap(...)}` must be the *sole* expression in `class=`. You cannot mix it with string interpolation (` class="foo ${this.classMap(...)}"`) — Lit will fail silently.
-
-### 3. `styleMap(obj)` — inline styles (passthrough)
-```typescript
-render() {
-  return html`
-    <div style=${this.styleMap({
-      width: `${this.size}px`,
-      opacity: this.visible ? 1 : 0,
-    })}></div>
-  `
-}
-```
-
-Direct passthrough to Lit's `styleMap` directive, exposed as a method so you don't have to import it in every component.
-
-### 4. `discover<T>(tag)` — cross-shadow component lookup
-```typescript
-connectedCallback() {
-  super.connectedCallback()
-
-  this.discover<SchmancyDialog>('schmancy-dialog').pipe(
-    takeUntil(this.disconnecting),
-  ).subscribe(dialog => dialog?.setDefaultAction('confirm'))
-}
-```
-
-Broadcasts a `{tag}-where-are-you` event. Any mounted `$LitElement` with that tag responds with itself. Works **across shadow DOM boundaries** — zero traversal.
-
-### 5. Auto-response to discovery events
-Every `$LitElement` automatically answers `{its-tag}-where-are-you` by dispatching `{its-tag}-here-i-am` with `{ detail: { component: this } }`. You opt in by extending — opt out by not.
-
-## Tailwind support
-
-Styles you import are pre-processed through the Schmancy Tailwind pipeline. Tailwind utility classes work in both the host and slotted content. All theme CSS variables (`--schmancy-sys-color-primary-default`, etc.) resolve inside the component's shadow root.
-
-```typescript
-// Works out of the box
-render() {
-  return html`<div class="flex items-center gap-2 text-primary-default">…</div>`
-}
-```
-
-## Extending with SCSS
-
-For complex styling, import a `.scss?inline` file and pass it to `$LitElement`:
-
-```typescript
-import style from './my-card.scss?inline'
-
-@customElement('my-card')
-class MyCard extends $LitElement(style) {
-  // SCSS features: nesting, mixins, @layer
-}
-```
-
-Simple components use template-literal CSS; complex ones use SCSS.
-
-## Standard component shape
-
-This is the skeleton 90% of Schmancy components follow:
-
-```typescript
-import { $LitElement } from '@mhmo91/schmancy/mixins'
-import { css, html } from 'lit'
-import { customElement, property, state } from 'lit/decorators.js'
-import { Subject, takeUntil } from 'rxjs'
-
-@customElement('my-component')
-export class MyComponent extends $LitElement(css`
-  :host { display: block; }
-`) {
-  // 1. Public API — reflected / typed
-  @property({ type: String, reflect: true }) variant: 'a' | 'b' = 'a'
-  @property({ type: Boolean, reflect: true }) disabled = false
-
-  // 2. Internal state
-  @state() private _open = false
-
-  // 3. Private RxJS subjects (if needed)
-  private _value$ = new Subject<string>()
-
-  // 4. Lifecycle
-  connectedCallback() {
-    super.connectedCallback()
-    this._value$.pipe(
-      debounceTime(150),
-      takeUntil(this.disconnecting),
-    ).subscribe(v => this.handleValue(v))
-  }
-
-  // 5. Rendering
-  render() {
-    return html`
-      <div class=${this.classMap({
-        'flex items-center': true,
-        'opacity-50': this.disabled,
-      })}>
-        <slot></slot>
-      </div>
-    `
-  }
-
-  // 6. Public imperative API (if any)
-  public open() { this._open = true }
-}
-
-declare global {
-  interface HTMLElementTagNameMap {
-    'my-component': MyComponent
-  }
-}
-```
-
-Guarantees from this shape:
-- Every subscription dies with the element.
-- Tailwind + theme tokens work.
-- Component is discoverable from anywhere via `discover('my-component')`.
-- Declared in the global tag map for TypeScript.
-
-## Why not `LitElement` directly?
-
-You can, but you'll re-implement:
-- Manual unsubscribe handling in `disconnectedCallback` for every `Observable`.
-- `classMap` space-splitting.
-- Tailwind variable wiring.
-- Cross-shadow discovery.
-
-`$LitElement` is 200 lines of common-denominator plumbing that keeps apps consistent. Using it is the convention; not using it is the outlier.
-
-## Rules
-
-1. **Every custom element extends `$LitElement(style?)`.**
-2. **Every RxJS subscription ends with `.pipe(takeUntil(this.disconnecting))`** — or you have a leak.
-3. **Call `super.connectedCallback()` and `super.disconnectedCallback()`** when you override them.
-4. **Don't mix `classMap` with string interpolation** in the same attribute.
-5. **Prefer `ref(createRef())` over `querySelector`** for your own shadow tree.
-6. **Register in `HTMLElementTagNameMap`** for TypeScript autocompletion.
-
-## See also
-- [store](./store.md) — contexts pair with `takeUntil(this.disconnecting)` for auto-cleaning subscriptions.
-- [area](./area.md) — route components all extend `$LitElement`.
-- [discovery](./discovery.md) — the discovery events `$LitElement` handles automatically.

package/ai/store.md

@@ -1,192 +0,0 @@
-# Store — State Foundation
-
-> **Not a utility. The state backbone of a Schmancy app.**
-> `createContext` + `@select` replaces Redux, Zustand, and a route-scoped cache without ceremony.
-
-A real app runs *many* small contexts — not one monolith. Typical production apps sit around 8–10:
-
-```
-userContext          ('local')      — signed-in user (persists across sessions)
-organizationContext  ('local')      — current org
-appStateContext      ('local')      — core app state (lists, selections, flags)
-agentsContext        ('memory')     — fetched data (re-fetched on reload)
-contactsContext      ('memory')     — Map<id, Contact> — mass data
-templatesContext     ('memory')     — list fetched from server
-currentTemplateIdCtx ('local')      — small pointer ref that persists
-composeContext       ('local')      — draft form state
-draftCtx             ('session')    — per-thread chat input (tab-scoped)
-strictCtx            ('session')    — per-thread toggles (tab-scoped)
-```
-
-**Split by persistence tier + lifetime**, not by feature area. Per-component ephemeral state → `session`. Cached fetches → `memory`. User-saved preferences → `local`. Large cached data → `indexeddb`.
-
-## Creating a context
-
-```typescript
-import { createContext } from '@mhmo91/schmancy'
-
-// Object store — persisted to localStorage
-export const userContext = createContext<User>(new User(), 'local', 'user')
-
-// Collection store — Map keyed by id
-export const contactsContext = createContext<Map<string, Contact>>(new Map(), 'memory', 'contacts')
-
-// Array store — ordered list
-export const tagsContext = createContext<string[]>([], 'memory', 'tags')
-
-// Session-scoped (per browser tab)
-export const draftContext = createContext<{ text: string }>({ text: '' }, 'session', 'compose-draft')
-```
-
-### Storage tiers
-
-| Mode | Backing | Survives refresh? | Survives tab close? | Size |
-|------|---------|-------------------|---------------------|------|
-| `'memory'` | JS heap | ❌ | ❌ | small |
-| `'session'` | `sessionStorage` | ✅ | ❌ (per-tab) | ~5 MB |
-| `'local'` | `localStorage` | ✅ | ✅ | ~5 MB |
-| `'indexeddb'` | IndexedDB | ✅ | ✅ | GB |
-
-Rule of thumb:
-- **User session data, prefs, drafts meant to persist** → `'local'`
-- **Per-tab ephemeral data** (wizard progress, per-thread drafts) → `'session'`
-- **Fetched from API, regenerable** → `'memory'`
-- **Large arrays, file-like data, offline-first** → `'indexeddb'`
-
-## Reading with `@select`
-
-```typescript
-import { select } from '@mhmo91/schmancy'
-
-@customElement('user-card')
-class UserCard extends $LitElement() {
-  // Auto-subscribes, re-renders on change
-  @select(userContext) user!: User
-
-  // Selector function narrows the dependency
-  @select(contactsContext, m => m.size) contactCount!: number
-
-  // Collection → stays as Map
-  @select(contactsContext) contacts!: Map<string, Contact>
-}
-```
-
-`@select` options:
-- `required` (default `true`) — wait for context `.ready` before `connectedCallback` completes.
-- `updateOnly` — only call `requestUpdate`, don't assign. Use when you read the value imperatively.
-- `deepClone` — `structuredClone` the value to prevent accidental mutation.
-- `debug` — log every emission.
-
-### Pick one item from a collection
-```typescript
-@selectItem(contactsContext, component => component.contactId)
-contact!: Contact | undefined
-```
-
-Use this on components that carry the key as a property (e.g. `this.contactId`) — avoids reading the whole map.
-
-## Writing state
-
-### Object store
-```typescript
-userContext.set({ name: 'Alice', email: 'alice@test.com' })
-userContext.set({ ...userContext.value, name: 'Bob' })  // partial update pattern
-```
-
-### Collection (Map) store
-```typescript
-contactsContext.set('id-1', { id: 'id-1', name: 'Alice' })
-contactsContext.delete('id-1')
-contactsContext.replace(new Map([/* fresh batch */]))
-```
-
-### Array store
-```typescript
-tagsContext.push('new-tag')
-tagsContext.replace(['a', 'b', 'c'])
-```
-
-## Observable API
-
-```typescript
-connectedCallback() {
-  super.connectedCallback()
-
-  userContext.$.pipe(
-    filter(() => userContext.ready),               // gate on initialization
-    distinctUntilChanged((a, b) => a.id === b.id), // ignore unrelated writes
-    switchMap(user => this.loadForUser(user)),     // cascade load
-    takeUntil(this.disconnecting),                 // cleanup
-  ).subscribe(data => this.data = data)
-}
-```
-
-- **`ctx.$`** — a `BehaviorSubject`. Use for chained transforms.
-- **`ctx.value`** — synchronous snapshot.
-- **`ctx.ready`** — boolean; becomes `true` after the backing store has loaded.
-
-### The gating pattern
-Every non-trivial subscription starts with `filter(() => ctx.ready)`. When your context is backed by `indexeddb` or re-hydrated from `localStorage`, the initial default value is emitted before the real stored value lands. Gate on `.ready` to skip the default.
-
-## Dynamic contexts (per-instance)
-
-For per-component ephemeral state that still benefits from persistence, instantiate the context **inside** `connectedCallback` with an instance-specific key:
-
-```typescript
-import { createContext, IStore } from '@mhmo91/schmancy'
-
-@customElement('chat-input')
-class ChatInput extends $LitElement() {
-  @property() draftKey?: string
-
-  private draftCtx: IStore<{ text: string }> | null = null
-
-  connectedCallback() {
-    super.connectedCallback()
-
-    if (this.draftKey) {
-      this.draftCtx = createContext<{ text: string }>(
-        { text: '' },
-        'session',
-        this.draftKey,          // e.g. `chat-draft-${threadId}`
-      )
-
-      // Hydrate once
-      this.draftCtx.$.pipe(
-        filter(() => this.draftCtx!.ready),
-        take(1),
-        tap(v => { this.text = v.text }),
-      ).subscribe()
-    }
-  }
-
-  private onInput(v: string) {
-    this.text = v
-    this.draftCtx?.set({ text: v })
-  }
-}
-```
-
-This is the pattern for *every* "draft that persists until sent" input.
-
-## Architectural rules
-
-1. **Declare contexts at module scope**, not inside classes — except dynamic per-instance ones.
-2. **Name the storage key** even for `'memory'` contexts — it helps debugging.
-3. **Keep each context small and single-purpose**. 9 small contexts beat 1 god context.
-4. **Subscribe with `takeUntil(this.disconnecting)`** — every time, no exceptions.
-5. **Gate on `.ready`** before any async cascading work.
-6. **Only the owning component writes**. Everyone else reads via `@select`.
-7. **Don't put functions, observables, or class instances into context** — only plain serializable data (for `'local'` / `'session'` / `'indexeddb'`).
-
-## Anti-patterns
-
-- ❌ Storing Promises in context. Use `memory` contexts for cached fetch *results*, not the in-flight Promise.
-- ❌ Cross-writing: component A writes to context X which is "owned" by component B. Centralize writes.
-- ❌ One monolithic `appContext` holding everything. You lose `distinctUntilChanged` granularity.
-- ❌ Forgetting `.ready` — causes double-fires on load with stale default values.
-- ❌ Using `'local'` for large blobs — hits quota, blocks the main thread on stringify/parse.
-
-## See also
-- [mixins](./mixins.md) — `$LitElement` provides `disconnecting` for every subscription.
-- [area](./area.md) — routing + contexts compose naturally (guards read context state).