@mhmo91/schmancy 0.8.6 → 0.9.3

package/dist/ai/discovery.md

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

package/dist/ai/divider.md

@@ -1,153 +1,31 @@
-# Divider Component
+# schmancy-divider
 
-A sleek animated divider component that provides visual separation between content sections with customizable orientation and animation effects.
-
-## Quick Start
+> Horizontal or vertical divider line with grow animation.
 
+## Usage
 ```html
-<!-- Basic horizontal divider -->
 <schmancy-divider></schmancy-divider>
-
-<!-- Vertical divider -->
-<schmancy-divider orientation="vertical"></schmancy-divider>
-
-<!-- Animated from center -->
-<schmancy-divider grow="both"></schmancy-divider>
 ```
 
 ## Properties
-
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `outline` | `'default' \| 'variant'` | `'variant'` | Color style of the divider |
-| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Divider direction |
-| `grow` | `'start' \| 'end' \| 'both'` | `'start'` | Animation growth direction |
+| vertical | boolean | `false` | Vertical orientation (use inside flex/grid) |
+| outline | `'default'\|'variant'` | `'variant'` | Line color intensity |
+| grow | `'start'\|'end'\|'both'` | `'start'` | Animation origin direction |
 
 ## Examples
-
-### Section Separators
 ```html
-<schmancy-surface>
-  <h2>Section One</h2>
-  <p>Content for the first section...</p>
-  
-  <schmancy-divider class="my-6"></schmancy-divider>
-  
-  <h2>Section Two</h2>
-  <p>Content for the second section...</p>
-</schmancy-surface>
-```
+<!-- Horizontal divider -->
+<schmancy-divider></schmancy-divider>
 
-### Sidebar Layout
-```html
-<div class="flex">
-  <nav class="w-64 p-4">
-    <!-- Navigation items -->
-  </nav>
-  
-  <schmancy-divider orientation="vertical" class="h-screen"></schmancy-divider>
-  
-  <main class="flex-1 p-4">
-    <!-- Main content -->
-  </main>
+<!-- Vertical divider in a flex container -->
+<div class="flex items-stretch h-16">
+  <span>Left</span>
+  <schmancy-divider vertical></schmancy-divider>
+  <span>Right</span>
 </div>
-```
-
-### Animated List Separators
-```html
-<schmancy-list>
-  ${items.map((item, index) => html`
-    <schmancy-list-item>${item.name}</schmancy-list-item>
-    ${index < items.length - 1 ? html`
-      <schmancy-divider 
-        grow="both" 
-        style="--animation-duration: 0.3s"
-      ></schmancy-divider>
-    ` : ''}
-  `)}
-</schmancy-list>
-```
-
-### Card with Sections
-```html
-<schmancy-card>
-  <div slot="header">
-    <h3>User Profile</h3>
-  </div>
-  
-  <div>
-    <p>Name: John Doe</p>
-    <p>Email: john@example.com</p>
-  </div>
-  
-  <schmancy-divider outline="default" class="my-4"></schmancy-divider>
-  
-  <div>
-    <h4>Recent Activity</h4>
-    <ul>
-      <li>Logged in - 2 hours ago</li>
-      <li>Updated profile - Yesterday</li>
-    </ul>
-  </div>
-</schmancy-card>
-```
 
-## Features
-
-### Animation Options
-
-**Growth Direction**:
-- `start`: Animates from start (left/top)
-- `end`: Animates from end (right/bottom)
-- `both`: Animates from center outward
-
-### RTL Support
-The component automatically adjusts animation direction for right-to-left layouts.
-
-### Color Variants
-- `variant`: Uses `outlineVariant` color (subtle)
-- `default`: Uses `outline` color (more prominent)
-
-## Styling
-
-### CSS Custom Properties
-```css
-schmancy-divider {
-  --divider-color: var(--schmancy-sys-color-outlineVariant);
-  --animation-duration: 1s;
-  --transform-origin: left; /* or right, center */
-}
+<!-- Grow from center -->
+<schmancy-divider grow="both"></schmancy-divider>
 ```
-
-### Animation Keyframes
-The component uses CSS animations for smooth drawing effects:
-- Horizontal dividers use `scaleX` transformation
-- Vertical dividers use `scaleY` transformation
-
-## Accessibility
-
-- Uses `aria-hidden="true"` on decorative connector lines
-- Semantic HTML structure
-- No interactive elements
-
-## Related Components
-
-- [Surface](./surface.md) - Container for divided content
-- [Card](./card.md) - Cards with divided sections
-- [List](./list.md) - Lists with dividers
-- [Layout](./layout.md) - Page layout divisions
-
-## Best Practices
-
-1. **Spacing**: Use consistent margin/padding around dividers
-2. **Animation**: Keep animations subtle (300-500ms)
-3. **Contrast**: Ensure sufficient contrast in both light/dark themes
-4. **Semantic HTML**: Use dividers for visual separation, not structural
-
-## Use Cases
-
-1. **Form Sections**: Separate form groups
-2. **Navigation**: Divide menu sections
-3. **Content**: Break up long text content
-4. **Lists**: Separate list items
-5. **Layouts**: Create visual boundaries in layouts

package/dist/ai/dropdown.md

@@ -1,238 +1,47 @@
-# Schmancy Dropdown - AI Reference
+# schmancy-dropdown
 
-```js
-// Basic Dropdown
-<schmancy-dropdown>
-  <schmancy-button slot="trigger">
-    Open Dropdown
-  </schmancy-button>
-  
-  <div slot="content">
-    <div>Dropdown content goes here</div>
-  </div>
-</schmancy-dropdown>
-
-// Dropdown with position
-<schmancy-dropdown
-  position="bottom-start|bottom-end|top-start|top-end|left-start|left-end|right-start|right-end">
-  <schmancy-button slot="trigger">
-    Open Dropdown
-  </schmancy-button>
-  
-  <div slot="content">
-    <div>Positioned dropdown content</div>
-  </div>
-</schmancy-dropdown>
-
-// Dropdown with menu items
-<schmancy-dropdown>
-  <schmancy-button slot="trigger">
-    Options
-  </schmancy-button>
-  
-  <schmancy-menu slot="content">
-    <schmancy-menu-item @click=${handleEdit}>Edit</schmancy-menu-item>
-    <schmancy-menu-item @click=${handleDuplicate}>Duplicate</schmancy-menu-item>
-    <schmancy-menu-item @click=${handleArchive}>Archive</schmancy-menu-item>
-    <schmancy-menu-item disabled>Share</schmancy-menu-item>
-    <schmancy-divider></schmancy-divider>
-    <schmancy-menu-item variant="danger" @click=${handleDelete}>Delete</schmancy-menu-item>
-  </schmancy-menu>
-</schmancy-dropdown>
-
-// Dropdown with custom width and offset
-<schmancy-dropdown
-  width="300px"
-  offset="5">
-  <schmancy-button slot="trigger">
-    Wide Dropdown
-  </schmancy-button>
-  
-  <div slot="content" style="padding: 16px;">
-    <h3>Custom Content</h3>
-    <p>This dropdown has custom width and offset.</p>
-  </div>
-</schmancy-dropdown>
-
-// Dropdown Properties
-position: string        // Position relative to trigger: "bottom-start" (default), "top-end", etc.
-width: string           // Width of the dropdown content
-offset: number          // Distance between trigger and content (pixels)
-open: boolean           // Whether the dropdown is open
-disabled: boolean       // Disable the dropdown
-closeOnSelect: boolean  // Close dropdown when an item inside is selected
-closeOnClickOutside: boolean // Close dropdown when clicking outside
-matchTriggerWidth: boolean   // Make content width match trigger width
-
-// Dropdown Events
-@open    // Fires when dropdown opens
-@close   // Fires when dropdown closes
-@select  // Fires when an item is selected (if using menu items)
-
-// Dropdown Methods
-dropdown.open() -> void    // Programmatically open the dropdown
-dropdown.close() -> void   // Programmatically close the dropdown
-dropdown.toggle() -> void  // Toggle the dropdown state
+> Floating dropdown with trigger slot and auto-positioned content portal.
 
-// Examples
-// Basic dropdown menu
+## Usage
+```html
 <schmancy-dropdown>
-  <schmancy-button slot="trigger">
-    <span>Actions</span>
-    <schmancy-icon slot="suffix" icon="chevron-down"></schmancy-icon>
-  </schmancy-button>
-  
-  <schmancy-menu slot="content">
-    <schmancy-menu-item @click=${viewItem}>
-      <schmancy-icon slot="prefix" icon="eye"></schmancy-icon>
-      View
-    </schmancy-menu-item>
-    
-    <schmancy-menu-item @click=${editItem}>
-      <schmancy-icon slot="prefix" icon="edit"></schmancy-icon>
-      Edit
-    </schmancy-menu-item>
-    
-    <schmancy-divider></schmancy-divider>
-    
-    <schmancy-menu-item variant="danger" @click=${deleteItem}>
-      <schmancy-icon slot="prefix" icon="trash"></schmancy-icon>
-      Delete
-    </schmancy-menu-item>
-  </schmancy-menu>
-</schmancy-dropdown>
-
-// Profile dropdown
-<schmancy-dropdown position="bottom-end">
-  <div slot="trigger" style="cursor: pointer;">
-    <schmancy-avatar
-      src="path/to/avatar.jpg"
-      size="medium">
-    </schmancy-avatar>
-  </div>
-  
-  <div slot="content">
-    <div style="padding: 16px; text-align: center;">
-      <schmancy-avatar
-        src="path/to/avatar.jpg"
-        size="large">
-      </schmancy-avatar>
-      <h3>John Doe</h3>
-      <p>john@example.com</p>
-    </div>
-    
-    <schmancy-divider></schmancy-divider>
-    
-    <schmancy-menu>
-      <schmancy-menu-item @click=${viewProfile}>
-        <schmancy-icon slot="prefix" icon="user"></schmancy-icon>
-        Profile
-      </schmancy-menu-item>
-      
-      <schmancy-menu-item @click=${openSettings}>
-        <schmancy-icon slot="prefix" icon="settings"></schmancy-icon>
-        Settings
-      </schmancy-menu-item>
-      
-      <schmancy-divider></schmancy-divider>
-      
-      <schmancy-menu-item @click=${signOut}>
-        <schmancy-icon slot="prefix" icon="logout"></schmancy-icon>
-        Sign Out
-      </schmancy-menu-item>
-    </schmancy-menu>
-  </div>
-</schmancy-dropdown>
-
-// Dropdown with form
-<schmancy-dropdown>
-  <schmancy-button slot="trigger">
-    Add User
-  </schmancy-button>
-  
-  <div slot="content" style="padding: 16px; width: 300px;">
-    <h3>Add User</h3>
-    <schmancy-form @submit=${(e) => {
-      addUser(e.detail.values);
-      dropdown.close();
-    }}>
-      <schmancy-input
-        name="name"
-        label="Name"
-        required>
-      </schmancy-input>
-      
-      <schmancy-input
-        name="email"
-        label="Email"
-        type="email"
-        required>
-      </schmancy-input>
-      
-      <div style="display: flex; justify-content: flex-end; gap: 8px; margin-top: 16px;">
-        <schmancy-button
-          type="button"
-          variant="tertiary"
-          @click=${() => dropdown.close()}>
-          Cancel
-        </schmancy-button>
-        
-        <schmancy-button
-          type="submit"
-          variant="primary">
-          Add
-        </schmancy-button>
-      </div>
-    </schmancy-form>
-  </div>
-</schmancy-dropdown>
-
-// Icon button dropdown
-<schmancy-dropdown>
-  <schmancy-icon-button
-    slot="trigger"
-    icon="more-vertical">
-  </schmancy-icon-button>
-  
-  <schmancy-menu slot="content">
-    <schmancy-menu-item>Option 1</schmancy-menu-item>
-    <schmancy-menu-item>Option 2</schmancy-menu-item>
-    <schmancy-menu-item>Option 3</schmancy-menu-item>
-  </schmancy-menu>
-</schmancy-dropdown>
-
-// Filter dropdown
-<schmancy-dropdown>
-  <schmancy-button slot="trigger" variant="tertiary">
-    <schmancy-icon slot="prefix" icon="filter"></schmancy-icon>
-    Filter
-  </schmancy-button>
-  
-  <div slot="content" style="padding: 16px; width: 250px;">
-    <h3>Filters</h3>
-    
-    <div style="margin-bottom: 16px;">
-      <label>Status</label>
-      <schmancy-radio-group>
-        <schmancy-radio-button value="all" label="All"></schmancy-radio-button>
-        <schmancy-radio-button value="active" label="Active"></schmancy-radio-button>
-        <schmancy-radio-button value="inactive" label="Inactive"></schmancy-radio-button>
-      </schmancy-radio-group>
-    </div>
-    
-    <div style="margin-bottom: 16px;">
-      <label>Categories</label>
-      <schmancy-checkbox label="Products"></schmancy-checkbox>
-      <schmancy-checkbox label="Services"></schmancy-checkbox>
-      <schmancy-checkbox label="Resources"></schmancy-checkbox>
-    </div>
-    
-    <schmancy-button 
-      variant="primary" 
-      style="width: 100%;"
-      @click=${applyFilters}>
-      Apply Filters
-    </schmancy-button>
-  </div>
-</schmancy-dropdown>
-```
+  <schmancy-button slot="trigger">Open</schmancy-button>
+  <schmancy-dropdown-content>
+    <p>Dropdown content here</p>
+  </schmancy-dropdown-content>
+</schmancy-dropdown>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| open | boolean | `false` | Whether the dropdown is open |
+| placement | string | `'bottom-start'` | Floating UI placement |
+| distance | number | `8` | Offset distance in pixels |
+
+## Placement Values
+`top`, `top-start`, `top-end`, `right`, `right-start`, `right-end`, `bottom`, `bottom-start`, `bottom-end`, `left`, `left-start`, `left-end`
+
+## Methods
+| Method | Description |
+|--------|-------------|
+| toggle() | Toggle open/close state |
+
+## Slots
+| Slot | Description |
+|------|-------------|
+| trigger | Element that opens the dropdown on click |
+| default | Dropdown content |
+
+## Examples
+```html
+<!-- Right-aligned dropdown -->
+<schmancy-dropdown placement="bottom-end">
+  <schmancy-icon-button slot="trigger">more_vert</schmancy-icon-button>
+  <schmancy-dropdown-content>
+    <div class="p-4">Custom content</div>
+  </schmancy-dropdown-content>
+</schmancy-dropdown>
+```
+
+Content is teleported to a portal for proper z-index stacking. Closes on outside click or Escape key.

package/dist/ai/expand.md

@@ -0,0 +1,63 @@
+# schmancy-expand
+
+> Expandable/accordion component. Inline mode uses grid-template-rows transitions; portal mode teleports content to a body-level `schmancy-expand-root` with backdrop.
+
+## Usage
+```html
+<schmancy-expand summary="Details">
+  <p>Content appears when expanded.</p>
+</schmancy-expand>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `summary` | string | `''` | Summary text shown when collapsed |
+| `open` | boolean | `false` | Expansion state (reflected) |
+| `summary-padding` | string | — | CSS padding for the summary row |
+| `content-padding` | string | — | CSS padding for the body |
+| `hide-indicator` | boolean | `false` | Hide the chevron indicator |
+| `indicator-rotate` | number | `90` | Rotation angle (deg) when open |
+| `backdrop` | boolean | `true` | Show semi-transparent backdrop in portal mode |
+| `inline` | boolean | `false` | Inline expansion instead of portal (no backdrop) |
+
+## Slots
+| Slot | Purpose |
+|------|---------|
+| (default) | Expanded content |
+| `summary` | Custom summary markup (overrides `summary` property) |
+
+## Behavior
+- **Portal mode (default)**: on open, content is teleported into a body-anchored `schmancy-expand-root` with a backdrop. Click outside or press `Escape` to close.
+- **Inline mode** (`inline`): uses `grid-template-rows: 0fr → 1fr` transition inside the host — no portal, no backdrop.
+- `SPRING_SNAPPY` physics for indicator rotation.
+- Respects `prefers-reduced-motion`.
+- Broadcast event `SCHMANCY_EXPAND_REQUEST_CLOSE` on `window` closes whichever instance is currently open.
+
+## Example — inline accordion
+```html
+${repeat(this.faqs, faq => faq.id, faq => html`
+  <schmancy-expand inline .summary=${faq.question}>
+    <p>${faq.answer}</p>
+  </schmancy-expand>
+`)}
+```
+
+## Example — portal with custom summary slot
+```html
+<schmancy-expand>
+  <div slot="summary" class="flex items-center gap-2">
+    <schmancy-icon>info</schmancy-icon>
+    <schmancy-typography type="title">Advanced options</schmancy-typography>
+  </div>
+  <div class="p-4">
+    <!-- settings form -->
+  </div>
+</schmancy-expand>
+```
+
+## Programmatic Close
+```typescript
+import { SCHMANCY_EXPAND_REQUEST_CLOSE } from '@mhmo91/schmancy'
+window.dispatchEvent(new Event(SCHMANCY_EXPAND_REQUEST_CLOSE))
+```

package/dist/ai/extra.md

@@ -0,0 +1,59 @@
+# Schmancy Extra
+
+> Data-driven dropdowns for common localization fields. Country and timezone pickers, form-associated and autocomplete-backed.
+
+## schmancy-select-countries
+Fully autocomplete-searchable country dropdown. Form-associated (participates in `<form>` submission and validation via `ElementInternals`).
+
+```html
+<schmancy-select-countries
+  name="country"
+  label="Country"
+  placeholder="Select a country"
+  required
+  value="DE"
+  @change=${e => this.country = e.target.value}
+></schmancy-select-countries>
+```
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `value` | string | — | ISO country code (reflected) |
+| `name` | string | `''` | Form field name |
+| `label` | string | `'Country'` | Visible label |
+| `hint` | string | `'Please select a country'` | Helper text |
+| `placeholder` | string | `'Select a country'` | Placeholder in the input |
+| `required` | boolean | `false` | Validation constraint |
+
+## schmancy-select-timezones
+Same pattern as countries, backed by timezone data.
+
+```html
+<schmancy-select-timezones
+  name="timezone"
+  label="Timezone"
+  value="Europe/Berlin"
+></schmancy-select-timezones>
+```
+
+Accepts the same set of properties (`value`, `name`, `label`, `hint`, `placeholder`, `required`).
+
+## Raw Data Exports
+If you want the underlying data without the component:
+```typescript
+import countries from '@mhmo91/schmancy'   // default export from countries.data
+import timezones from '@mhmo91/schmancy'   // default export from timezones.data
+```
+
+Each countries row: `{ code, name, dialCode?, flag?, ... }`. Timezones: `{ name, offset, label, ... }`.
+
+## Form Integration
+Both use `formAssociated = true` and register with the parent `<form>`. Works with native `form.checkValidity()` and with [`schmancy-form`](./form.md).
+
+```html
+<schmancy-form @submit=${this.onSubmit}>
+  <schmancy-select-countries name="country" required></schmancy-select-countries>
+  <schmancy-select-timezones name="timezone" required></schmancy-select-timezones>
+  <schmancy-button type="submit" variant="filled">Save</schmancy-button>
+</schmancy-form>
+```

package/dist/ai/float.md

@@ -0,0 +1,14 @@
+# schmancy-float (deprecated alias)
+
+> Backward-compatibility alias for [`schmancy-window`](./window.md). Existing code keeps working — new code should use `schmancy-window` directly.
+
+## Migration
+```html
+<!-- Before -->
+<schmancy-float id="panel">…</schmancy-float>
+
+<!-- After -->
+<schmancy-window id="panel">…</schmancy-window>
+```
+
+All properties are identical. See [window.md](./window.md) for full API.