@mhmo91/schmancy 0.9.4 → 0.9.6

package/skills/schmancy/nav-drawer.md

@@ -0,0 +1,52 @@
+# schmancy-nav-drawer
+
+> Responsive navigation drawer that switches between push (desktop) and overlay (mobile) modes.
+
+## Usage
+```html
+<schmancy-nav-drawer breakpoint="md">
+  <schmancy-nav-drawer-navbar>
+    <!-- Navigation rail or sidebar content -->
+  </schmancy-nav-drawer-navbar>
+  <schmancy-nav-drawer-content>
+    <!-- Main content area -->
+  </schmancy-nav-drawer-content>
+</schmancy-nav-drawer>
+```
+
+## Properties (schmancy-nav-drawer)
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| breakpoint | `'sm'\|'md'\|'lg'\|'xl'` | `'md'` | Responsive breakpoint for push/overlay switch |
+| open | `'open'\|'close'` | auto | Drawer state |
+| fullscreen | boolean | `false` | Fullscreen mode (hides sidebar) |
+
+## Child Components
+| Component | Description |
+|-----------|-------------|
+| `schmancy-nav-drawer-navbar` | Sidebar container (auto-hides in overlay mode) |
+| `schmancy-nav-drawer-content` | Main content area (fills remaining space) |
+
+## Behavior
+- Above breakpoint: push mode (sidebar pushes content)
+- Below breakpoint: overlay mode (sidebar overlays content)
+- Toggle via `SchmancyEvents.NavDrawer_toggle` event
+- Grid layout: `auto 1fr` columns
+
+## Examples
+```html
+<schmancy-nav-drawer breakpoint="lg">
+  <schmancy-nav-drawer-navbar>
+    <schmancy-navigation-rail activeIndex="0">
+      <schmancy-navigation-rail-item icon="home" label="Home">
+      </schmancy-navigation-rail-item>
+    </schmancy-navigation-rail>
+  </schmancy-nav-drawer-navbar>
+  <schmancy-nav-drawer-content>
+    <schmancy-area name="main" default="home-page">
+      <schmancy-route when="home-page" .component=${lazy(() => import('./home'))}>
+      </schmancy-route>
+    </schmancy-area>
+  </schmancy-nav-drawer-content>
+</schmancy-nav-drawer>
+```

package/skills/schmancy/navigation-bar.md

@@ -0,0 +1,48 @@
+# schmancy-navigation-bar
+
+> Horizontal bottom navigation bar for mobile with 3-7 destinations, auto-hide on scroll, and fullscreen support.
+
+## Usage
+```html
+<schmancy-navigation-bar activeIndex="0" class="fixed bottom-0 left-0 right-0">
+  <schmancy-navigation-bar-item icon="home" label="Home"></schmancy-navigation-bar-item>
+  <schmancy-navigation-bar-item icon="search" label="Search"></schmancy-navigation-bar-item>
+  <schmancy-navigation-bar-item icon="settings" label="Settings"></schmancy-navigation-bar-item>
+</schmancy-navigation-bar>
+```
+
+## Properties (schmancy-navigation-bar)
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| activeIndex | number | `-1` | Currently active item index |
+| hideLabels | boolean | `false` | Hide labels, show only icons |
+| elevation | number (0-5) | `2` | Shadow elevation |
+| hideOnScroll | boolean | `false` | Auto-hide on scroll down |
+
+## Properties (schmancy-navigation-bar-item)
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| icon | string | `''` | Material Symbols icon name |
+| label | string | `''` | Item label text |
+| badge | string | `''` | Badge content (number or text) |
+| active | boolean | `false` | Whether this item is active |
+| disabled | boolean | `false` | Whether this item is disabled |
+| hideLabels | boolean | `false` | Whether to hide the label |
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| navigation-change | `{ oldIndex, newIndex, item }` | When active item changes |
+
+## Examples
+```html
+<!-- With badges and scroll-hide -->
+<schmancy-navigation-bar activeIndex="0" hideOnScroll>
+  <schmancy-navigation-bar-item icon="inbox" label="Inbox" badge="5">
+  </schmancy-navigation-bar-item>
+  <schmancy-navigation-bar-item icon="favorite" label="Favorites">
+  </schmancy-navigation-bar-item>
+</schmancy-navigation-bar>
+```
+
+Automatically hides in fullscreen mode. Consumer must position the bar (e.g., `class="fixed bottom-0 left-0 right-0"`).

package/skills/schmancy/navigation-rail.md

@@ -0,0 +1,62 @@
+# schmancy-navigation-rail
+
+> Vertical navigation rail for desktop with 3-7 destinations, expand/collapse, and badge support.
+
+## Usage
+```html
+<schmancy-navigation-rail activeIndex="0">
+  <schmancy-navigation-rail-item icon="home" label="Home"></schmancy-navigation-rail-item>
+  <schmancy-navigation-rail-item icon="search" label="Search"></schmancy-navigation-rail-item>
+  <schmancy-navigation-rail-item icon="settings" label="Settings"></schmancy-navigation-rail-item>
+</schmancy-navigation-rail>
+```
+
+## Properties (schmancy-navigation-rail)
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| activeIndex | number | `-1` | Currently active item index |
+| activeValue | string | `''` | Active item by value string |
+| labelVisibility | `'all'\|'selected'\|'none'` | `'all'` | When to show labels |
+| alignment | `'top'\|'center'\|'bottom'` | `'top'` | Item vertical alignment |
+| expanded | boolean | `false` | Expanded width (240px vs 80px) |
+| keyboardNavigation | boolean | `true` | Enable arrow key navigation |
+
+## Slots
+| Slot | Description |
+|------|-------------|
+| fab | Floating action button at top |
+| menu | Menu button below FAB |
+| header | Custom header content |
+| footer | Custom footer content |
+| default | Navigation rail items |
+
+## Properties (schmancy-navigation-rail-item)
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| icon | string | `''` | Material Symbols icon name |
+| label | string | `''` | Item label text |
+| value | string | `''` | Value for routing |
+| active | boolean | `false` | Whether active |
+| badge | string | `''` | Badge text |
+| badgeVariant | `'error'\|'primary'\|'secondary'` | `'error'` | Badge color |
+| disabled | boolean | `false` | Whether disabled |
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| navigate | string | Item value when clicked |
+
+## Examples
+```html
+<schmancy-navigation-rail activeIndex="0" alignment="top">
+  <schmancy-button slot="fab" variant="filled">
+    <schmancy-icon>add</schmancy-icon>
+  </schmancy-button>
+  <schmancy-navigation-rail-item icon="dashboard" label="Dashboard" value="dash">
+  </schmancy-navigation-rail-item>
+  <schmancy-navigation-rail-item icon="people" label="Users" value="users" badge="3">
+  </schmancy-navigation-rail-item>
+</schmancy-navigation-rail>
+```
+
+Automatically hides in fullscreen mode. Width is 80px collapsed, 240px expanded.

package/skills/schmancy/notification.md

@@ -0,0 +1,60 @@
+# $notify
+
+> Notification service with type-colored luminous glow, progress bar countdown, and arc-path entry animation.
+
+## Usage
+```typescript
+import { $notify } from '@mhmo91/schmancy'
+
+$notify.success('Item saved')
+$notify.error('Failed to connect')
+```
+
+## $notify API
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `success(message?, options?)` | `string` (id) | Green glow, 1.5s duration |
+| `error(message?, options?)` | `string` (id) | Red glow, 2.5s duration |
+| `warning(message?, options?)` | `string` (id) | Orange glow, 2.5s duration |
+| `info(message?, options?)` | `string` (id) | Blue glow, 2s duration |
+| `show(options)` | `string` (id) | Full options control |
+| `persistent(message, options?)` | `string` (id) | No auto-dismiss (duration: 0) |
+| `customDuration(msg, ms, options?)` | `string` (id) | Custom duration in ms |
+| `dismiss(id?)` | `void` | Dismiss by id or most recent |
+| `update(id, options)` | `void` | Update existing notification content |
+
+## Options
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `message` | `string` | required | Notification body text |
+| `title` | `string` | `undefined` | Optional title line |
+| `type` | `'info' \| 'success' \| 'warning' \| 'error'` | `'info'` | Notification type |
+| `duration` | `number` | Type-specific | Auto-dismiss ms (0 = persistent) |
+| `closable` | `boolean` | `true` | Show close button |
+| `playSound` | `boolean` | `true` | Play type-specific sound |
+| `showProgress` | `boolean` | `false` | Show indeterminate progress bar |
+
+## Physics
+- Type-colored luminous glow shadow (18% intensity, 28% on hover)
+- Arc-path entry animation from last click position to top-right corner
+- Hover: glow intensifies + `translateY(-2px)` lift
+- Progress bar shows countdown timer; pauses on hover
+- Only one notification visible at a time (replaces previous)
+
+## Examples
+```typescript
+// Success with title
+$notify.success('Changes saved', { title: 'Success' })
+
+// Persistent loading indicator
+const id = $notify.persistent('Processing...', { showProgress: true })
+// Later: dismiss it
+$notify.dismiss(id)
+
+// Error with longer duration
+$notify.error('Connection lost', { duration: 5000 })
+
+// Update existing notification
+const nid = $notify.info('Uploading...')
+$notify.update(nid, { message: 'Upload complete', type: 'success' })
+```

package/skills/schmancy/option.md

@@ -0,0 +1,43 @@
+# schmancy-option
+
+> Selectable item for `schmancy-select`, `schmancy-autocomplete`, and `schmancy-menu`. Lightweight and a11y-ready.
+
+## Usage
+```html
+<schmancy-select label="Country">
+  <schmancy-option value="us">United States</schmancy-option>
+  <schmancy-option value="de">Germany</schmancy-option>
+  <schmancy-option value="jp" disabled>Japan</schmancy-option>
+</schmancy-select>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `value` | string | `''` | Value reported when this option is selected |
+| `label` | string | auto | Display label (falls back to text content) |
+| `selected` | boolean | `false` | Reflects selected state |
+| `disabled` | boolean | `false` | Disables interaction |
+| `group` | string | `''` | Grouping identifier for grouped lists |
+| `icon` | string | `''` | Material icon name before the label |
+
+## Events
+| Event | Payload | When |
+|-------|---------|------|
+| `click` | — | Standard click event |
+| `option-select` | `CustomEvent<{ value, label }>` | Dispatched on activation |
+
+## Behavior
+- Auto-generates `id` for ARIA wiring if not set.
+- Infers `label` from text content when omitted.
+- Keyboard focusable with a visible focus ring via `:focus-visible`.
+- Parent select/autocomplete coordinates selection state via slot query.
+
+## Example — grouped options
+```html
+<schmancy-select label="Framework">
+  <schmancy-option value="lit" group="web" icon="bolt">Lit</schmancy-option>
+  <schmancy-option value="react" group="web">React</schmancy-option>
+  <schmancy-option value="swift" group="mobile">Swift</schmancy-option>
+</schmancy-select>
+```

package/skills/schmancy/page.md

@@ -0,0 +1,42 @@
+# schmancy-page
+
+> Native mobile-like page container. Fills remaining viewport height, prevents rubber-banding, pull-to-refresh, and double-tap zoom.
+
+## Usage
+```html
+<schmancy-page rows="auto_1fr_auto">
+  <header>App bar</header>
+  <main>Scrollable content</main>
+  <footer>Bottom nav</footer>
+</schmancy-page>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `rows` | string | `'auto_1fr_auto'` | Grid template rows — underscores become spaces (e.g. `'1fr_2fr_auto'`) |
+| `show-scrollbar` | boolean | `false` | Display scrollbar on scrollable area |
+| `no-select` | boolean | `false` | Disable text selection |
+
+## Behavior
+- Listens to `visualViewport` resize/scroll + `orientationchange` + keyboard focus events to recompute height.
+- Accounts for theme bottom offset (iOS safe area, home indicator).
+- Auto-assigns semantic elements (`header`, `main`, `footer`) to slots.
+- Inner scroll area uses `schmancy-scroll` for momentum-preserving scroll.
+
+## When to Use
+- Root of a mobile view or panel that should feel like a native page.
+- Any container where viewport-aware height + scroll containment matters.
+
+## Example — 3-row app shell
+```html
+<schmancy-page rows="auto_1fr_auto">
+  <schmancy-surface type="solid" rounded="none">
+    <schmancy-typography type="title">My App</schmancy-typography>
+  </schmancy-surface>
+
+  <div class="p-4">…scrollable content…</div>
+
+  <schmancy-navigation-bar></schmancy-navigation-bar>
+</schmancy-page>
+```

package/skills/schmancy/progress.md

@@ -0,0 +1,30 @@
+# schmancy-progress
+
+> Linear progress bar with determinate and indeterminate modes, color variants, and glass effect.
+
+## Usage
+```html
+<schmancy-progress value="60" max="100"></schmancy-progress>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| value | number | `0` | Current progress value |
+| max | number | `100` | Maximum value |
+| indeterminate | boolean | `false` | Show indeterminate animation |
+| size | `'xs'\|'sm'\|'md'\|'lg'` | `'md'` | Track height (1px, 2px, 4px, 8px) |
+| color | `'primary'\|'secondary'\|'tertiary'\|'error'\|'success'` | `'primary'` | Bar color |
+| glass | boolean | `false` | Glass/frosted effect |
+
+## Examples
+```html
+<!-- Indeterminate loading -->
+<schmancy-progress indeterminate color="secondary"></schmancy-progress>
+
+<!-- Glass effect progress -->
+<schmancy-progress value="75" glass size="lg" color="success"></schmancy-progress>
+
+<!-- Thin track -->
+<schmancy-progress value="30" size="xs"></schmancy-progress>
+```

package/skills/schmancy/qr-scanner.md

@@ -0,0 +1,51 @@
+# schmancy-qr-scanner
+
+> Camera-based QR code scanner using `jsQR`. Requests rear-camera access, decodes frames in real time, deduplicates reads.
+
+## Usage
+```html
+<schmancy-qr-scanner
+  continuous
+  @scan-result=${e => this.handleScan(e.detail.data)}
+></schmancy-qr-scanner>
+```
+
+```typescript
+handleScan(data: string) {
+  console.log('QR decoded:', data)
+}
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `continuous` | boolean | `true` | Keep scanning after a successful read (dedupe repeated reads) |
+
+## Events
+| Event | Detail | When |
+|-------|--------|------|
+| `scan-result` | `{ data: string, timestamp: number }` | QR code successfully decoded |
+
+## Behavior
+- Requests `getUserMedia` with `facingMode: 'environment'` (rear camera) at 1280×720.
+- Decodes via `jsQR` on `animationFrames` stream with `throttleTime` to avoid CPU thrashing.
+- `distinctUntilChanged` prevents duplicate emissions for the same code.
+- Brief success flash on each valid read.
+- Stops camera + tears down subscriptions on disconnect.
+- Displays an error state if camera permission is denied.
+
+## Requires
+- HTTPS (or `localhost`) for camera access.
+- User permission to the camera.
+
+## Example
+```html
+<schmancy-surface type="glass" rounded="all">
+  <schmancy-qr-scanner
+    @scan-result=${(e: CustomEvent<{ data: string }>) => {
+      $notify.success(`Scanned: ${e.detail.data}`)
+      this.scannedCode = e.detail.data
+    }}
+  ></schmancy-qr-scanner>
+</schmancy-surface>
+```

package/skills/schmancy/radio-group.md

@@ -0,0 +1,50 @@
+# schmancy-radio-group
+
+> Radio button group with options array or slotted radio buttons.
+
+## Usage
+```html
+<!-- With options array -->
+<schmancy-radio-group label="Size" name="size"
+  .options=${[{label: 'Small', value: 's'}, {label: 'Large', value: 'l'}]}
+  @change=${(e) => handle(e.detail.value)}>
+</schmancy-radio-group>
+```
+
+## Properties (schmancy-radio-group)
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| value | string | `''` | Currently selected value |
+| label | string | `''` | Group label |
+| name | string | `''` | Form submission name |
+| options | `{label: string, value: string}[]` | `[]` | Radio options |
+| required | boolean | `false` | Whether selection is required |
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| change | `{ value: string }` | When selection changes |
+
+## Properties (schmancy-radio-button)
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| value | string | `''` | Button value |
+| checked | boolean | `false` | Whether selected |
+| disabled | boolean | `false` | Whether disabled |
+| name | string | `''` | Group name |
+
+## Examples
+```html
+<!-- With slotted radio buttons -->
+<schmancy-radio-group label="Priority" name="priority" value="medium">
+  <schmancy-radio-button value="low">
+    <span slot="label">Low</span>
+  </schmancy-radio-button>
+  <schmancy-radio-button value="medium">
+    <span slot="label">Medium</span>
+  </schmancy-radio-button>
+  <schmancy-radio-button value="high">
+    <span slot="label">High</span>
+  </schmancy-radio-button>
+</schmancy-radio-group>
+```

package/skills/schmancy/range.md

@@ -0,0 +1,47 @@
+# schmancy-range
+
+> Numeric slider input with theme-driven track gradient and focus halo.
+
+## Usage
+```html
+<schmancy-range
+  label="Volume"
+  min="0"
+  max="100"
+  step="1"
+  .value=${50}
+  @change=${e => this.volume = e.detail.value}
+></schmancy-range>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `min` | number | `0` | Minimum value |
+| `max` | number | `1` | Maximum value |
+| `step` | number | `0.01` | Increment per tick |
+| `value` | number | `0` | Current value |
+| `label` | string | — | Optional label (current value displays on the right) |
+| `disabled` | boolean | `false` | Disabled state (38% opacity) |
+
+## Events
+| Event | Payload | When |
+|-------|---------|------|
+| `change` | `{ value: number }` | On input change |
+
+## Visual
+- Primary-colored track gradient (filled portion = primary, empty = 30% primary).
+- Circular thumb with hover halo (8px primary glow at 12% opacity).
+- Disabled state: 38% opacity, not-allowed cursor.
+
+## Example — precise float control
+```html
+<schmancy-range
+  label="Mass"
+  min="0.5"
+  max="2.0"
+  step="0.05"
+  .value=${this.mass}
+  @change=${(e: CustomEvent<{ value: number }>) => this.mass = e.detail.value}
+></schmancy-range>
+```

package/skills/schmancy/rxjs-utils.md

@@ -0,0 +1,60 @@
+# Schmancy RxJS Utils
+
+> RxJS-wrapped DOM observation helpers. Use when you need to react to elements appearing, disappearing, or changing across the document.
+
+## Imports
+```typescript
+import {
+  mutationObserver,
+  waitForElement,
+  waitForElementAll,
+  waitForElements,
+  waitForElementsAll,
+  waitUntil,
+} from '@mhmo91/schmancy'
+```
+
+## `mutationObserver(target, options?)`
+RxJS wrapper around `MutationObserver`.
+```typescript
+mutationObserver(document.body, { childList: true, subtree: true })
+  .pipe(takeUntil(this.disconnecting))
+  .subscribe(mutations => { /* react */ })
+```
+
+## `waitForElement(selector, timeout = 5000)`
+Emits the first matching element once it exists in the DOM. Throws on timeout. Pass `undefined` to wait forever.
+```typescript
+waitForElement('#auth-banner').subscribe(el => el.focus())
+waitForElement('.lazy-panel', 10000).subscribe(el => el.click())
+```
+
+## `waitForElementAll(selector, timeout?)`
+Emits whenever the matching set changes (all current matches).
+```typescript
+waitForElementAll('.live-tile').subscribe(tiles => {
+  tiles.forEach(t => observe(t))
+})
+```
+
+## `waitForElements([sel1, sel2, ...], timeout?)` / `waitForElementsAll`
+Multi-selector variants — resolve once *any*/`every` selector is present.
+
+## `waitUntil([selectors], timeout = 5000)`
+Emits once when **all** selectors have matches. Throws on timeout.
+```typescript
+waitUntil(['header', 'main', 'footer'])
+  .subscribe(() => console.log('Page shell ready'))
+```
+
+## How It Works
+All helpers share `mutationObserver(document.body)` with `childList: true, subtree: true` and `.startWith(document.body)` so they check once immediately and re-check on every DOM mutation.
+
+## When to Use
+- Integrating third-party scripts that inject DOM late.
+- Coordinating with slot-projected children that may mount asynchronously.
+- Awaiting app-shell elements before attaching shortcuts.
+
+## When NOT to Use
+- Inside your own component — use `firstUpdated()` or `queryAssignedElements`.
+- For cross-shadow discovery — use [discovery](./discovery.md) instead.

package/skills/schmancy/select.md

@@ -0,0 +1,49 @@
+# schmancy-select
+
+> Dropdown select with single and multi-select support, keyboard navigation, and form association.
+
+## Usage
+```html
+<schmancy-select label="Country" placeholder="Choose..." required>
+  <schmancy-option value="us" label="United States"></schmancy-option>
+  <schmancy-option value="de" label="Germany"></schmancy-option>
+</schmancy-select>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| value | string \| string[] | `''` | Selected value(s) |
+| values | string[] | `[]` | Selected values (multi-select) |
+| label | string | `''` | Label text |
+| placeholder | string | `''` | Placeholder when no selection |
+| name | string | `undefined` | Form submission name |
+| required | boolean | `false` | Whether selection is required |
+| disabled | boolean | `false` | Whether the select is disabled |
+| multi | boolean | `false` | Enable multi-select mode |
+| hint | string | `''` | Hint text below the select |
+| size | `'xxs'\|'xs'\|'sm'\|'md'\|'lg'` | `'md'` | Input height |
+| validateOn | `'always'\|'touched'\|'dirty'\|'submitted'` | `'touched'` | When to show validation |
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| change | `{ value: string \| string[] }` | When selection changes |
+
+## Examples
+```html
+<!-- Multi-select -->
+<schmancy-select label="Tags" multi placeholder="Select tags...">
+  <schmancy-option value="urgent" label="Urgent"></schmancy-option>
+  <schmancy-option value="review" label="Review"></schmancy-option>
+  <schmancy-option value="done" label="Done"></schmancy-option>
+</schmancy-select>
+
+<!-- Compact size -->
+<schmancy-select size="xs" placeholder="Status">
+  <schmancy-option value="active" label="Active"></schmancy-option>
+  <schmancy-option value="inactive" label="Inactive"></schmancy-option>
+</schmancy-select>
+```
+
+Children must be `<schmancy-option>` elements with `value` and `label` attributes.

package/skills/schmancy/sheet.md

@@ -0,0 +1,76 @@
+# schmancy-sheet / sheet
+
+> Side/bottom panel with glass backdrop, luminous edge glow, and spring entry animation. Use `sheet` service for imperative usage.
+
+## Usage
+```typescript
+import { sheet } from '@mhmo91/schmancy'
+
+sheet.push({
+  component: MyComponent,       // Component class or tag name
+  position: SchmancySheetPosition.Side,
+  props: { itemId: '123' },     // Passed to component
+})
+```
+
+## sheet API
+| Method | Description |
+|--------|-------------|
+| `push(config)` | Open a sheet with component content |
+| `dismiss(uid?)` | Close sheet by uid, or most recent |
+| `closeAll()` | Close all open sheets |
+| `isOpen(uid)` | Check if sheet with uid is open |
+
+## SheetConfig
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `component` | `ComponentType` | required | Component class or lazy loader |
+| `uid` | `string` | Auto-generated | Unique identifier for the sheet |
+| `position` | `SchmancySheetPosition` | Auto (side on desktop, bottom on mobile) | `Side` or `Bottom` |
+| `persist` | `boolean` | `false` | Keep DOM after close |
+| `lock` | `boolean` | `false` | Prevent ESC and overlay click dismiss |
+| `props` | `Record<string, unknown>` | `undefined` | Properties passed to component |
+| `close` | `() => void` | `undefined` | Close callback |
+
+## Component Properties (schmancy-sheet)
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `open` | `boolean` | `false` | Open state |
+| `position` | `'side' \| 'bottom'` | `'side'` | Panel position |
+| `persist` | `boolean` | `false` | Keep in DOM after close |
+| `lock` | `boolean` | `false` | Disable dismiss via ESC/overlay |
+| `handleHistory` | `boolean` | `true` | Handle browser back button |
+
+## Events
+| Event | Description |
+|-------|-------------|
+| `close` | Fired when sheet closes |
+
+## Physics
+- Glass backdrop: `backdrop-blur-lg` + `backdrop-saturate-150`
+- Luminous edge glow on panel (primary color, 15% intensity)
+- Spring entry: `scale(0.95)` to `scale(1)` with Blackbird easing
+- Side: slides from right; Bottom: slides from bottom
+- Background siblings set to `inert` while open
+- Stacks with dialogs via shared `overlayStack` z-index manager
+
+## Examples
+```typescript
+import { sheet, SchmancySheetPosition } from '@mhmo91/schmancy'
+
+// Open side sheet
+sheet.push({
+  component: UserEditor,
+  props: { userId: '456' },
+})
+
+// Locked bottom sheet
+sheet.push({
+  component: PaymentForm,
+  position: SchmancySheetPosition.Bottom,
+  lock: true,
+})
+
+// Dismiss programmatically
+sheet.dismiss()
+```