@mhmo91/schmancy 0.9.2 → 0.9.3

package/dist/ai/expand.md

@@ -0,0 +1,63 @@
+# schmancy-expand
+
+> Expandable/accordion component. Inline mode uses grid-template-rows transitions; portal mode teleports content to a body-level `schmancy-expand-root` with backdrop.
+
+## Usage
+```html
+<schmancy-expand summary="Details">
+  <p>Content appears when expanded.</p>
+</schmancy-expand>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `summary` | string | `''` | Summary text shown when collapsed |
+| `open` | boolean | `false` | Expansion state (reflected) |
+| `summary-padding` | string | — | CSS padding for the summary row |
+| `content-padding` | string | — | CSS padding for the body |
+| `hide-indicator` | boolean | `false` | Hide the chevron indicator |
+| `indicator-rotate` | number | `90` | Rotation angle (deg) when open |
+| `backdrop` | boolean | `true` | Show semi-transparent backdrop in portal mode |
+| `inline` | boolean | `false` | Inline expansion instead of portal (no backdrop) |
+
+## Slots
+| Slot | Purpose |
+|------|---------|
+| (default) | Expanded content |
+| `summary` | Custom summary markup (overrides `summary` property) |
+
+## Behavior
+- **Portal mode (default)**: on open, content is teleported into a body-anchored `schmancy-expand-root` with a backdrop. Click outside or press `Escape` to close.
+- **Inline mode** (`inline`): uses `grid-template-rows: 0fr → 1fr` transition inside the host — no portal, no backdrop.
+- `SPRING_SNAPPY` physics for indicator rotation.
+- Respects `prefers-reduced-motion`.
+- Broadcast event `SCHMANCY_EXPAND_REQUEST_CLOSE` on `window` closes whichever instance is currently open.
+
+## Example — inline accordion
+```html
+${repeat(this.faqs, faq => faq.id, faq => html`
+  <schmancy-expand inline .summary=${faq.question}>
+    <p>${faq.answer}</p>
+  </schmancy-expand>
+`)}
+```
+
+## Example — portal with custom summary slot
+```html
+<schmancy-expand>
+  <div slot="summary" class="flex items-center gap-2">
+    <schmancy-icon>info</schmancy-icon>
+    <schmancy-typography type="title">Advanced options</schmancy-typography>
+  </div>
+  <div class="p-4">
+    <!-- settings form -->
+  </div>
+</schmancy-expand>
+```
+
+## Programmatic Close
+```typescript
+import { SCHMANCY_EXPAND_REQUEST_CLOSE } from '@mhmo91/schmancy'
+window.dispatchEvent(new Event(SCHMANCY_EXPAND_REQUEST_CLOSE))
+```

package/dist/ai/extra.md

@@ -0,0 +1,59 @@
+# Schmancy Extra
+
+> Data-driven dropdowns for common localization fields. Country and timezone pickers, form-associated and autocomplete-backed.
+
+## schmancy-select-countries
+Fully autocomplete-searchable country dropdown. Form-associated (participates in `<form>` submission and validation via `ElementInternals`).
+
+```html
+<schmancy-select-countries
+  name="country"
+  label="Country"
+  placeholder="Select a country"
+  required
+  value="DE"
+  @change=${e => this.country = e.target.value}
+></schmancy-select-countries>
+```
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `value` | string | — | ISO country code (reflected) |
+| `name` | string | `''` | Form field name |
+| `label` | string | `'Country'` | Visible label |
+| `hint` | string | `'Please select a country'` | Helper text |
+| `placeholder` | string | `'Select a country'` | Placeholder in the input |
+| `required` | boolean | `false` | Validation constraint |
+
+## schmancy-select-timezones
+Same pattern as countries, backed by timezone data.
+
+```html
+<schmancy-select-timezones
+  name="timezone"
+  label="Timezone"
+  value="Europe/Berlin"
+></schmancy-select-timezones>
+```
+
+Accepts the same set of properties (`value`, `name`, `label`, `hint`, `placeholder`, `required`).
+
+## Raw Data Exports
+If you want the underlying data without the component:
+```typescript
+import countries from '@mhmo91/schmancy'   // default export from countries.data
+import timezones from '@mhmo91/schmancy'   // default export from timezones.data
+```
+
+Each countries row: `{ code, name, dialCode?, flag?, ... }`. Timezones: `{ name, offset, label, ... }`.
+
+## Form Integration
+Both use `formAssociated = true` and register with the parent `<form>`. Works with native `form.checkValidity()` and with [`schmancy-form`](./form.md).
+
+```html
+<schmancy-form @submit=${this.onSubmit}>
+  <schmancy-select-countries name="country" required></schmancy-select-countries>
+  <schmancy-select-timezones name="timezone" required></schmancy-select-timezones>
+  <schmancy-button type="submit" variant="filled">Save</schmancy-button>
+</schmancy-form>
+```

package/dist/ai/float.md

@@ -0,0 +1,14 @@
+# schmancy-float (deprecated alias)
+
+> Backward-compatibility alias for [`schmancy-window`](./window.md). Existing code keeps working — new code should use `schmancy-window` directly.
+
+## Migration
+```html
+<!-- Before -->
+<schmancy-float id="panel">…</schmancy-float>
+
+<!-- After -->
+<schmancy-window id="panel">…</schmancy-window>
+```
+
+All properties are identical. See [window.md](./window.md) for full API.

package/dist/ai/iframe.md

@@ -0,0 +1,44 @@
+# schmancy-iframe
+
+> Sandboxed iframe that auto-sizes to its content. Ships with sensible document resets (font, spacing, tables, pre, blockquote).
+
+## Usage
+```html
+<schmancy-iframe .html=${emailBodyHtml}></schmancy-iframe>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `html` | string | `''` | Body HTML fragment to render |
+| `css` | string | `''` | Extra CSS injected after `baseCss` |
+| `baseCss` | string | default reset | Document CSS — override for fully custom styling |
+| `sandbox` | string | `'allow-same-origin allow-popups'` | Iframe sandbox attribute |
+| `minHeight` | number | `60` | Minimum iframe height in px |
+
+## Events
+| Event | When |
+|-------|------|
+| `load` | Native iframe load; height auto-syncs after |
+
+## Default Resets
+The built-in `baseCss` applies: system font, 14px/1.6 line-height, reset margins for headings/lists/paragraphs, bordered tables, blockquote styling, code/pre backgrounds, responsive images.
+
+## Examples
+```html
+<!-- Email preview with extra styles -->
+<schmancy-iframe
+  .html=${this.email.bodyHtml}
+  .css=${`h1 { color: #6200ee; }`}
+></schmancy-iframe>
+
+<!-- Fully custom base styling -->
+<schmancy-iframe
+  .html=${fragment}
+  .baseCss=${'html,body{margin:0;background:#000;color:#fff}'}
+></schmancy-iframe>
+```
+
+## When to Use
+- Rendering untrusted / styled third-party HTML (emails, rich snippets, MD-rendered content) in isolation.
+- Preview panes for user-generated HTML.

package/dist/ai/json.md

@@ -0,0 +1,33 @@
+# schmancy-json
+
+> Pretty-printed JSON viewer with key highlighting and click-to-copy.
+
+## Usage
+```html
+<schmancy-json .data=${{ user: 'alice', score: 42 }}></schmancy-json>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `data` | object | `{}` | JSON-serialisable data to display |
+| `highlightKeys` | string[] | `[]` | Keys whose values are highlighted (warning color, bold) |
+| `compact` | boolean | `false` | Disable pretty-printing (single line) |
+
+## Behavior
+- Click anywhere on the viewer to copy the full JSON to clipboard (fires `$notify.success`).
+- Container uses `surface-container` glass background with hover state.
+- Monospace font, 10px size — optimized for dense debug output.
+- Values for `highlightKeys` render inside `<span class="text-warning-default font-bold">`.
+
+## Examples
+```html
+<!-- Debug view with key highlights -->
+<schmancy-json
+  .data=${this.state}
+  .highlightKeys=${['error', 'pending']}
+></schmancy-json>
+
+<!-- Compact inline -->
+<schmancy-json compact .data=${{ id: 42, status: 'ok' }}></schmancy-json>
+```

package/dist/ai/layout.md

@@ -0,0 +1,63 @@
+# Schmancy Layout
+
+> Layout primitives: `schmancy-grid`, `schmancy-flex`, `schmancy-scroll`, plus `sch-grid` / `sch-flex` v2 variants.
+
+> **Prefer Tailwind classes directly** for layout in new code. These components exist for quick composition and design-token consistency (`gap="sm|md|lg"` maps to theme spacing).
+
+## schmancy-grid
+```html
+<schmancy-grid cols="1fr 2fr 1fr" gap="md" align="center">
+  <div>Left</div><div>Center</div><div>Right</div>
+</schmancy-grid>
+```
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `flow` | `'row' \| 'col' \| 'dense' \| 'row-dense' \| 'col-dense'` | `'row'` | Grid auto-flow |
+| `align` | `'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'` | `'stretch'` | Item alignment |
+| `justify` | `'start' \| 'center' \| 'end' \| 'stretch'` | `'stretch'` | Item justification |
+| `content` | `'start' \| 'center' \| 'end' \| 'stretch' \| 'around' \| 'evenly' \| 'between'` | — | Align-content |
+| `gap` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg'` | `'none'` | Grid gap |
+| `cols` | string | — | grid-template-columns (e.g. `"1fr 2fr"`) |
+| `rows` | string | — | grid-template-rows |
+| `rcols` | object | — | Responsive cols: `{ sm: '1fr', md: '1fr 1fr', lg: '1fr 2fr 1fr' }` |
+| `wrap` | boolean | `false` | Grid auto-wrap |
+
+## schmancy-flex
+```html
+<schmancy-flex flow="row" justify="between" align="center" gap="md">
+  <div>Logo</div><div>Nav</div>
+</schmancy-flex>
+```
+
+| Property | Type | Default |
+|----------|------|---------|
+| `flow` | `'row' \| 'row-reverse' \| 'col' \| 'col-reverse'` | `'col'` |
+| `wrap` | `'wrap' \| 'nowrap' \| 'wrap-reverse'` | `'wrap'` |
+| `align` | `'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'` | `'start'` |
+| `justify` | `'start' \| 'center' \| 'end' \| 'stretch' \| 'between'` | `'start'` |
+| `gap` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'none'` |
+
+## schmancy-scroll
+```html
+<schmancy-scroll hide direction="vertical" name="main">
+  <!-- long content -->
+</schmancy-scroll>
+```
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `hide` | boolean | `false` | Hide scrollbar in supported browsers |
+| `direction` | `'vertical' \| 'horizontal' \| 'both'` | `'both'` | Scroll axes |
+| `name` | string | — | Identifier for global scroll events |
+| `debounce` | number | — | Debounce time in ms for scroll events |
+
+Smooth scroll-behavior, overscroll containment, and support for flex-shrink sizing.
+
+## sch-grid / sch-flex (v2)
+
+Reflected-attribute variants optimized for styling via CSS selectors. Same prop model as the classic components with a `sch-` prefix. Use when you need to target the layout from parent CSS without Tailwind.
+
+## Notes
+- All layout components extend the base `Layout` class which exposes pass-through CSS properties (padding, margin, width, position, border, etc.).
+- Prefer Tailwind (`class="flex items-center gap-2"`) for new code — these components remain for consistent theme-driven gaps and rapid prototyping.

package/dist/ai/mailbox.md

@@ -0,0 +1,102 @@
+# Schmancy Mailbox
+
+> Full email composition + campaign management system. Orchestrates recipients, templates, editor, attachments, and preview. Extracted from funkhaus-events and generalized.
+
+## Components
+
+| Tag | Purpose |
+|-----|---------|
+| `schmancy-mailbox` | Top-level orchestrator |
+| `schmancy-email-editor` | Subject + body composition |
+| `schmancy-email-viewer` | HTML/plaintext preview |
+| `schmancy-email-recipients` | Recipient list with import/CSV |
+| `schmancy-email-layout-selector` | Layout template picker |
+| `schmancy-email-template-picker` | Email template browser |
+
+## Usage
+```html
+<schmancy-mailbox
+  .config=${{
+    sendEndpoint: '/api/emails/send',
+    uploadEndpoint: '/api/uploads',
+    authenticateRequest: (req) => ({ ...req, headers: { Authorization: `Bearer ${token}` } })
+  }}
+  .templates=${myTemplates}
+  .importSources=${[
+    { id: 'ticketholders', label: 'Ticket holders', icon: 'confirmation_number', handler: loadTicketHolders },
+    { id: 'waitlist', label: 'Waitlist', icon: 'hourglass_empty', handler: loadWaitlist },
+  ]}
+></schmancy-mailbox>
+```
+
+## schmancy-mailbox Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `config` | `EmailComposeConfig` | `{}` | Endpoints, auth, upload handlers |
+| `templates` | `EmailTemplate[]` | `[]` | Available email templates |
+| `importSources` | `ImportSource[]` | `[]` | Import buttons shown in recipients panel |
+| `disabled` | boolean | `false` | Disable all interactions |
+| `recipientsTitle` | string | `'Recipients'` | Recipients panel heading |
+| `recipientsEmptyTitle` | string | `'No recipients yet'` | Empty state title |
+| `recipientsEmptyMessage` | string | `'Import from sources or upload a CSV'` | Empty state body |
+| `enableCsvImport` | boolean | `true` | Allow CSV file import |
+| `enableDragDrop` | boolean | `true` | Accept dropped CSV files |
+
+## Key Types
+```typescript
+interface EmailTemplate { id, name, subject, body, category?, thumbnail? }
+
+interface EmailComposeConfig {
+  sendEndpoint?: string
+  templatesEndpoint?: string
+  uploadEndpoint?: string
+  authenticateRequest?: (req: RequestInit) => RequestInit
+  uploadHandler?: (file: File) => Promise<string>
+  imageUploadHandler?: (file: File) => Promise<string>
+}
+
+interface SendEmailRequest {
+  recipients: string[]
+  subject: string
+  body: string
+  attachments: EmailAttachment[]
+  templateId?: string | null
+}
+
+interface ImportSource {
+  id: string
+  label: string
+  icon: string       // Material icon name
+  handler: () => void // Populates recipients via events
+}
+```
+
+## Events
+| Event | Detail | Where |
+|-------|--------|-------|
+| `emails-imported` | `{ emails, source }` | Recipients |
+| `recipient-removed` | `{ email }` | Recipients |
+| `recipients-cleared` | `{}` | Recipients |
+| `selection-changed` | `{ selectedEmails }` | Recipients |
+| `compose-changed` | `{ subject, body, templateId, attachments }` | Editor |
+| `send-email` | `{ request: SendEmailRequest }` | Mailbox — consumer POSTs to backend |
+| `send-error` | `{ error }` | Mailbox |
+
+## Recipients Flow
+1. User clicks an `ImportSource` button (or drops a CSV).
+2. CSV is parsed → `validEmails`, `invalidEmails`, `duplicates` reported.
+3. `emails-imported` event fires; mailbox merges into selected recipients.
+4. User edits subject/body via email-editor; changes bubble as `compose-changed`.
+5. On send, `send-email` fires with the full `SendEmailRequest` — parent handles network.
+
+## Minimal Integration
+```typescript
+<schmancy-mailbox
+  .config=${config}
+  .templates=${templates}
+  @send-email=${async (e: CustomEvent<{ request: SendEmailRequest }>) => {
+    const result = await api.sendCampaign(e.detail.request)
+    if (!result.success) this.dispatchError(result.message)
+  }}
+></schmancy-mailbox>
+```

package/dist/ai/map.md

@@ -0,0 +1,55 @@
+# schmancy-map
+
+> Google Maps component. Accepts address string (auto-geocoded) or exact lat/lng. Singleton-loaded Maps SDK.
+
+## Usage
+```html
+<!-- By address -->
+<schmancy-map
+  address="Times Square, New York"
+  api-key="YOUR_GOOGLE_MAPS_KEY"
+></schmancy-map>
+
+<!-- By coordinates -->
+<schmancy-map
+  .latitude=${40.758}
+  .longitude=${-73.985}
+  .zoom=${15}
+  type="satellite"
+  api-key="YOUR_GOOGLE_MAPS_KEY"
+></schmancy-map>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `address` | string | — | Location for geocoding (e.g. `"Eiffel Tower, Paris"`) |
+| `latitude` | number | — | Precise latitude (takes precedence over address) |
+| `longitude` | number | — | Precise longitude |
+| `zoom` | number | default Maps default | Map zoom level |
+| `type` | `'roadmap' \| 'satellite' \| 'hybrid' \| 'terrain'` | `'roadmap'` | Map style |
+| `height` | string | — | Custom height (e.g. `'400px'`, `'60vh'`) |
+| `apiKey` | string | **required** | Google Maps API key |
+
+## Behavior
+- The first `schmancy-map` instance triggers a singleton script load of `maps.googleapis.com/maps/api/js` with the `places` library.
+- Subsequent instances reuse the same loader — no duplicate network requests.
+- If `address` is provided without coordinates, the built-in `Geocoder` resolves it before rendering.
+- Errors (invalid key, unauthorized domain, geocode failure) render a fallback message inside the host.
+
+## Setup
+1. Acquire a Google Maps JavaScript API key from Google Cloud Console.
+2. Enable the **Maps JavaScript API** and **Geocoding API**.
+3. Add your domain to the authorized list.
+
+## Example
+```html
+<schmancy-surface type="subtle" rounded="all">
+  <schmancy-map
+    address="1600 Amphitheatre Parkway, Mountain View, CA"
+    height="320px"
+    type="hybrid"
+    .apiKey=${import.meta.env.VITE_GOOGLE_MAPS_KEY}
+  ></schmancy-map>
+</schmancy-surface>
+```

package/dist/ai/mixins.md

@@ -1,70 +1,201 @@
-# Schmancy Mixins
+# $LitElement — Base Class Foundation
 
-> Base classes and utilities: `$LitElement`, `disconnecting`, `classMap`, `styleMap`.
+> **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.
 
-## $LitElement
+## The minimal component
 
-The base class for all Schmancy components. Extends LitElement with Tailwind support and RxJS cleanup.
+```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
-import { $LitElement } from '@mhmo91/schmancy/dist/mixins'
-import { css } from 'lit'
+connectedCallback() {
+  super.connectedCallback()
 
-@customElement('my-component')
-class MyComponent extends $LitElement(css`:host { display: block }`) {
-  // ...
+  userContext.$.pipe(
+    takeUntil(this.disconnecting),
+  ).subscribe(user => this.user = user)
 }
 ```
 
-## Provided Features
+`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>
+  `
+}
+```
 
-### disconnecting (Subject)
-RxJS Subject that emits when the component is disconnected. Use with `takeUntil` for automatic cleanup.
+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()
-  someObservable$.pipe(
-    takeUntil(this.disconnecting)
-  ).subscribe()
+
+  this.discover<SchmancyDialog>('schmancy-dialog').pipe(
+    takeUntil(this.disconnecting),
+  ).subscribe(dialog => dialog?.setDefaultAction('confirm'))
 }
 ```
 
-### classMap(classes)
-Enhanced version of Lit's `classMap` that splits space-separated keys.
+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
-// Supports space-separated class keys (unlike standard classMap)
-class=${this.classMap({
-  'flex items-center gap-2': true,
-  'bg-primary-default': this.active,
-})}
+// Works out of the box
+render() {
+  return html`<div class="flex items-center gap-2 text-primary-default">…</div>`
+}
 ```
 
-**Critical:** Must be the SOLE expression in `class=`. Never mix with string interpolation.
+## Extending with SCSS
 
-### styleMap(styles)
-Direct passthrough to Lit's `styleMap` directive.
+For complex styling, import a `.scss?inline` file and pass it to `$LitElement`:
 
 ```typescript
-style=${this.styleMap({ width: '100px', opacity: this.visible ? 1 : 0 })}
+import style from './my-card.scss?inline'
+
+@customElement('my-card')
+class MyCard extends $LitElement(style) {
+  // SCSS features: nesting, mixins, @layer
+}
 ```
 
-### discover(tag)
-Find components by tag name via event-based discovery.
+Simple components use template-literal CSS; complex ones use SCSS.
+
+## Standard component shape
+
+This is the skeleton 90% of Schmancy components follow:
 
 ```typescript
-this.discover<MyOtherComponent>('my-other-component').pipe(
-  takeUntil(this.disconnecting)
-).subscribe(component => { ... })
+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
+  }
+}
 ```
 
-### stableId / uid
-- `stableId`: Deterministic ID based on DOM path (stable across renders)
-- `uid`: Unique instance ID (auto-generated or set via attribute)
+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
 
-### dispatchScopedEvent(name, detail, options)
-Dispatches both a scoped event (`name::uid`) and generic event for backward compatibility.
+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.
 
-### locale
-Current locale from theme context, falls back to `navigator.language`.
+## 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.