@mhmo91/schmancy 0.9.3 → 0.9.4

package/ai/area.md

@@ -1,215 +1,141 @@
-# Area — Routing Foundation
+# Area — Routing
 
-> **Not just a component. The routing framework your app runs on.**
-> `area` is the imperative API. `schmancy-area` is the region where a component lives. `schmancy-route` declares the options.
-
-Routing in Schmancy is four things working together:
+Schmancy's client-side router. Three pieces:
 
 | Piece | Role |
 |-------|------|
-| `<schmancy-area name="...">` | Declares a named region of the screen |
-| `<schmancy-route when="tag">` | Declares which component can occupy it |
-| `area.push(...)` | Imperative navigation (click handlers, guards, effects) |
-| `lazy(() => import('...'))` | Code-split route components |
-
-## The Shape of a Real App
-
-Real apps nest areas. Outer `name="root"` handles public vs. authenticated. Inner `name="aria"` handles sub-views inside the authenticated shell.
-
-```typescript
-// app root — handles sign-in / public / authenticated
-@customElement('my-app')
-class MyApp extends $LitElement() {
-  render() {
-    return html`
-      <schmancy-theme root scheme="dark">
-        <schmancy-surface type="solid" fill="all">
-          <schmancy-scroll>
-            <schmancy-area
-              name="root"
-              .default=${lazy(() => import('./pages/landing.page'))}
-            >
-              <schmancy-route when="landing-page"
-                .component=${lazy(() => import('./pages/landing.page'))}
-              ></schmancy-route>
-
-              <schmancy-route when="methodology-page"
-                .component=${lazy(() => import('./pages/methodology.page'))}
-              ></schmancy-route>
-
-              <!-- Guarded route -->
-              <schmancy-route when="app-index"
-                .component=${lazy(() => import('./app/app.page'))}
-                .guard=${firebaseAuthState$.pipe(
-                  map(u => !!u && !u.isAnonymous),
-                  takeUntil(this.disconnecting),
-                )}
-                @redirect=${() => area.push({
-                  component: 'landing-page',
-                  area: 'root',
-                  historyStrategy: 'replace',
-                })}
-              ></schmancy-route>
-            </schmancy-area>
-          </schmancy-scroll>
-        </schmancy-surface>
-      </schmancy-theme>
-    `
-  }
-}
-```
-
-```typescript
-// nested area — inside the app shell
-render() {
-  return html`
-    <schmancy-nav-drawer>
-      <schmancy-nav-drawer-navbar width="180px">
-        <schmancy-list-item @click=${() => area.push({ area: 'aria', component: 'aria-agents-page' })}>
-          Agents
-        </schmancy-list-item>
-        <schmancy-list-item @click=${() => area.push({ area: 'aria', component: 'aria-knowledge-page' })}>
-          Knowledge
-        </schmancy-list-item>
-      </schmancy-nav-drawer-navbar>
-
-      <schmancy-nav-drawer-content>
-        <schmancy-area name="aria" default="aria-knowledge-page">
-          <schmancy-route when="aria-agents-page" .component=${lazy(() => import('./pages/agents'))}></schmancy-route>
-          <schmancy-route when="aria-knowledge-page" .component=${lazy(() => import('./pages/knowledge'))}></schmancy-route>
-          <schmancy-route when="aria-templates-page" .component=${lazy(() => import('./pages/templates'))}></schmancy-route>
-        </schmancy-area>
-      </schmancy-nav-drawer-content>
-    </schmancy-nav-drawer>
-  `
-}
+| `<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
+## `schmancy-area` properties
 
-| Property | Type | Required | Description |
-|----------|------|----------|-------------|
-| `name` | string | ✅ | Unique area identifier referenced in `area.push({ area: name })` |
-| `default` | `RouteComponent \| string` | — | Fallback when no route matches — prefer `lazy()` |
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | string (required) | Area identifier used in `area.push({ area })` |
+| `default` | `RouteComponent \| string` | Fallback when no route matches |
 
-## `schmancy-route` Properties
+## `schmancy-route` properties
 
-| Property | Type | Required | Description |
-|----------|------|----------|-------------|
-| `when` | string | ✅ | **Must exactly match** a `@customElement('tag')` tag name |
-| `component` | `RouteComponent` | ✅ | Class, tag name, or `lazy()` wrapper |
-| `guard` | `Observable<boolean>` | — | When emits `false`, route blocks and fires `@redirect` |
-| `exact` | boolean | — | Strict-equality matching |
+| 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 (imperative API)
+## `area` service
 
 ```typescript
 import { area } from '@mhmo91/schmancy'
 
 area.push({
-  area: 'root',               // target area name
-  component: 'app-index',     // tag name (or class reference)
-  params?: { id: '123' },     // pushed onto area.params()
+  area: 'root',
+  component: 'app-index',
+  params?: { id: '123' },
   historyStrategy?: 'push' | 'replace' | 'silent',
 })
 ```
 
 `historyStrategy`:
-- `'push'` (default) — browser back button returns to previous route
-- `'replace'` — overwrites current history entry (use after guards / redirects)
-- `'silent'` — changes the area without adding any history (transient state)
+- `'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
-connectedCallback() {
-  super.connectedCallback()
 
-  area.on('root').pipe(
-    takeUntil(this.disconnecting),
-  ).subscribe(route => {
-    console.log('root area is now:', route.component)
-  })
+```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))
-}
+area.params<{ id: string }>('detail').pipe(
+  takeUntil(this.disconnecting),
+).subscribe(params => this.loadItem(params.id))
 ```
 
-## Lazy Loading
-
-Code-split your routes. `lazy()` returns a preloadable reference.
+## Lazy loading
 
 ```typescript
 import { lazy } from '@mhmo91/schmancy'
-
 const HomePage = lazy(() => import('./home.page'))
 
-// Optional: preload on hover
-<schmancy-button
-  @mouseenter=${() => HomePage.preload()}
-  @click=${() => area.push({ area: 'root', component: 'home-page' })}
->
-  Home
-</schmancy-button>
+// Optional preload
+html`<button @mouseenter=${() => HomePage.preload()}>Home</button>`
 ```
 
-## Guards — the production pattern
+## Guards
 
-Guards are **RxJS Observables**, not booleans. This lets auth state flow through naturally.
+`guard` is an Observable<boolean>.
 
-```typescript
-import { firebaseAuthState$ } from './contexts/user.context'
+- 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/app.page'))}
-  .guard=${firebaseAuthState$.pipe(
-    map(user => !!user && !user.isAnonymous),
+  .component=${lazy(() => import('./app'))}
+  .guard=${authState$.pipe(
+    map(u => !!u),
     takeUntil(this.disconnecting),
   )}
   @redirect=${() => area.push({
-    component: 'landing-page',
-    area: 'root',
-    historyStrategy: 'replace',
-  })}
-></schmancy-route>
+    component: 'home-page', area: 'root', historyStrategy: 'replace',
+  })}></schmancy-route>
 ```
 
-- `guard` emits `true` → route renders.
-- `guard` emits `false` → Schmancy fires a `redirect` event on the route; handle it with `area.push(...)` using `historyStrategy: 'replace'` so the blocked route doesn't stay in history.
-
-## Rules
+Compound guard (multiple streams):
 
-1. `when="tag-name"` **must exactly match** `@customElement('tag-name')` on the component's class.
-2. Every route component should extend `$LitElement` and use `takeUntil(this.disconnecting)` in subscriptions.
-3. Route components are responsible for their own scroll/focus handling on mount.
-4. When calling `area.push` after auth guards or side-effectful redirects, use `historyStrategy: 'replace'`.
-5. Nested areas are not just allowed — they're the default for any app with a shell + sub-views.
-
-## Common recipes
-
-### Redirect after sign-in
 ```typescript
-await signIn(email, password)
-area.push({ component: 'app-index', area: 'root', historyStrategy: 'replace' })
+.guard=${combineLatest([permissions$, orgContext.$]).pipe(
+  takeUntil(this.disconnecting),
+  map(([perms, org]) => perms.includes('billing.view') && org?.billing?.configured),
+)}
 ```
 
-### Silent state swap (no history pollution)
-```typescript
-// e.g. swapping between auth screens without adding history
-area.push({ component: 'signup-form', area: 'sign', historyStrategy: 'silent' })
-```
+## Nested areas
 
-### Click-driven sub-nav
-```typescript
-<schmancy-list-item @click=${() => area.push({ area: 'aria', component: 'aria-agents-page' })}>
-  Agents
-</schmancy-list-item>
-```
+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.
 
-### Preload routes on hover
-```typescript
-const DashboardPage = lazy(() => import('./dashboard.page'))
+```html
+<!-- outer -->
+<schmancy-area name="root">
+  <schmancy-route when="app-index" .component=${AppShell}></schmancy-route>
+</schmancy-area>
 
-html`<a @mouseenter=${() => DashboardPage.preload()} @click=${() => area.push({ area: 'root', component: 'dashboard-page' })}>Dashboard</a>`
+<!-- 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/ai/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/ai/mixins.md

@@ -1,17 +1,16 @@
-# $LitElement — Base Class Foundation
+# `$LitElement`
 
-> **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.
+Base class for Schmancy components. Extends `LitElement` with RxJS cleanup, Tailwind support, and cross-shadow discovery.
 
-## The minimal component
+## Usage
 
 ```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`
+@customElement('my-component')
+class MyComponent extends $LitElement(css`
   :host { display: block; }
 `) {
   render() {
@@ -20,147 +19,69 @@ class MyCard extends $LitElement(css`
 }
 ```
 
-That's it. You now get the five things below for free.
+`$LitElement(style?)` accepts either a Lit `css` tagged literal or a string (e.g. SCSS imported with `?inline`).
+
+## Provided members
 
-## What `$LitElement` gives you
+### `disconnecting: Subject<void>`
+Emits once when the element disconnects. Pair with `takeUntil` for cleanup:
 
-### 1. `disconnecting` — automatic RxJS cleanup
 ```typescript
 connectedCallback() {
   super.connectedCallback()
-
-  userContext.$.pipe(
+  someObservable$.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>
-  `
+  ).subscribe()
 }
 ```
 
-Direct passthrough to Lit's `styleMap` directive, exposed as a method so you don't have to import it in every component.
+### `classMap(obj)`
+Wraps Lit's `classMap` so keys can be space-separated:
 
-### 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'))
-}
+html`<div class=${this.classMap({
+  'flex items-center gap-2': true,
+  'opacity-50': this.disabled,
+})}></div>`
 ```
 
-Broadcasts a `{tag}-where-are-you` event. Any mounted `$LitElement` with that tag responds with itself. Works **across shadow DOM boundaries** — zero traversal.
+Must be the only expression in `class=` — don't mix with string interpolation.
 
-### 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.
+### `styleMap(obj)`
+Passthrough to Lit's `styleMap`.
 
 ```typescript
-// Works out of the box
-render() {
-  return html`<div class="flex items-center gap-2 text-primary-default">…</div>`
-}
+html`<div style=${this.styleMap({ width: `${w}px` })}></div>`
 ```
 
-## Extending with SCSS
-
-For complex styling, import a `.scss?inline` file and pass it to `$LitElement`:
+### `discover<T>(tag): Observable<T | null>`
+Find another Schmancy component by tag via event-based handshake. Works across shadow DOM.
 
 ```typescript
-import style from './my-card.scss?inline'
-
-@customElement('my-card')
-class MyCard extends $LitElement(style) {
-  // SCSS features: nesting, mixins, @layer
-}
+this.discover<SchmancyDialog>('schmancy-dialog').pipe(
+  takeUntil(this.disconnecting),
+).subscribe(dialog => dialog?.setDefaultAction('confirm'))
 ```
 
-Simple components use template-literal CSS; complex ones use SCSS.
-
-## Standard component shape
+### Auto-response to discovery
+Every `$LitElement` responds to `{its-tag}-where-are-you` events with `{its-tag}-here-i-am` carrying `{ detail: { component: this } }`.
 
-This is the skeleton 90% of Schmancy components follow:
+## Component skeleton
 
 ```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
+export class MyComponent extends $LitElement(css`:host { display: block }`) {
   @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))
+    // subscriptions here, with takeUntil(this.disconnecting)
   }
 
-  // 5. Rendering
   render() {
-    return html`
-      <div class=${this.classMap({
-        'flex items-center': true,
-        'opacity-50': this.disabled,
-      })}>
-        <slot></slot>
-      </div>
-    `
+    return html`<slot></slot>`
   }
-
-  // 6. Public imperative API (if any)
-  public open() { this._open = true }
 }
 
 declare global {
@@ -170,32 +91,9 @@ declare global {
 }
 ```
 
-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.
+- 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.