@mhmo91/schmancy 0.9.4 → 0.9.6

package/skills/schmancy/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/skills/schmancy/checkbox.md

@@ -0,0 +1,36 @@
+# schmancy-checkbox
+
+> Checkbox with label support and form association.
+
+## Usage
+```html
+<schmancy-checkbox label="I agree to terms" @change=${(e) => handle(e.detail.value)}>
+</schmancy-checkbox>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| value | boolean | `false` | Whether the checkbox is checked |
+| checked | boolean | `false` | Alias for value |
+| label | string | `undefined` | Label text (alternative to slot) |
+| name | string | auto | Form submission name |
+| disabled | boolean | `false` | Whether the checkbox is disabled |
+| required | boolean | `false` | Whether the checkbox is required |
+| size | `'xxs'\|'xs'\|'sm'\|'md'\|'lg'` | `'md'` | Checkbox size |
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| change | `{ value: boolean }` | When checked state changes |
+
+## Examples
+```html
+<!-- With label property -->
+<schmancy-checkbox label="Enable notifications" .value=${true}></schmancy-checkbox>
+
+<!-- With slotted label -->
+<schmancy-checkbox name="terms" required>
+  Accept <a href="/terms">terms and conditions</a>
+</schmancy-checkbox>
+```

package/skills/schmancy/chips.md

@@ -0,0 +1,87 @@
+# Chips
+
+> Four chip types: filter (toggleable), input (removable), suggestion (action), assist (action + elevated). Filter chips have embedded `magnetic` directive and selection glow.
+
+## Chip Types
+
+| Element | Purpose | Selected state | Default elevated |
+|---------|---------|---------------|-----------------|
+| `schmancy-filter-chip` | Toggle filters on/off | Yes (persists) | No |
+| `schmancy-input-chip` | Display user input, removable | No | No |
+| `schmancy-suggestion-chip` | Contextual recommendations | No | No |
+| `schmancy-assist-chip` | Prompt user actions | No | Yes |
+
+## Properties (schmancy-filter-chip)
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `value` | `string` | `''` | Unique identifier |
+| `selected` | `boolean` | `false` | Toggle state |
+| `removable` | `boolean` | `false` | Show remove button |
+| `disabled` | `boolean` | `false` | Disabled state |
+| `elevated` | `boolean` | `false` | Add shadow elevation |
+
+## Properties (schmancy-input-chip)
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `value` | `string` | `''` | Unique identifier |
+| `icon` | `string` | `''` | Material icon name |
+| `avatar` | `string` | `''` | Avatar image URL |
+| `removable` | `boolean` | `true` | Show remove button |
+| `disabled` | `boolean` | `false` | Disabled state |
+
+## Properties (schmancy-suggestion-chip / schmancy-assist-chip)
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `value` | `string` | `''` | Unique identifier |
+| `icon` | `string` | `''` | Material icon name |
+| `href` | `string` | `''` | Navigation URL |
+| `target` | `string` | `''` | Link target |
+| `disabled` | `boolean` | `false` | Disabled state |
+| `elevated` | `boolean` | `false` (suggestion) / `true` (assist) | Shadow elevation |
+
+## Events
+| Event | Chip types | Detail | Description |
+|-------|-----------|--------|-------------|
+| `change` | filter | `{ value, selected }` | Selection toggled |
+| `remove` | filter, input | `{ value }` | Remove button clicked |
+| `action` | suggestion, assist | `{ value }` | Chip clicked |
+
+## Physics
+- **magnetic** directive on filter chips (strength: 2, radius: 40)
+- Filter selected: secondary glow shadow (20% intensity)
+- Hover: luminous glow shadow (primary, 15%)
+- Active: spring press `scale(0.95)` with 100ms transition
+
+## Examples
+```html
+<!-- Filter chips for categories -->
+${repeat(categories, c => c.id, c => html`
+  <schmancy-filter-chip
+    value=${c.id}
+    ?selected=${selectedIds.has(c.id)}
+    @change=${(e: CustomEvent) => this.toggleFilter(e.detail)}
+  >
+    ${c.name}
+  </schmancy-filter-chip>
+`)}
+
+<!-- Input chips for tags -->
+${repeat(tags, t => t, t => html`
+  <schmancy-input-chip
+    value=${t}
+    @remove=${(e: CustomEvent) => this.removeTag(e.detail.value)}
+  >
+    ${t}
+  </schmancy-input-chip>
+`)}
+
+<!-- Suggestion chips -->
+<schmancy-suggestion-chip value="nearby" icon="location_on">
+  Nearby
+</schmancy-suggestion-chip>
+
+<!-- Assist chip with navigation -->
+<schmancy-assist-chip value="calendar" icon="event" href="/calendar">
+  Open Calendar
+</schmancy-assist-chip>
+```

package/skills/schmancy/code-highlight.md

@@ -0,0 +1,47 @@
+# schmancy-code
+
+> Syntax-highlighted code block with line numbers, copy button, and collapsible display.
+
+## Usage
+```html
+<schmancy-code language="typescript" .code=${'const x = 42'}></schmancy-code>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| code | string | `''` | Code content to highlight |
+| language | string | `'javascript'` | Language for syntax highlighting |
+| filename | string | `undefined` | Filename shown in header |
+| lineNumbers | boolean | `false` | Show line numbers |
+| copyButton | boolean | `true` | Show copy-to-clipboard button |
+| highlightLines | string | `undefined` | Lines to highlight (e.g., `'1-3,5,7-9'`) |
+| maxHeight | string | `undefined` | Max height before scrolling |
+
+## Supported Languages
+javascript, typescript, html, xml, markdown, bash
+
+## Examples
+```html
+<!-- TypeScript with line numbers and highlighted lines -->
+<schmancy-code
+  language="typescript"
+  lineNumbers
+  highlightLines="2-3"
+  .code=${`import { html } from 'lit'
+const greeting = 'Hello'
+console.log(greeting)`}>
+</schmancy-code>
+
+<!-- Bash with filename -->
+<schmancy-code language="bash" filename="install.sh"
+  .code=${'npm install @mhmo91/schmancy'}>
+</schmancy-code>
+
+<!-- With max height -->
+<schmancy-code language="javascript" maxHeight="300px"
+  .code=${longCodeString}>
+</schmancy-code>
+```
+
+Renders inside a collapsible `schmancy-details` with a macOS-style header (colored dots + language label). Uses highlight.js with schmancy color tokens.

package/skills/schmancy/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/skills/schmancy/content-drawer.md

@@ -0,0 +1,65 @@
+# schmancy-content-drawer
+
+> Responsive content drawer that switches between side panel (push) and bottom sheet (overlay) based on viewport.
+
+## Usage
+```html
+<schmancy-content-drawer>
+  <schmancy-content-drawer-main>
+    <!-- Primary content -->
+  </schmancy-content-drawer-main>
+  <schmancy-content-drawer-sheet>
+    <div slot="placeholder">Select an item</div>
+  </schmancy-content-drawer-sheet>
+</schmancy-content-drawer>
+```
+
+## Properties (schmancy-content-drawer)
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| open | `'open'\|'close'` | auto | Sheet state |
+
+## Properties (schmancy-content-drawer-main)
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| minWidth | number | `360` | Minimum width in pixels |
+
+## Properties (schmancy-content-drawer-sheet)
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| minWidth | number | `576` | Minimum width in pixels |
+
+## Rendering Content to Sheet
+```typescript
+// Dispatch event to render component in the sheet
+window.dispatchEvent(new CustomEvent('schmancy-content-drawer-render', {
+  detail: {
+    component: myElement,
+    state: {},
+    params: {},
+    props: {}
+  }
+}))
+```
+
+## Behavior
+- When `main.minWidth + sheet.minWidth <= viewport`: push mode (side-by-side)
+- When viewport is smaller: overlay mode (bottom sheet)
+- Sheet content is routed via an internal `schmancy-area`
+
+## Examples
+```html
+<schmancy-content-drawer>
+  <schmancy-content-drawer-main minWidth="400">
+    <div class="p-4">
+      <h2>List View</h2>
+      <!-- List items that open detail in sheet -->
+    </div>
+  </schmancy-content-drawer-main>
+  <schmancy-content-drawer-sheet minWidth="500">
+    <div slot="placeholder">
+      <p>Select an item to view details</p>
+    </div>
+  </schmancy-content-drawer-sheet>
+</schmancy-content-drawer>
+```

package/skills/schmancy/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/skills/schmancy/date-range.md

@@ -0,0 +1,50 @@
+# schmancy-date-range
+
+> Date range selector with preset ranges, step navigation, and mobile sheet support.
+
+## Usage
+```html
+<schmancy-date-range
+  .dateFrom=${{label: 'From', value: '2024-01-01'}}
+  .dateTo=${{label: 'To', value: '2024-12-31'}}
+  @change=${(e) => handleRange(e.detail)}>
+</schmancy-date-range>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| type | `'date'\|'datetime-local'` | `'date'` | Date input type |
+| dateFrom | `{label: string, value: string}` | `{label:'From',value:''}` | Start date |
+| dateTo | `{label: string, value: string}` | `{label:'To',value:''}` | End date |
+| minDate | string | `undefined` | Minimum selectable date |
+| maxDate | string | `undefined` | Maximum selectable date |
+| step | `'day'\|'week'\|'month'\|'year'\|number` | `undefined` | Navigation step size |
+| placeholder | string | `'Select date range'` | Display placeholder |
+| disabled | boolean | `false` | Whether disabled |
+| required | boolean | `false` | Whether required |
+| clearable | boolean | `true` | Allow clearing selection |
+| collapse | boolean | `false` | Icon-only on mobile |
+| customPresets | array | `[]` | Additional preset ranges |
+| format | string | auto | Date format string |
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| change | `{ dateFrom: string, dateTo: string }` | When date range changes |
+
+## Examples
+```html
+<!-- With step navigation (arrows shift by week) -->
+<schmancy-date-range step="week"
+  .dateFrom=${{label:'From', value:'2024-03-01'}}
+  .dateTo=${{label:'To', value:'2024-03-07'}}>
+</schmancy-date-range>
+
+<!-- Collapsed on mobile, custom presets -->
+<schmancy-date-range collapse
+  .customPresets=${[{label:'Q1',dateFrom:'2024-01-01',dateTo:'2024-03-31'}]}>
+</schmancy-date-range>
+```
+
+Built-in presets include Today, Yesterday, This Week, This Month, This Year, and more.

package/skills/schmancy/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/skills/schmancy/details.md

@@ -0,0 +1,66 @@
+# schmancy-details
+
+> Expandable disclosure with spring-animated indicator, magnetic summary, and CSS grid collapse animation.
+
+## Usage
+```html
+<schmancy-details summary="Show more">
+  <p>Expandable content here</p>
+</schmancy-details>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `summary` | `string` | `''` | Summary text (or use `summary` slot) |
+| `open` | `boolean` | `false` | Expanded state |
+| `type` | SurfaceMixin type | `'solid'` | Surface type for the container |
+| `rounded` | SurfaceMixin rounded | `'all'` | Corner rounding |
+| `locked` | `boolean` | `false` | Prevents open/close interaction |
+| `overlay` | `boolean` | `false` | Content overlays below instead of pushing |
+| `indicator-placement` | `'start' \| 'end'` | `'end'` | Chevron indicator position |
+| `hide-indicator` | `boolean` | `false` | Hide the expand/collapse indicator |
+| `indicator-rotate` | `number` | `90` | Indicator rotation degrees when open |
+| `summary-padding` | `string` | `'p-3'` | Tailwind padding class for summary |
+| `content-padding` | `string` | `'p-3'` | Tailwind padding class for content |
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `toggle` | `{ open: boolean }` | Fired when open state changes |
+
+## Slots
+| Slot | Description |
+|------|-------------|
+| (default) | Content revealed on expand |
+| `summary` | Custom summary content (overrides `summary` prop) |
+| `indicator` | Custom expand/collapse indicator |
+| `actions` | Action buttons in the summary bar (click does not toggle) |
+| `details` | Additional content slot |
+
+## Physics
+- **magnetic** directive on summary (strength: 2, radius: 50) when not locked
+- Spring-animated chevron indicator using Web Animations API
+- CSS grid transition for smooth height animation (400ms spring easing)
+- Luminous elevation glow when open
+- Lazy rendering: content is not rendered until first opened
+
+## Examples
+```html
+<!-- Basic expandable -->
+<schmancy-details summary="Advanced Settings" indicator-placement="start">
+  <div>Settings content</div>
+</schmancy-details>
+
+<!-- Overlay mode (content floats over siblings) -->
+<schmancy-details summary="Quick preview" overlay>
+  <div>Preview content overlays below</div>
+</schmancy-details>
+
+<!-- With custom summary and actions -->
+<schmancy-details>
+  <span slot="summary">Custom title</span>
+  <schmancy-icon-button slot="actions" icon="edit"></schmancy-icon-button>
+  <div>Detail content</div>
+</schmancy-details>
+```

package/skills/schmancy/dialog.md

@@ -0,0 +1,69 @@
+# schmancy-dialog / $dialog
+
+> Dialog with glass surface, cursorGlow, and mobile bottom-sheet adaptation. Use `$dialog` service for imperative usage.
+
+## Usage
+```typescript
+import { $dialog } from '@mhmo91/schmancy'
+
+// Confirm dialog
+const confirmed = await $dialog.confirm({
+  title: 'Delete item?',
+  message: 'This cannot be undone.',
+  confirmText: 'Delete',
+  cancelText: 'Cancel',
+  variant: 'danger',
+})
+
+// Component dialog (renders any template/element)
+await $dialog.component(html`<my-editor .data=${item}></my-editor>`)
+```
+
+## $dialog API
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `confirm(options)` | `Promise<boolean>` | Show confirm dialog with title/message/buttons |
+| `ask(message, event?)` | `Promise<boolean>` | Quick confirm with just a message |
+| `danger(options)` | `Promise<boolean>` | Confirm with danger variant |
+| `component(content, options?)` | `Promise<boolean>` | Show any template/element as dialog |
+| `prompt(options)` | `Promise<string \| null>` | Input dialog, returns value or null |
+| `dismiss()` | `boolean` | Dismiss topmost dialog |
+
+## Confirm Options
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `title` | `string` | `undefined` | Dialog title |
+| `subtitle` | `string` | `undefined` | Subtitle below title |
+| `message` | `string` | `undefined` | Body message |
+| `confirmText` | `string` | `'Confirm'` | Confirm button label |
+| `cancelText` | `string` | `'Cancel'` | Cancel button label |
+| `variant` | `'default' \| 'danger'` | `'default'` | Button color scheme |
+| `position` | `{x,y} \| MouseEvent` | Last click | Animation origin |
+| `content` | `TemplateResult \| HTMLElement` | `undefined` | Custom content in body |
+
+## Physics
+- **cursorGlow** on dialog surface (radius: 250, intensity: 0.1)
+- Glass surface with `backdrop-blur-lg` and `backdrop-saturate-150`
+- Luminous glow shadow around dialog container
+- Mobile: renders as bottom sheet with drag handle and swipe dismiss
+
+## Examples
+```typescript
+// Quick ask
+if (await $dialog.ask('Remove this entry?', event)) {
+  removeEntry()
+}
+
+// Prompt for input
+const name = await $dialog.prompt({
+  title: 'Rename',
+  label: 'New name',
+  defaultValue: currentName,
+})
+
+// Custom component dialog
+await $dialog.component(
+  html`<user-profile-editor .user=${user}></user-profile-editor>`,
+  { position: event }
+)
+```