@mhmo91/schmancy 0.9.4 → 0.9.5

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

@@ -0,0 +1,56 @@
+# schmancy-input
+
+> Text input with form association, validation strategies, and size variants.
+
+## Usage
+```html
+<schmancy-input label="Email" type="email" required></schmancy-input>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| value | string | `''` | Current input value |
+| type | string | `'text'` | HTML input type (text, password, email, number, date, etc.) |
+| label | string | `''` | Label text above the input |
+| placeholder | string | `''` | Placeholder text |
+| name | string | auto | Form submission name |
+| required | boolean | `false` | Whether the field is required |
+| disabled | boolean | `false` | Whether the field is disabled |
+| readonly | boolean | `false` | Whether the field is read-only |
+| error | boolean | `false` | Whether the field shows an error state |
+| validationMessage | string | `''` | Custom validation message |
+| hint | string | `undefined` | Hint text below the field |
+| size | `'xxs'\|'xs'\|'sm'\|'md'\|'lg'` | `'md'` | Input height (24-56px) |
+| validateOn | `'always'\|'touched'\|'dirty'\|'submitted'` | `'touched'` | When to show validation |
+| align | `'left'\|'center'\|'right'` | `'left'` | Text alignment |
+| pattern | string | `undefined` | Regex validation pattern |
+| inputmode | string | `undefined` | Virtual keyboard hint |
+| min/max | string | `undefined` | Range constraints |
+| minlength/maxlength | number | `undefined` | Length constraints |
+| clickable | boolean | `false` | Show pointer cursor when readonly |
+| autofocus | boolean | `false` | Auto-focus on mount |
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| input | `{ value: string }` | Every keystroke |
+| change | `{ value: string }` | On blur/native change |
+| enter | `{ value: string }` | When Enter key is pressed |
+
+## Examples
+```html
+<!-- Password with validation -->
+<schmancy-input label="Password" type="password" required minlength="8"
+  hint="At least 8 characters"></schmancy-input>
+
+<!-- Compact number input -->
+<schmancy-input type="number" size="xs" min="0" max="100"
+  placeholder="Qty"></schmancy-input>
+
+<!-- With enter handler -->
+<schmancy-input label="Search" placeholder="Type and press Enter"
+  @enter=${(e) => search(e.detail.value)}></schmancy-input>
+```
+
+**Tag aliases:** `<sch-input>` (backward compatible)

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

@@ -0,0 +1,36 @@
+# lightbox (directive)
+
+> Lit directive that opens a fullscreen image viewer on click with gallery support and FLIP animation.
+
+## Usage
+```typescript
+import { lightbox } from '@mhmo91/schmancy'
+
+html`<img src="photo.jpg" ${lightbox()} />`
+```
+
+## Parameters
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| options.images | string[] | `undefined` | Array of image URLs for gallery mode |
+| options.index | number | `0` | Starting image index in gallery |
+| options.overlay | TemplateResult | `undefined` | Custom overlay template on image |
+
+## Examples
+```html
+<!-- Single image -->
+<img src="photo.jpg" ${lightbox()} />
+
+<!-- Gallery with multiple images -->
+<img src="thumb1.jpg" ${lightbox({
+  images: ['full1.jpg', 'full2.jpg', 'full3.jpg'],
+  index: 0
+})} />
+
+<!-- With overlay content -->
+<img src="photo.jpg" ${lightbox({
+  overlay: html`<div class="absolute bottom-4 left-4 text-white">Caption</div>`
+})} />
+```
+
+Features: FLIP animation from click position, keyboard navigation (Escape, Arrow keys), gallery counter, backdrop blur. Click image or press Escape to close.

package/skills/schmancy/list.md

@@ -0,0 +1,67 @@
+# schmancy-list / schmancy-list-item
+
+> List container with list items that have glass hover glow, spring press, and selected state with secondary glow.
+
+## Usage
+```html
+<schmancy-list>
+  <schmancy-list-item>Item 1</schmancy-list-item>
+  <schmancy-list-item selected>Item 2</schmancy-list-item>
+</schmancy-list>
+```
+
+## Properties (schmancy-list)
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `surface` | `TSurfaceColor` | `undefined` | Surface color type, provided to children via context |
+| `fill` | `SchmancySurfaceFill` | `'auto'` | Surface fill style |
+| `elevation` | `0-5` | `0` | Surface elevation level |
+
+## Properties (schmancy-list-item)
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `selected` | `boolean` | `false` | Selected state with secondary glow |
+| `readonly` | `boolean` | `false` | Disables interaction (no hover, no cursor) |
+| `rounded` | `boolean` | `false` | Rounded corners |
+
+## Slots (schmancy-list-item)
+| Slot | Description |
+|------|-------------|
+| (default) | Item content |
+| `leading` | Leading content (images auto-sized to 16-20px) |
+| `trailing` | Trailing content (images auto-sized to 16-20px) |
+
+## Physics
+- Hover: glass background (`surface-on` at 8%) + subtle primary glow shadow
+- Active: spring compress `scale(0.98)` with 100ms transition
+- Selected: secondary container background at 30% + secondary glow shadow
+- No resting background on unselected items (transparent)
+
+## Examples
+```html
+<!-- Basic list with selection -->
+<schmancy-list>
+  ${repeat(items, item => item.id, item => html`
+    <schmancy-list-item
+      ?selected=${item.id === selectedId}
+      @click=${() => this.select(item.id)}
+    >
+      ${item.name}
+    </schmancy-list-item>
+  `)}
+</schmancy-list>
+
+<!-- List with leading/trailing slots -->
+<schmancy-list surface="surface">
+  <schmancy-list-item>
+    <schmancy-icon slot="leading">person</schmancy-icon>
+    User Name
+    <schmancy-icon slot="trailing">chevron_right</schmancy-icon>
+  </schmancy-list-item>
+</schmancy-list>
+
+<!-- Readonly list -->
+<schmancy-list>
+  <schmancy-list-item readonly>Display only</schmancy-list-item>
+</schmancy-list>
+```

package/skills/schmancy/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>
+```

package/skills/schmancy/map.md

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

package/skills/schmancy/menu.md

@@ -0,0 +1,39 @@
+# schmancy-menu
+
+> Context menu that opens a dialog with menu items positioned at the click location.
+
+## Usage
+```html
+<schmancy-menu>
+  <schmancy-button slot="trigger">Actions</schmancy-button>
+  <schmancy-menu-item @click=${() => edit()}>Edit</schmancy-menu-item>
+  <schmancy-menu-item @click=${() => remove()}>Delete</schmancy-menu-item>
+</schmancy-menu>
+```
+
+## Slots
+| Slot | Description |
+|------|-------------|
+| trigger | Button that opens the menu (clicks open dialog) |
+| button | Legacy alias for trigger |
+| default | Menu items or custom content |
+
+## schmancy-menu-item
+Auto-dismisses the dialog when clicked. Renders as a `schmancy-list-item` internally.
+
+## Examples
+```html
+<!-- With icon button trigger -->
+<schmancy-menu>
+  <schmancy-icon-button slot="trigger">more_vert</schmancy-icon-button>
+  <schmancy-menu-item @click=${() => duplicate()}>Duplicate</schmancy-menu-item>
+  <schmancy-menu-item @click=${() => archive()}>Archive</schmancy-menu-item>
+</schmancy-menu>
+
+<!-- Default trigger (three-dot icon button) -->
+<schmancy-menu>
+  <schmancy-menu-item @click=${() => share()}>Share</schmancy-menu-item>
+</schmancy-menu>
+```
+
+Uses `$dialog.component()` internally. Menu items auto-dismiss the dialog. Custom components in the default slot must call `$dialog.dismiss()` manually.

package/skills/schmancy/mixins.md

@@ -0,0 +1,99 @@
+# `$LitElement`
+
+Base class for Schmancy components. Extends `LitElement` with RxJS cleanup, Tailwind support, and cross-shadow discovery.
+
+## Usage
+
+```typescript
+import { $LitElement } from '@mhmo91/schmancy/mixins'
+import { customElement } from 'lit/decorators.js'
+import { css, html } from 'lit'
+
+@customElement('my-component')
+class MyComponent extends $LitElement(css`
+  :host { display: block; }
+`) {
+  render() {
+    return html`<slot></slot>`
+  }
+}
+```
+
+`$LitElement(style?)` accepts either a Lit `css` tagged literal or a string (e.g. SCSS imported with `?inline`).
+
+## Provided members
+
+### `disconnecting: Subject<void>`
+Emits once when the element disconnects. Pair with `takeUntil` for cleanup:
+
+```typescript
+connectedCallback() {
+  super.connectedCallback()
+  someObservable$.pipe(
+    takeUntil(this.disconnecting),
+  ).subscribe()
+}
+```
+
+### `classMap(obj)`
+Wraps Lit's `classMap` so keys can be space-separated:
+
+```typescript
+html`<div class=${this.classMap({
+  'flex items-center gap-2': true,
+  'opacity-50': this.disabled,
+})}></div>`
+```
+
+Must be the only expression in `class=` — don't mix with string interpolation.
+
+### `styleMap(obj)`
+Passthrough to Lit's `styleMap`.
+
+```typescript
+html`<div style=${this.styleMap({ width: `${w}px` })}></div>`
+```
+
+### `discover<T>(tag): Observable<T | null>`
+Find another Schmancy component by tag via event-based handshake. Works across shadow DOM.
+
+```typescript
+this.discover<SchmancyDialog>('schmancy-dialog').pipe(
+  takeUntil(this.disconnecting),
+).subscribe(dialog => dialog?.setDefaultAction('confirm'))
+```
+
+### Auto-response to discovery
+Every `$LitElement` responds to `{its-tag}-where-are-you` events with `{its-tag}-here-i-am` carrying `{ detail: { component: this } }`.
+
+## Component skeleton
+
+```typescript
+@customElement('my-component')
+export class MyComponent extends $LitElement(css`:host { display: block }`) {
+  @property({ type: String, reflect: true }) variant: 'a' | 'b' = 'a'
+  @state() private _open = false
+
+  connectedCallback() {
+    super.connectedCallback()
+    // subscriptions here, with takeUntil(this.disconnecting)
+  }
+
+  render() {
+    return html`<slot></slot>`
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'my-component': MyComponent
+  }
+}
+```
+
+## Rules
+
+- Call `super.connectedCallback()` / `super.disconnectedCallback()` when overriding.
+- All RxJS subscriptions end with `.pipe(takeUntil(this.disconnecting))`.
+- Register the tag in `HTMLElementTagNameMap` for TypeScript.
+- Don't mix `classMap` with string interpolation in the same attribute.

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