@mhmo91/schmancy 0.9.2 → 0.9.4

package/dist/ai/charts.md

@@ -0,0 +1,93 @@
+# Schmancy Charts
+
+> Canvas-rendered area chart and horizontal pill chart. Theme-aware, lazy-animated, with auto peak highlighting.
+
+## schmancy-area-chart
+
+> Smooth Catmull-Rom spline area chart with peak markers and hover tooltips.
+
+```html
+<schmancy-area-chart
+  .data=${[
+    { label: '9 AM', value: 12.4 },
+    { label: '10 AM', value: 18.9 },
+    { label: '11 AM', value: 42.1, metadata: { users: 320 } },
+    { label: '12 PM', value: 56.7 },
+  ]}
+  value-prefix="EUR "
+  value-decimals="2"
+  peak-count="2"
+  height="240"
+></schmancy-area-chart>
+```
+
+### Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `data` | `ChartDataPoint[]` | `[]` | `{ label, value, metadata? }[]` |
+| `height` | number | `200` | Chart height in px |
+| `showGrid` | boolean | `true` | Background grid lines |
+| `showLabels` | boolean | `true` | X-axis labels |
+| `showTooltip` | boolean | `true` | Hover tooltip |
+| `peakCount` | number | `3` | Top-N points highlighted larger |
+| `animationDuration` | number | `800` | Entrance animation ms |
+| `animated` | boolean | `true` | Animate on first visible |
+| `valuePrefix` | string | `''` | Display prefix (e.g. `"EUR "`) |
+| `valueSuffix` | string | `''` | Display suffix (e.g. `"%"`) |
+| `valueDecimals` | number | `2` | Decimal places |
+| `theme` | `Partial<ChartTheme>` | `{}` | Override colors, stroke, radii |
+
+### ChartTheme
+| Key | Default | Description |
+|-----|---------|-------------|
+| `primaryColor` | `--schmancy-sys-color-primary` | Line + fill gradient color |
+| `gradientOpacity` | `[0.4, 0.05]` | Top/bottom fill opacity |
+| `strokeWidth` | `2` | Line thickness |
+| `pointRadius` | `4` | Normal point radius |
+| `peakRadius` | `6` | Peak point radius |
+
+## schmancy-pills
+
+> Horizontal bar chart with optional stacked segments, medal ranks, and peak/low styling.
+
+```html
+<schmancy-pills
+  .data=${[
+    { label: 'Mon', value: 1240, rank: 1 },
+    { label: 'Tue', value: 980 },
+    { label: 'Wed', value: 1830, rank: 2, segments: [
+      { label: 'Pizza', value: 1200 },
+      { label: 'Drinks', value: 630 }
+    ]},
+  ]}
+></schmancy-pills>
+```
+
+### Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `data` | `PillDataPoint[]` | `[]` | Rows with optional stacked `segments` |
+| `valuePrefix` / `valueSuffix` / `valueDecimals` | — | — | Value formatting (same as area chart) |
+| `showMedals` | boolean | `true` | Show 🥇🥈🥉 for rank 1/2/3 |
+
+### PillDataPoint
+```typescript
+{
+  label: string
+  value: number
+  segments?: { label, value, color }[]  // stacked
+  isPeak?: boolean   // highlighted
+  isLow?: boolean    // muted
+  rank?: 1 | 2 | 3   // medal
+  metadata?: Record<string, unknown>
+}
+```
+
+## Behavior
+- Both charts use an IntersectionObserver to defer animation until visible.
+- Responsive — resize triggers a re-render.
+- Dark/light aware via theme CSS variables.
+
+## When to Use
+- Area chart: time-series or comparative trends.
+- Pills: ranked categorical data (leaderboards, top days, distribution).

package/dist/ai/connectivity.md

@@ -0,0 +1,36 @@
+# schmancy-connectivity-status
+
+> App-wide online/offline banner. Mount once near the root and forget it.
+
+## Usage
+```html
+<!-- In your app shell -->
+<schmancy-connectivity-status></schmancy-connectivity-status>
+```
+
+## Properties
+None — it's entirely self-driven from `window` online/offline events.
+
+## Behavior
+- Listens to `window` `online` / `offline` events via RxJS `merge`.
+- `distinctUntilChanged` prevents duplicate banners.
+- Animated slide-down banner with spring-style easing when state changes.
+- Offline: error-colored banner with pulsing icon.
+- Online (after offline): success-colored banner with bouncing icon, auto-dismisses after a short timer.
+- Plays matching sounds from the `$sounds` audio service (skipped on initial load).
+- Respects `prefers-reduced-motion` implicitly via CSS.
+
+## Setup
+Place it once at the root — typically just inside your main `schmancy-theme` or app shell:
+
+```html
+<schmancy-theme>
+  <schmancy-connectivity-status></schmancy-connectivity-status>
+  <schmancy-page>
+    <!-- rest of app -->
+  </schmancy-page>
+</schmancy-theme>
+```
+
+## See Also
+- [audio.md](./audio.md) — the `$sounds` service used for feedback tones.

package/dist/ai/date-range-inline.md

@@ -0,0 +1,44 @@
+# schmancy-date-range-inline
+
+> Smart inline from/to date picker with validation, auto-correction, and gap constraints. Simpler surface than the full `schmancy-date-range` popover.
+
+## Usage
+```html
+<schmancy-date-range-inline
+  .dateFrom=${{ label: 'Check-in', value: '2026-05-01' }}
+  .dateTo=${{ label: 'Check-out', value: '2026-05-05' }}
+  min-date="2026-01-01"
+  max-date="2026-12-31"
+  .minGap=${1}
+  .maxGap=${30}
+  @change=${e => this.handleRange(e.detail)}
+></schmancy-date-range-inline>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `type` | `'date' \| 'datetime-local'` | `'date'` | Underlying input type |
+| `dateFrom` | `{ label, value }` | `{ label: 'From', value: '' }` | From-date configuration |
+| `dateTo` | `{ label, value }` | `{ label: 'To', value: '' }` | To-date configuration |
+| `minDate` | string | — | Minimum selectable date (ISO string) |
+| `maxDate` | string | — | Maximum selectable date (ISO string) |
+| `compact` | boolean | `false` | Tighter UI spacing |
+| `autoCorrect` | boolean | `true` | Auto-fix invalid ranges (e.g. swap if from > to) |
+| `minGap` | number | `0` | Minimum days between from and to |
+| `maxGap` | number | — | Maximum days between from and to |
+| `defaultGap` | number | `1` | Default gap when seeding the second date |
+| `allowSameDate` | boolean | `false` | Permit from === to |
+
+## Events
+| Event | Detail | When |
+|-------|--------|------|
+| `change` | `{ dateFrom, dateTo, isValid }` | Either input changes |
+
+## Behavior
+- Extends `SchmancyFormField()` — integrates with `schmancy-form` validation.
+- Auto-correction: invalid ranges flip, or the second date shifts to respect `minGap`/`maxGap`.
+- Inline (not a popover) — always visible, good for filters and trip-planning UIs.
+
+## Prefer full picker
+For a popup calendar with presets and visual selection, use [`schmancy-date-range`](./date-range.md).

package/dist/ai/delay.md

@@ -0,0 +1,50 @@
+# schmancy-delay
+
+> Defers rendering of children by a duration, with an entrance motion. Siblings auto-stagger without manual delay math.
+
+## Usage
+```html
+<schmancy-delay delay="200">
+  <h1>Appears after 200ms</h1>
+</schmancy-delay>
+
+<!-- Auto-staggered list: each child inherits + stacks its own delay -->
+<schmancy-delay delay="100">
+  <schmancy-delay delay="100"><div>Step 1</div></schmancy-delay>
+  <schmancy-delay delay="100"><div>Step 2</div></schmancy-delay>
+  <schmancy-delay delay="100"><div>Step 3</div></schmancy-delay>
+</schmancy-delay>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `delay` | number | `0` | Ms to wait before rendering this node |
+| `motion` | `'flyBelow' \| 'flyAbove' \| 'fadeIn'` | `'flyBelow'` | `@lit-labs/motion` entrance animation |
+| `once` | boolean | `true` | Skip delay on subsequent renders within the same session (keyed on content hash) |
+
+## Context
+- Consumes parent `delayContext` and adds its own delay.
+- Walks previous siblings that are also `schmancy-delay` and accumulates their delays.
+- Provides the resulting `effectiveDelay` down to descendants via context.
+
+Result: nested `schmancy-delay` nodes produce natural staggered entrances without manual math.
+
+## Session Caching
+- When `once=true`, the content is hashed on first render and cached in `sessionStorage`.
+- On subsequent component mounts (route revisits), the delay is skipped — content appears instantly.
+- Set `once=false` to always replay the delay.
+
+## Example — hero reveal
+```html
+<schmancy-delay delay="0" motion="fadeIn">
+  <schmancy-delay delay="300"><h1>Welcome</h1></schmancy-delay>
+  <schmancy-delay delay="200"><p>Subtitle…</p></schmancy-delay>
+  <schmancy-delay delay="200">
+    <schmancy-button variant="filled">Get started</schmancy-button>
+  </schmancy-delay>
+</schmancy-delay>
+```
+
+## See Also
+- Use [`gravity`](./directives.md#gravity--elements-fall-into-place-with-mass-based-bounce) directive for mass-based staggered reveal on lists — often simpler than nested `schmancy-delay`.

package/dist/ai/discovery.md

@@ -0,0 +1,67 @@
+# Schmancy Discovery
+
+> Event-based component and element discovery across shadow DOM boundaries. No DOM traversal — just broadcast and race.
+
+## Why
+Web components hide inside shadow DOM. Traversing with `querySelector` + `shadowRoot` everywhere is fragile. Discovery broadcasts a "where are you?" event; components respond with themselves.
+
+## API
+```typescript
+import {
+  discover,
+  discoverComponent,
+  discoverAnyComponent,
+  discoverElement,
+  discoverAllElements,
+} from '@mhmo91/schmancy'
+```
+
+### `discover(query, timeout?)`
+Smart auto-detect. Routes to `discoverElement` for CSS selectors (`#`, `.`, `[`) and `discoverComponent` for tag names.
+```typescript
+discover<SchmancyNavigationRail>('schmancy-navigation-rail').subscribe(el => el?.select('home'))
+discover('#hero-card').subscribe(el => el?.focus())
+```
+
+### `discoverComponent(tag, timeout = 100)`
+Broadcasts `{tag}-where-are-you`; first responder wins.
+```typescript
+discoverComponent<SchmancyDialog>('schmancy-dialog')
+  .subscribe(dialog => dialog?.open())
+```
+
+### `discoverAnyComponent(...tags)`
+Race between multiple tags — first to respond wins.
+```typescript
+discoverAnyComponent('schmancy-navigation-rail', 'schmancy-navigation-bar')
+  .subscribe(nav => nav?.select(route))
+```
+
+### `discoverElement(selector, timeout = 150)`
+Finds any element by CSS selector across shadow DOM. Uses a request ID + universal `schmancy-discover` event. Every `$LitElement` responds if it finds a match in its shadow root.
+```typescript
+discoverElement('[data-section="pricing"]').subscribe(section => section?.scrollIntoView())
+```
+
+### `discoverAllElements(selector, timeout = 150)`
+Collects **all** matching responses within the timeout window.
+```typescript
+discoverAllElements('.flagged').subscribe(all => console.log(all.length))
+```
+
+## How the Handshake Works
+1. Caller creates a unique `requestId` and broadcasts `schmancy-discover` on `window` with `{ selector, requestId }`.
+2. Every `$LitElement` listens for this event (wired up in the base class).
+3. Any matching element dispatches `schmancy-discover-response` with `{ requestId, element }`.
+4. Caller collects responses for the timeout window and emits via RxJS.
+
+## Pattern in Base Class
+Every `$LitElement` inherits auto-response: `discover<T>(tag)` (method on the component) and `{tagName}-where-are-you`/`{tagName}-here-i-am` events. See [mixins.md](./mixins.md).
+
+## When to Use
+- Cross-shadow coordination between unrelated components.
+- Imperatively focusing or driving a far-away UI piece from a handler.
+
+## When NOT to Use
+- Same-tree data flow — use `@provide`/`@consume` (Lit context) or Schmancy [`store`](./store.md).
+- Parent-to-child directly — just use `this.renderRoot.querySelector()`.

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.
+
+## 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>
+```