@mhmo91/schmancy 0.9.2 → 0.9.4

package/README.md

@@ -16,17 +16,17 @@ import { magnetic, cursorGlow, gravity } from '@mhmo91/schmancy/directives'
 ## Quick Start
 
 ```html
-<schmancy-theme color="#6200ee" scheme="auto">
-  <schmancy-surface type="subtle" rounded="all" fill="all">
-    <schmancy-button variant="filled">Click me</schmancy-button>
+<schmancy-theme root scheme="dark">
+  <schmancy-surface type="solid" fill="all">
+    <schmancy-area name="root" .default=${lazy(() => import('./home.page'))}>
+      <schmancy-route when="home-page" .component=${lazy(() => import('./home.page'))} />
+    </schmancy-area>
   </schmancy-surface>
 </schmancy-theme>
 ```
 
 ## Design: Luminous Glass
 
-Every surface is translucent glass. Depth = blur intensity. Elevation = colored glow. Interactions = spring physics.
-
 | Surface | Opacity | Blur | Purpose |
 |---------|---------|------|---------|
 | `solid` | 92% | — | Dense glass, high readability |
@@ -34,77 +34,21 @@ Every surface is translucent glass. Depth = blur intensity. Elevation = colored
 | `glass` | 55% | 16px | Overlays, dialogs, dropdowns |
 | `luminous` | 42% | 20px | Hero panels with glow halo |
 
-## Components
-
-### Surfaces & Layout
-- [Surface](./ai/surface.md) — Glass depth system: solid, subtle, glass, luminous
-- [Card](./ai/card.md) — Content containers with glow elevation and cursorGlow
-- [Content Drawer](./ai/content-drawer.md) — Master-detail split panels
-- [Divider](./ai/divider.md) — Visual separators
-
-### Navigation
-- [Tabs](./ai/tabs.md) — Tabbed interfaces
-- [Navigation Bar](./ai/navigation-bar.md) — Bottom navigation (mobile)
-- [Navigation Rail](./ai/navigation-rail.md) — Side navigation (desktop)
-- [Nav Drawer](./ai/nav-drawer.md) — Slide-out navigation drawer
-- [Steps](./ai/steps.md) — Multi-step process indicator
-- [Area](./ai/area.md) — Client-side routing
-
-### Overlays
-- [Dialog](./ai/dialog.md) — Glass modal dialogs with cursorGlow
-- [Sheet](./ai/sheet.md) — Side/bottom panels with glass backdrop
-- [Notification](./ai/notification.md) — Toast notifications with type-colored glow
-- [Menu](./ai/menu.md) — Context menus
-- [Dropdown](./ai/dropdown.md) — Floating dropdown panels
-- [Tooltip](./ai/tooltip.md) — Hover tooltips
-- [Lightbox](./ai/lightbox.md) — Image gallery with FLIP animations
-
-### Form Elements
-- [Input](./ai/input.md) — Text input with luminous focus glow
-- [Textarea](./ai/textarea.md) — Multi-line text input
-- [Select](./ai/select.md) — Dropdown select
-- [Autocomplete](./ai/autocomplete.md) — Searchable dropdown
-- [Checkbox](./ai/checkbox.md) — Checkboxes
-- [Radio Group](./ai/radio-group.md) — Radio buttons
-- [Chips](./ai/chips.md) — Filter/input/suggestion chips with magnetic
-- [Form](./ai/form.md) — Form container with validation
-- [Date Range](./ai/date-range.md) — Date pickers
-
-### Interactive Elements
-- [Button](./ai/button.md) — Buttons with magnetic + glow hover
-- [List](./ai/list.md) — Interactive lists with glass hover
-- [Details](./ai/details.md) — Expandable sections with magnetic summary
-- [Table](./ai/table.md) — Data tables
-- [Tree](./ai/tree.md) — Hierarchical tree view
-
-### Feedback
-- [Progress](./ai/progress.md) — Linear progress bar
-- [Busy](./ai/busy.md) — Loading overlays
-- [Badge](./ai/badge.md) — Status indicators
-
-### Display
-- [Typography](./ai/typography.md) — Text styling system
-- [Icons](./ai/icons.md) — Material Symbols
-- [Avatar](./ai/avatar.md) — Profile images with fallback initials
-- [Code Highlight](./ai/code-highlight.md) — Syntax highlighting
-
-## Directives
-
-19 Lit directives that snap onto any element. [Full reference →](./ai/directives.md)
-
-**Physics:** `magnetic`, `cursorGlow`, `livingBorder`, `gravity`, `depthOfField`, `longPress`
-**Effects:** `nebula`, `liquid`, `ripple`
-**Text:** `animateText`, `cycleText`, `typewriter`
-**Visibility:** `reveal`, `intersect`
-**Interaction:** `drag`, `drop`, `color`
-
-## System
-
-- [Theme](./ai/theme.md) — Color theming + dark/light mode
-- [Store](./ai/store.md) — Reactive state management with persistence
-- [Mixins](./ai/mixins.md) — $LitElement base mixin with RxJS lifecycle
-- [Animation](./ai/animation.md) — Blackbird spring physics system
+## Docs
+
+Schmancy is organized in four layers:
+
+- **Foundations** — [Area](./ai/area.md) · [Store](./ai/store.md) · [Mixins ($LitElement)](./ai/mixins.md) · [Theme](./ai/theme.md) · [Directives](./ai/directives.md)
+- **Atoms** — [Typography](./ai/typography.md) · [Icons](./ai/icons.md) · [Button](./ai/button.md) · [Surface](./ai/surface.md) · [Divider](./ai/divider.md) · [Avatar](./ai/avatar.md)
+- **Composites (by job)** — Forms, Navigation, Overlays, Interaction, Feedback, Display
+- **Utilities** — [Animation](./ai/animation.md) · [Audio](./ai/audio.md) · [Discovery](./ai/discovery.md) · [RxJS Utils](./ai/rxjs-utils.md) · [Utils](./ai/utils.md)
+
+**Full component index:** [ai/INDEX.md](./ai/INDEX.md) — the single-file map with every tag, service, and convention. Written primarily for AI agents; humans welcome.
 
 ## Tech Stack
 
 [Lit](https://lit.dev) · [RxJS](https://rxjs.dev) · [Tailwind CSS v4](https://tailwindcss.com) · [Blackbird](./src/utils/animation.ts)
+
+## License
+
+Apache-2.0

package/ai/INDEX.md

@@ -0,0 +1,72 @@
+# Schmancy — Documentation Index
+
+A Web Component UI library on Lit + RxJS + Tailwind CSS.
+
+## Foundations
+
+The framework pieces — touch before components.
+
+- [Area](./area.md) — `<schmancy-area>`, `<schmancy-route>`, `area.push()`, `lazy()` for routing.
+- [Store](./store.md) — `createContext`, `@select`, `@selectItem`, storage backends.
+- [Mixins](./mixins.md) — `$LitElement` base class.
+- [Theme](./theme.md) — `<schmancy-theme>`, color scheme, CSS variables.
+- [Directives](./directives.md) — Lit directives for physics, effects, text, visibility, interaction.
+- [Animation](./animation.md) — Spring presets (`SPRING_SMOOTH`, etc.), `createAnimation`.
+
+## Components by job
+
+### Display
+[Typography](./typography.md) · [Icons](./icons.md) · [Avatar](./avatar.md) · [Divider](./divider.md) · [Badge](./badge.md) · [Code Highlight](./code-highlight.md) · [Typewriter](./typewriter.md) · [JSON](./json.md) · [Iframe](./iframe.md) · [Map](./map.md) · [Charts](./charts.md)
+
+### Surfaces & layout
+[Surface](./surface.md) · [Card](./card.md) · [Scroll / Grid / Flex](./layout.md) · [Page](./page.md) · [Content Drawer](./content-drawer.md) · [Window](./window.md) · [Boat](./boat.md) · [Float](./float.md)
+
+### Forms
+[Form](./form.md) · [Input](./input.md) · [Textarea](./textarea.md) · [Select](./select.md) · [Autocomplete](./autocomplete.md) · [Option](./option.md) · [Checkbox](./checkbox.md) · [Radio Group](./radio-group.md) · [Chips](./chips.md) · [Date Range](./date-range.md) · [Date Range Inline](./date-range-inline.md) · [Range](./range.md) · [Extra (Country/Timezone)](./extra.md)
+
+### Navigation
+[Nav Drawer](./nav-drawer.md) · [Tabs](./tabs.md) · [Navigation Bar](./navigation-bar.md) · [Navigation Rail](./navigation-rail.md) · [Steps](./steps.md) · [Teleport](./teleport.md) · [Theme Button](./theme-button.md)
+
+### Overlays
+[Dialog](./dialog.md) · [Sheet](./sheet.md) · [Notification](./notification.md) · [Menu](./menu.md) · [Dropdown](./dropdown.md) · [Tooltip](./tooltip.md) · [Lightbox](./lightbox.md) · [Expand](./expand.md)
+
+### Interactive
+[Button](./button.md) · [List](./list.md) · [Details](./details.md) · [Table](./table.md) · [Tree](./tree.md) · [Slider](./slider.md) · [QR Scanner](./qr-scanner.md)
+
+### Feedback
+[Progress](./progress.md) · [Busy](./busy.md) · [Connectivity](./connectivity.md) · [Delay](./delay.md)
+
+### Domain
+[Mailbox](./mailbox.md)
+
+## Services (imperative APIs)
+
+| Service | Purpose |
+|---------|---------|
+| `area` | Route navigation (see [area](./area.md)) |
+| `$dialog` | Open dialogs (see [dialog](./dialog.md)) |
+| `$notify` | Toast notifications (see [notification](./notification.md)) |
+| `schmancyContentDrawer` | Side panel (see [content-drawer](./content-drawer.md)) |
+| `theme` | Theme state, `fullscreen$` (see [theme](./theme.md)) |
+| `sound` | Audio feedback (see [audio](./audio.md)) |
+| `overlayStack` | Z-index coordinator (see [utils](./utils.md)) |
+| `windowManager` | Window registry (see [window](./window.md)) |
+
+## Utilities
+
+[Discovery](./discovery.md) — cross-shadow component lookup.
+[RxJS Utils](./rxjs-utils.md) — `waitForElement`, `waitUntil`, `mutationObserver`.
+[Utils](./utils.md) — `similarity`, `numbers`, `overlayStack`, `intersection$`, `hashContent`.
+[Audio](./audio.md) — synthesized feedback sounds.
+
+## Conventions
+
+- Lists use `repeat(items, item => item.id, tpl)`.
+- View switching uses `cache(...)`.
+- Expensive work uses `guard([deps], fn)`.
+- DOM access uses `ref(createRef())`.
+- Conditionals use `when(...)`, `choose(...)`, `ifDefined(...)`.
+- All RxJS subscriptions end with `.pipe(takeUntil(this.disconnecting))`.
+- Don't use `setTimeout` / `setInterval` / `addEventListener` — use RxJS (`timer`, `interval`, `fromEvent`).
+- Colors come from `--schmancy-sys-color-*` CSS vars or Tailwind theme classes.
+- `classMap(...)` must be the sole expression in `class=`; never mix with string interpolation.

package/ai/area.md

@@ -1,61 +1,141 @@
-# schmancy-area / schmancy-route
+# Area — Routing
 
-> Client-side router with named areas, lazy loading, route guards, and browser history integration.
+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
 
-## Usage
 ```html
-<schmancy-area name="main" default="home-page">
-  <schmancy-route when="home-page" .component=${lazy(() => import('./home'))}></schmancy-route>
-  <schmancy-route when="settings-page" .component=${lazy(() => import('./settings'))}></schmancy-route>
+<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>
 ```
 
-## Properties (schmancy-area)
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| name | string | required | Unique area name |
-| default | RouteComponent | - | Default route component |
-
-## Properties (schmancy-route)
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| when | string | required | Route identifier (must match `@customElement` tag) |
-| component | RouteComponent | required | Component to render (class, tag name, or lazy) |
-| exact | boolean | `false` | Exact path matching |
-| guard | Observable<boolean> | - | Route guard observable |
-
-## Programmatic Navigation (area service)
+## `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'
 
-// Navigate
-area.push({ area: 'main', component: 'settings-page', params: { id: '123' } })
+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 area changes
-area.on('main').pipe(takeUntil(this.disconnecting)).subscribe(route => { ... })
+### Subscribe to route state
 
-// Get params
-area.params<{id: string}>('main').pipe(takeUntil(this.disconnecting)).subscribe(params => { ... })
+```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
+## Lazy loading
+
 ```typescript
 import { lazy } from '@mhmo91/schmancy'
-const LazyPage = lazy(() => import('./my-page'))
+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(...)`.
 
-// Preload on hover
-element.addEventListener('mouseenter', () => LazyPage.preload())
+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>
 ```
 
-## Examples
+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
-<!-- With route guard -->
-<schmancy-area name="admin" default="admin-dashboard">
-  <schmancy-route when="admin-dashboard"
-    .component=${lazy(() => import('./dashboard'))}
-    .guard=${isAdmin$}>
-  </schmancy-route>
+<!-- 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>
 ```
 
-**Critical:** `when="tag-name"` MUST exactly match `@customElement('tag-name')` on the component class.
+## 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/audio.md

@@ -0,0 +1,69 @@
+# Schmancy Audio
+
+> Emotional sound service — synthesizes short, empathetic sounds via Web Audio API keyed on feelings (joyful, tense, calm, etc.). No assets. No external players. Just tones + puffs generated on demand.
+
+## Usage
+```typescript
+import { sound } from '@mhmo91/schmancy'
+
+sound.play('joyful')     // trigger a feeling sound
+sound.setVolume(0.2)     // 0..1
+sound.setMuted(true)
+sound.resetTheme()       // back to defaults
+```
+
+## Feelings
+Organized by emotional category:
+
+| Category | Feelings |
+|----------|----------|
+| Happy | `joyful`, `content`, `excited`, `grateful`, `proud`, `loved` |
+| Sad | `sad`, `disappointed`, `hurt`, `lonely`, `melancholy` |
+| Anxious | `worried`, `nervous`, `overwhelmed`, `tense` |
+| Angry | `frustrated`, `angry`, `annoyed` |
+| Tired | `tired`, `drained`, `bored` |
+| Calm | `calm`, `peaceful`, `relaxed`, `focused` |
+| Connected | `connected`, `supported`, `welcomed` |
+| Mixed | `confused`, `nostalgic`, `bittersweet` |
+
+(See `mood-audio.types.ts` for the authoritative list.)
+
+## Observable API
+```typescript
+sound.theme$.subscribe(theme => console.log(theme?.name ?? 'default'))
+sound.volume$.subscribe(v => {})
+sound.muted$.subscribe(m => {})
+```
+
+## Settings Persistence
+Volume, mute, and custom theme persist to `localStorage` under key `schmancy-sound-settings` (via `createContext`).
+
+## AI-Generated Themes
+```typescript
+import type { SoundTheme } from '@mhmo91/schmancy'
+
+const customTheme: SoundTheme = {
+  name: 'ocean',
+  sounds: {
+    joyful: { puffs: [...], tones: [...] },
+    // partial override — falls through to defaults for anything omitted
+  }
+}
+
+sound.setTheme(customTheme)
+```
+
+Each `FeelingSound` consists of:
+- **puffs** — short bursts (air/noise, e.g. `{ startTime, duration, frequency, volume }`)
+- **tones** — oscillators (`sine`/`triangle`/`square`/`sawtooth` with envelope)
+
+## Built-in Feedback Hooks
+Other Schmancy components play these automatically:
+- [`schmancy-connectivity-status`](./connectivity.md) on offline/online.
+- Some success/error paths in notifications and dialogs via the `$sounds` legacy helper.
+
+## Legacy API
+- `$sounds` — older generator exported for compatibility.
+- `EmotionalSoundGenerator` — underlying class.
+
+Prefer `sound` for new code.

package/ai/boat.md

@@ -0,0 +1,47 @@
+# schmancy-boat
+
+> Draggable floating FAB that expands into a panel. Great for persistent assistant/chat panels.
+
+> **Note:** `schmancy-window` is the evolved successor with more capabilities (resize, maximize, multi-window registry). Prefer `schmancy-window` for new code unless you want the simpler FAB-to-panel model.
+
+## Usage
+```html
+<schmancy-boat id="assistant" icon="smart_toy" label="Assistant">
+  <div slot="header">Assistant</div>
+  <div class="p-4">Panel body content</div>
+</schmancy-boat>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `id` | string | `'default'` | Unique identifier (persists drag position in localStorage) |
+| `icon` | string | — | Material icon for the FAB state |
+| `label` | string | — | Label text in FAB state |
+| `open` | boolean | `false` | Panel open/closed (reflected) |
+| `corner` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | `'bottom-right'` | Anchor corner |
+| `expandedWidth` | string | responsive | e.g. `'320px'` |
+| `lowered` | boolean | `false` | Lower shadow in FAB state |
+
+## Getter / Setter
+```typescript
+boat.state = 'expanded' | 'collapsed'   // equivalent to open = true/false
+boat.state                              // current state
+boat.expand() / boat.close()
+```
+
+## Behavior
+- Drag to reposition. Releases snap to the nearest corner.
+- Open/close uses clip-path + `SPRING_SMOOTH` for elegant reveal.
+- Position persists in `localStorage` under `schmancy-boat-{id}`.
+- Respects `prefers-reduced-motion`.
+
+## Example
+```html
+<schmancy-boat id="chat" icon="chat" label="Chat" corner="bottom-right">
+  <span slot="header">Messages</span>
+  <schmancy-list class="p-2">
+    <!-- messages -->
+  </schmancy-list>
+</schmancy-boat>
+```

package/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/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/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).