@mhmo91/schmancy 0.9.3 → 0.9.5

package/skills/schmancy/steps.md

@@ -0,0 +1,53 @@
+# schmancy-steps-container / schmancy-step
+
+> Vertical stepper with collapsible steps, completion state, and navigation.
+
+## Usage
+```html
+<schmancy-steps-container currentStep="1" @change=${(e) => handleStep(e.detail.value)}>
+  <schmancy-step position="1" title="Account" description="Create your account">
+    <schmancy-input label="Email" required></schmancy-input>
+  </schmancy-step>
+  <schmancy-step position="2" title="Profile" description="Set up profile">
+    <schmancy-input label="Name" required></schmancy-input>
+  </schmancy-step>
+</schmancy-steps-container>
+```
+
+## Properties (schmancy-steps-container)
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| currentStep | number | `1` | Currently active step (1-based) |
+| gap | number | `4` | Gap between steps (Tailwind scale) |
+
+## Properties (schmancy-step)
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| position | number | `1` | Step position (1-based) |
+| title | string | `''` | Step title |
+| description | string | `''` | Step description |
+| completed | boolean | `false` | Explicitly mark as complete |
+| lockBack | boolean | `false` | Prevent navigating to previous steps |
+
+## Events (schmancy-steps-container)
+| Event | Detail | Description |
+|-------|--------|-------------|
+| change | `{ value: number }` | When current step changes |
+
+## Examples
+```html
+<!-- With locked steps -->
+<schmancy-steps-container currentStep="2">
+  <schmancy-step position="1" title="Step 1" completed lockBack>
+    <!-- Already completed, cannot go back -->
+  </schmancy-step>
+  <schmancy-step position="2" title="Step 2">
+    <p>Current step content</p>
+  </schmancy-step>
+  <schmancy-step position="3" title="Step 3">
+    <!-- Not yet reachable -->
+  </schmancy-step>
+</schmancy-steps-container>
+```
+
+Only the active step renders its slotted content. Completed steps show a checkmark. Active step expands with `flex: 1`.

package/skills/schmancy/store.md

@@ -0,0 +1,126 @@
+# Store — Context System
+
+Reactive state management: `createContext`, `@select`, `@selectItem`.
+
+## Creating a context
+
+```typescript
+import { createContext } from '@mhmo91/schmancy'
+
+// Object
+const userContext = createContext<User>(new User(), 'local', 'user')
+
+// Map (collection)
+const itemsContext = createContext<Map<string, Item>>(new Map(), 'indexeddb', 'items')
+
+// Array
+const tagsContext = createContext<string[]>([], 'memory', 'tags')
+```
+
+Signature: `createContext(initial, storage, key)`.
+
+## Storage backends
+
+| Mode | Backing | Survives refresh | Survives tab close | Capacity |
+|------|---------|------------------|--------------------|----------|
+| `'memory'` | JS heap | ❌ | ❌ | RAM |
+| `'session'` | `sessionStorage` | ✅ | ❌ (per-tab) | ~5 MB |
+| `'local'` | `localStorage` | ✅ | ✅ | ~5 MB |
+| `'indexeddb'` | IndexedDB | ✅ | ✅ | GB |
+
+Pick by data size and lifetime:
+- User prefs, long-lived drafts → `'local'`
+- Per-tab ephemeral (cart, wizard) → `'session'`
+- Fetched from API, regenerable → `'memory'`
+- Collections with >100 entries you want cached → `'indexeddb'`
+
+## Reading with `@select`
+
+```typescript
+import { select } from '@mhmo91/schmancy'
+
+@customElement('my-component')
+class MyComponent extends $LitElement() {
+  @select(userContext) user!: User
+
+  // Selector narrows the dependency
+  @select(itemsContext, m => m.size) count!: number
+
+  @select(itemsContext) items!: Map<string, Item>
+}
+```
+
+`@select` options:
+- `required` (default `true`) — wait for `.ready` before `connectedCallback` completes.
+- `updateOnly` — call `requestUpdate` without assigning.
+- `deepClone` — `structuredClone` the value.
+- `debug` — log every emission.
+
+## `@selectItem`
+
+Pick one entry from a collection context, keyed off a component property:
+
+```typescript
+@selectItem(itemsContext, component => component.itemId)
+item!: Item | undefined
+```
+
+## Writing
+
+```typescript
+// Object
+userContext.set({ name: 'Alice' })
+userContext.set({ ...userContext.value, name: 'Bob' })
+
+// Map
+itemsContext.set('id-1', item)
+itemsContext.delete('id-1')
+itemsContext.replace(newMap)
+
+// Array
+tagsContext.push('new')
+tagsContext.replace(['a', 'b'])
+```
+
+## Observable API
+
+```typescript
+userContext.$.pipe(
+  filter(() => userContext.ready),
+  takeUntil(this.disconnecting),
+).subscribe(user => { /* ... */ })
+
+userContext.value       // synchronous snapshot
+userContext.ready       // true once the backing store has loaded
+```
+
+Gate subscriptions on `.ready` — `'local'` / `'session'` / `'indexeddb'` contexts emit their default value before the real stored value hydrates.
+
+## Dynamic contexts
+
+For per-instance state with persistence, create the context inside `connectedCallback` with an instance-scoped key:
+
+```typescript
+private draftCtx: IStore<{ text: string }> | null = null
+
+connectedCallback() {
+  super.connectedCallback()
+  if (this.draftKey) {
+    this.draftCtx = createContext<{ text: string }>(
+      { text: '' },
+      'session',
+      this.draftKey,
+    )
+  }
+}
+```
+
+## Rules
+
+- Declare contexts at module scope (except dynamic per-instance ones).
+- Name the storage key even for `'memory'` contexts — it helps debugging.
+- Keep each context single-purpose. One write shouldn't invalidate unrelated readers.
+- Only the owning component writes. Others read via `@select`.
+- Every subscription uses `takeUntil(this.disconnecting)`.
+- Gate on `.ready` before async cascading work.
+- Don't store Promises, Observables, functions, or class instances in persistent contexts.

package/skills/schmancy/surface.md

@@ -0,0 +1,86 @@
+# Surface
+
+> Glass depth container. Every surface is translucent — depth comes from blur intensity.
+
+## Usage
+
+```html
+<schmancy-surface type="subtle" rounded="all" fill="all">
+  Content on frosted glass
+</schmancy-surface>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `type` | string | `'subtle'` | Glass depth level (see below) |
+| `fill` | string | `'auto'` | `'all'`, `'width'`, `'height'`, `'auto'` |
+| `rounded` | string | `'none'` | `'none'`, `'top'`, `'bottom'`, `'left'`, `'right'`, `'all'` |
+| `elevation` | number | `0` | Glow intensity 0-5 (primary-colored glow, not shadow) |
+| `clickable` | boolean | `false` | Adds luminous hover + spring press |
+
+## Surface Types
+
+### Structural (glass depth model)
+
+| Type | Opacity | Blur | Use for |
+|------|---------|------|---------|
+| `solid` | 92% | — | Dense glass ground layer, highest readability |
+| `subtle` | 78% | 8px | Frosted panels, default containers |
+| `glass` | 55% | 16px | Dialogs, dropdowns, overlays |
+| `luminous` | 42% | 20px | Hero panels, featured content |
+
+### Semantic (tinted glass)
+`primary`, `secondary`, `tertiary`, `error`, `success`, `warning`, `info`
+Each applies a translucent tint of its color + 4px blur.
+
+### Utility
+- `transparent` — no background
+- `outlined` — border only
+
+## Examples
+
+```html
+<!-- Page background -->
+<schmancy-surface type="solid" fill="all" rounded="none">
+  <slot></slot>
+</schmancy-surface>
+
+<!-- Card-like container -->
+<schmancy-surface type="subtle" rounded="all" elevation="1">
+  <div class="p-4">Frosted panel with glow</div>
+</schmancy-surface>
+
+<!-- Dialog surface (used internally by schmancy-dialog) -->
+<schmancy-surface type="glass" rounded="all">
+  <div class="p-6">Glass overlay content</div>
+</schmancy-surface>
+
+<!-- Hero panel with glow halo -->
+<schmancy-surface type="luminous" rounded="all" elevation="3">
+  <div class="p-8">Featured content</div>
+</schmancy-surface>
+
+<!-- Clickable surface with spring physics -->
+<schmancy-surface type="subtle" rounded="all" clickable @click=${handler}>
+  Hover: lift + glow. Press: spring compress.
+</schmancy-surface>
+
+<!-- Error state -->
+<schmancy-surface type="error" rounded="all">
+  <div class="p-3">Something went wrong</div>
+</schmancy-surface>
+```
+
+## Elevation (Glow-based)
+
+Elevation 1-5 applies a primary-colored glow underneath the surface:
+```
+Level 1: subtle glow (15% primary)
+Level 5: strong glow (42% primary)
+```
+
+## Paint Containment
+
+`glass` and `luminous` types automatically apply `contain: content` for GPU optimization.

package/skills/schmancy/table.md

@@ -0,0 +1,60 @@
+# schmancy-table
+
+> Virtualized data table with sorting, custom column rendering, and sticky headers.
+
+## Usage
+```typescript
+html`
+<schmancy-table
+  .columns=${columns}
+  .data=${items}
+  keyField="id"
+  cols="1fr 2fr 1fr"
+  sortable
+  @click=${(e) => selectRow(e.detail)}>
+</schmancy-table>
+`
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| columns | `TableColumn[]` | `[]` | Column definitions |
+| data | `T[]` | `[]` | Data array |
+| keyField | string | `'id'` | Unique key property on each item |
+| cols | string | `'1fr'` | CSS grid-template-columns |
+| sortable | boolean | `false` | Enable column sorting |
+
+## TableColumn Interface
+```typescript
+interface TableColumn<T> {
+  name: string             // Column header text
+  key?: keyof T            // Data property key
+  align?: 'left' | 'right' | 'center'
+  weight?: 'normal' | 'bold'
+  render?: (item: T) => TemplateResult | string | number
+  sortable?: boolean       // Per-column sort toggle
+  value?: (item: T) => any // Custom sort value function
+}
+```
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| click | `{ item: T, index: number }` | Row clicked |
+| sort-change | `{ column, direction }` | Sort state changed |
+
+## Examples
+```typescript
+const columns = [
+  { name: 'Name', key: 'name', sortable: true },
+  { name: 'Status', key: 'status', render: (item) =>
+    html`<schmancy-badge color=${item.active ? 'success' : 'neutral'}>
+      ${item.active ? 'Active' : 'Inactive'}
+    </schmancy-badge>` },
+  { name: 'Created', key: 'createdAt', sortable: true,
+    value: (item) => new Date(item.createdAt).getTime() },
+]
+```
+
+Uses `lit-virtualizer` for efficient rendering of large datasets. Header is sticky with glass surface.

package/skills/schmancy/tabs.md

@@ -0,0 +1,49 @@
+# schmancy-tab-group / schmancy-tab
+
+> Tab container with tab navigation and scroll-spy mode.
+
+## Usage
+```html
+<schmancy-tab-group activeTab="overview">
+  <schmancy-tab label="Overview" value="overview">
+    <p>Overview content</p>
+  </schmancy-tab>
+  <schmancy-tab label="Details" value="details">
+    <p>Details content</p>
+  </schmancy-tab>
+</schmancy-tab-group>
+```
+
+## Properties (schmancy-tab-group)
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| activeTab | string | first tab | Currently active tab value |
+| mode | `'tabs'\|'scroll'` | `'tabs'` | Display mode (tabs or scroll-spy) |
+| rounded | boolean | `true` | Rounded tab bar |
+
+## Properties (schmancy-tab)
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| label | string | - | Tab label text |
+| value | string | - | Unique tab identifier |
+| active | boolean | `false` | Whether this tab is active |
+
+## Events (schmancy-tab-group)
+| Event | Detail | Description |
+|-------|--------|-------------|
+| tab-changed | string | Active tab value when changed |
+
+## Examples
+```html
+<!-- Scroll-spy mode (tabs follow scroll position) -->
+<schmancy-tab-group mode="scroll">
+  <schmancy-tab label="Section 1" value="s1">
+    <div style="height: 500px">Long content</div>
+  </schmancy-tab>
+  <schmancy-tab label="Section 2" value="s2">
+    <div style="height: 500px">More content</div>
+  </schmancy-tab>
+</schmancy-tab-group>
+```
+
+In `tabs` mode, only the active tab renders content. In `scroll` mode, all tabs render and the nav highlights the visible section.

package/skills/schmancy/teleport.md

@@ -0,0 +1,55 @@
+# schmancy-teleport
+
+> Move DOM between locations with a FLIP-animated transition. Two instances sharing an `id` handshake via broadcast events — when one mounts, it finds the other and flies the content between them.
+
+## Usage
+```html
+<!-- Start position -->
+<schmancy-teleport id="hero-image">
+  <img src="portrait.jpg" alt="" />
+</schmancy-teleport>
+
+<!-- Later, in a different view -->
+<schmancy-teleport id="hero-image"></schmancy-teleport>
+```
+
+When the second instance mounts, the image smoothly animates from its old bounding rect to the new one.
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `id` | string | **required** | Shared identifier between source and target |
+| `uuid` | number | auto | Instance UUID for disambiguation (read-only) |
+| `delay` | number | `0` | Delay before teleporting (ms) |
+
+## Discovery Events
+The service broadcasts on `window`:
+- `FINDING_MORTIES` — "is anyone mounted with id X?"
+- `HERE_RICKY` — instances reply with self reference
+- `WhereAreYouRicky` / `HereMorty` — instance-to-instance handshake
+
+Uses RxJS with a race/throwIfEmpty pattern to handle missing counterparts gracefully.
+
+## Typical Pattern — route transitions
+```html
+<!-- List view -->
+${repeat(items, item => item.id, item => html`
+  <schmancy-teleport id=${`card-${item.id}`}>
+    <schmancy-card @click=${() => router.push(`/item/${item.id}`)}>
+      <img src=${item.thumbnail} />
+    </schmancy-card>
+  </schmancy-teleport>
+`)}
+
+<!-- Detail view -->
+<schmancy-teleport id=${`card-${this.params.id}`}></schmancy-teleport>
+```
+
+## Notes
+- Uses `watchElementRect` (ResizeObserver + scroll tracking) to keep source/target in sync.
+- Animation uses the FLIP technique: capture first rect, invert on mount, play to final.
+- All subscriptions clean up via `takeUntil(this.disconnecting)`.
+- Each teleport pair must share a unique `id` string.
+
+## See Also
+- For programmatic teleportation from JS: import `teleportationService` from `@mhmo91/schmancy/teleport`.

package/skills/schmancy/textarea.md

@@ -0,0 +1,48 @@
+# schmancy-textarea
+
+> Multi-line text input with auto-resize and form integration.
+
+## Usage
+```html
+<schmancy-textarea label="Description" placeholder="Enter details..."></schmancy-textarea>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| value | string | `''` | Current text value |
+| label | string | `''` | Label text above the textarea |
+| 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 |
+| hint | string | `undefined` | Hint text below the field |
+| rows | number | `undefined` | Fixed visible rows (omit for auto-size) |
+| cols | number | `20` | Column width |
+| maxlength | number | `undefined` | Maximum character length |
+| minlength | number | `undefined` | Minimum character length |
+| autoHeight | boolean | `true` | Auto-grow height with content |
+| fillHeight | boolean | `false` | Fill container height |
+| resize | `'none'\|'vertical'\|'horizontal'\|'both'` | `'vertical'` | Resize handle |
+| align | `'left'\|'center'\|'right'` | `'left'` | Text alignment |
+| wrap | `'hard'\|'soft'` | `'soft'` | Text wrapping mode |
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| change | `{ value: string }` | On input or native change |
+| enter | `{ value: string }` | When Enter key is pressed |
+
+## Examples
+```html
+<!-- Auto-sizing textarea -->
+<schmancy-textarea label="Notes" autoHeight></schmancy-textarea>
+
+<!-- Fixed height, no resize -->
+<schmancy-textarea rows="5" resize="none" placeholder="Comments..."></schmancy-textarea>
+
+<!-- Fill container -->
+<schmancy-textarea fillHeight label="Content"></schmancy-textarea>
+```

package/skills/schmancy/theme-button.md

@@ -0,0 +1,26 @@
+# schmancy-theme-button
+
+> Minimal palette-icon button that spins 360° on click. Hook its `click` to toggle/regenerate your theme.
+
+## Usage
+```html
+<schmancy-theme-button @click=${() => this.toggleTheme()}></schmancy-theme-button>
+```
+
+## Behavior
+- Renders a `schmancy-button` (variant `text`) wrapping a palette `schmancy-icon`.
+- On click: Web Animations API rotates the icon 360° over 300ms.
+- No properties — it's a UI affordance; wire the theme logic via `@click`.
+
+## Typical Wiring
+```typescript
+import { theme } from '@mhmo91/schmancy'
+
+// Toggle dark/light
+<schmancy-theme-button @click=${() => theme.toggleScheme()}></schmancy-theme-button>
+
+// Randomize primary color
+<schmancy-theme-button @click=${() => theme.randomize()}></schmancy-theme-button>
+```
+
+See [theme.md](./theme.md) for the full theme service API.

package/skills/schmancy/theme.md

@@ -0,0 +1,58 @@
+# schmancy-theme
+
+> Root theme provider that generates color tokens from a source color and distributes them as CSS custom properties.
+
+## Usage
+```html
+<schmancy-theme color="#6200ee" scheme="auto" root>
+  <your-app></your-app>
+</schmancy-theme>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `color` | `string` | Random hex | Primary source color in hex format (e.g. `#6200ee`) |
+| `scheme` | `'dark' \| 'light' \| 'auto'` | `'auto'` | Color scheme. `auto` follows system preference |
+| `root` | `boolean` | `false` | Apply CSS variables to `document.body` instead of shadow host |
+| `locale` | `string` | `navigator.language` | Locale for number/date formatting (e.g. `de-DE`, `ar-SA`) |
+| `name` | `string` | Auto-generated | Unique name for session storage persistence |
+
+## Theme Service (`theme`)
+```typescript
+import { theme } from '@mhmo91/schmancy'
+
+theme.scheme          // 'dark' | 'light' | 'auto' (sync)
+theme.color           // Current hex color (sync)
+theme.scheme$         // Observable<string>
+theme.resolvedScheme$ // Observable<'dark'|'light'> (resolves 'auto')
+
+theme.setScheme('dark')
+theme.setColor('#2196f3')
+theme.toggleScheme()
+theme.isDarkMode()    // Observable<boolean>
+theme.setFullscreen(true)
+```
+
+## Examples
+```html
+<!-- App root with dark blue theme -->
+<schmancy-theme color="#1565c0" scheme="dark" root>
+  <my-app></my-app>
+</schmancy-theme>
+
+<!-- Nested theme override for a section -->
+<schmancy-theme color="#e91e63" scheme="light">
+  <div class="accent-section">...</div>
+</schmancy-theme>
+
+<!-- Arabic locale -->
+<schmancy-theme color="#4caf50" locale="ar-SA" root>
+  <my-app></my-app>
+</schmancy-theme>
+```
+
+## Notes
+- Color and scheme persist to `sessionStorage` per instance
+- Generates success/warning/info/error semantic color tokens automatically
+- Wraps content in a `schmancy-container` with `containerLowest` surface

package/skills/schmancy/tooltip.md

@@ -0,0 +1,38 @@
+# tooltip (directive)
+
+> Lit directive that adds a positioned tooltip to any element on hover/focus.
+
+## Usage
+```typescript
+import { tooltip } from '@mhmo91/schmancy'
+
+html`<button ${tooltip('Click to save')}>Save</button>`
+```
+
+## Parameters
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| text | string | required | Tooltip text content |
+| options.position | `'top'\|'right'\|'bottom'\|'left'` | `'top'` | Tooltip placement |
+| options.delay | number | `300` | Show delay in ms |
+| options.showArrow | boolean | `true` | Show arrow indicator |
+
+## Examples
+```html
+<!-- Bottom positioned -->
+<schmancy-icon-button ${tooltip('Delete item', { position: 'bottom' })}>
+  delete
+</schmancy-icon-button>
+
+<!-- No delay, no arrow -->
+<span ${tooltip('Status: Active', { delay: 0, showArrow: false })}>
+  Active
+</span>
+
+<!-- Right positioned -->
+<div ${tooltip('More info here', { position: 'right' })}>
+  Hover me
+</div>
+```
+
+Uses Floating UI for smart positioning with automatic flipping when near viewport edges. Accessible via `aria-describedby`. Closes on Escape key.

package/skills/schmancy/tree.md

@@ -0,0 +1,53 @@
+# schmancy-tree
+
+> Collapsible tree node with animated expand/collapse and chevron rotation.
+
+## Usage
+```html
+<schmancy-tree>
+  <span slot="root">Parent Item</span>
+  <div>Child content here</div>
+</schmancy-tree>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| open | boolean | `false` | Whether children are visible |
+
+## Slots
+| Slot | Description |
+|------|-------------|
+| root | The clickable root element (toggles open/close) |
+| default | Child content (shown when open) |
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| toggle | - | When the tree node is toggled |
+
+## Examples
+```html
+<!-- Nested trees -->
+<schmancy-tree>
+  <span slot="root">Documents</span>
+  <schmancy-tree>
+    <span slot="root">Reports</span>
+    <div>Q1 Report</div>
+    <div>Q2 Report</div>
+  </schmancy-tree>
+  <schmancy-tree>
+    <span slot="root">Invoices</span>
+    <div>Invoice #001</div>
+  </schmancy-tree>
+</schmancy-tree>
+
+<!-- Initially open -->
+<schmancy-tree open>
+  <span slot="root">Settings</span>
+  <div>General</div>
+  <div>Security</div>
+</schmancy-tree>
+```
+
+Clicking the root slot or the chevron button toggles visibility. Animations use the Web Animations API with 150ms duration.