@mhmo91/schmancy 0.9.4 → 0.9.6

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. The `<schmancy-tooltip>` component was removed — use this directive.
+
+## 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.

package/skills/schmancy/typewriter.md

@@ -0,0 +1,46 @@
+# schmancy-typewriter
+
+> Text-reveal component powered by [TypeIt](https://typeitjs.com). Characters pop in with entrance + wobble physics; custom cursor pulses with drop-shadow glow.
+
+## Usage
+```html
+<schmancy-typewriter>
+  Hello, world.
+</schmancy-typewriter>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `speed` | number | `35` | Ms per character typed |
+| `deleteSpeed` | number | `20` | Ms per character deleted |
+| `delay` | number | `0` | Initial delay before typing (inherited via `delayContext`) |
+| `autoStart` | boolean | `true` | Start typing on connect |
+| `cursorChar` | string | `''` | Character for the cursor (empty = default block cursor) |
+| `once` | boolean | `true` | Only animate once per session (`sessionStorage` hash) |
+| `loop` | boolean | `false` | Loop infinitely (overrides `once`) |
+| `cyclePause` | number | `1500` | Default pause for cycling (ms) |
+
+## Behavior
+- **Lazy start** via IntersectionObserver — won't type until visible.
+- **Session caching** — when `once=true`, content hash is stored; subsequent visits skip the animation.
+- **Delay coordination** — consumes `delayContext`, staggering with parent `schmancy-delay`.
+- Character entrance animation: scale 0.3 → 1.1 → 1 with blur-to-focus.
+- Alternating characters get a subtle `wobble` rotation.
+- Cursor pulses with `drop-shadow(0 0 8px currentColor)` glow.
+
+## Slot Content
+Text (or nested HTML) goes in the default slot. TypeIt handles strings, tags, line breaks.
+
+```html
+<schmancy-typewriter speed="50">
+  First line.<br>
+  <strong>Bold second.</strong>
+</schmancy-typewriter>
+```
+
+## Vs. `typewriter` directive
+- **Component (`schmancy-typewriter`)**: slot-based, lazy-starts on visibility, one-shot content reveal with cached skipping.
+- **Directive (`typewriter([...phrases])`)**: cycles through a phrase array with typing + deleting + optional Web Audio sound. See [directives.md](./directives.md).
+
+Use the directive for looping taglines. Use the component for one-time paragraph reveals.

package/skills/schmancy/typography.md

@@ -0,0 +1,53 @@
+# schmancy-typography
+
+> Typography component with type scale tokens, editable mode, and line clamping.
+
+## Usage
+```html
+<schmancy-typography type="headline" token="lg">Page Title</schmancy-typography>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| type | `'display'\|'headline'\|'title'\|'subtitle'\|'body'\|'label'` | `'body'` | Typography category |
+| token | `'xs'\|'sm'\|'md'\|'lg'\|'xl'\|''` | `'md'` | Size token (set `''` to use Tailwind classes) |
+| align | `'left'\|'center'\|'right'\|'justify'` | `undefined` | Text alignment |
+| weight | `'normal'\|'medium'\|'bold'` | `undefined` | Font weight |
+| transform | `'uppercase'\|'lowercase'\|'capitalize'\|'normal'` | `undefined` | Text transform |
+| maxLines | 1-6 | `undefined` | Line clamp (truncate with ellipsis) |
+| editable | boolean | `false` | Enable inline editing |
+| value | string | `''` | Text value (editable mode) |
+| placeholder | string | `''` | Placeholder (editable mode) |
+
+## Events (editable mode only)
+| Event | Detail | Description |
+|-------|--------|-------------|
+| change | `{ value: string }` | When edited text is committed (blur/Enter) |
+
+## Type Scale Reference
+| Type | Token | Size |
+|------|-------|------|
+| display | xl/lg/md/sm/xs | 72/57/45/36/28px |
+| headline | xl/lg/md/sm/xs | 36/32/28/24/20px |
+| title | xl/lg/md/sm/xs | 24/22/16/14/12px |
+| body | xl/lg/md/sm/xs | 18/16/14/12/10px |
+| label | xl/lg/md/sm/xs | 16/14/12/11/10px |
+
+## Examples
+```html
+<!-- Responsive sizing with Tailwind (set token="") -->
+<schmancy-typography type="display" token="" class="text-2xl md:text-4xl">
+  Responsive Title
+</schmancy-typography>
+
+<!-- Editable text -->
+<schmancy-typography type="title" token="lg" editable .value=${'Click to edit'}
+  @change=${(e) => save(e.detail.value)}>
+</schmancy-typography>
+
+<!-- Clamped to 2 lines -->
+<schmancy-typography type="body" token="md" maxLines="2">
+  Long text that will be truncated after two lines...
+</schmancy-typography>
+```

package/skills/schmancy/utils.md

@@ -0,0 +1,95 @@
+# Schmancy Utils
+
+> Non-component utilities exported from `@mhmo91/schmancy` (or `@mhmo91/schmancy/utils`). Animation presets, similarity search, number formatting, intersection observer wrapper, overlay z-index manager, and content hashing.
+
+## Animation
+
+See [animation.md](./animation.md) for the full Blackbird spring system. In brief:
+
+```typescript
+import {
+  SPRING_SMOOTH, SPRING_SNAPPY, SPRING_BOUNCY, SPRING_GENTLE,
+  createAnimation, createRevealAnimation, createDismissAnimation, createScaleAnimation,
+  getEasing, prefersReducedMotion,
+  ANIMATION_CSS_VARS, tailwindAnimations, GRID_ANIMATION_CSS,
+} from '@mhmo91/schmancy'
+```
+
+## Number Formatting — `numbers` / `Numbers`
+Locale-aware number formatting + currency + rounding.
+```typescript
+import numbers from '@mhmo91/schmancy'
+
+numbers.roundNumber(3.14159, 2)              // 3.14
+numbers.format(1234567.89)                   // "1,234,567.89" (system locale)
+numbers.format(1234.5, 'de-DE')              // "1.234,5"
+numbers.formatCurrency(99.95, 'EUR')         // "€99.95"
+numbers.systemLocale                         // "en-US" / "de-DE" / etc.
+```
+
+## Fuzzy Search — `similarity(query, target, options?)`
+Autocomplete-tuned similarity scoring. Prioritizes start-matches and word boundaries.
+```typescript
+import { similarity } from '@mhmo91/schmancy'
+
+similarity('john', 'John Doe')   // ~0.975 (starts-with)
+similarity('doe', 'John Doe')    // ~0.765 (word-boundary)
+similarity('jhn', 'John Doe')    // ~0.3–0.5 (fuzzy)
+```
+
+Tiers:
+- `1.00` exact
+- `0.95–1.00` target starts with query
+- `0.765–0.85` word-boundary match
+- `0.56–0.70` substring
+- `0.50` subsequence
+- `0.00–0.50` fuzzy (Dice + Levenshtein + Jaccard + anagram)
+
+Options:
+| Key | Default | Effect |
+|-----|---------|--------|
+| `normalizeAccents` | `true` | Strip diacritics before compare |
+| `includeWordJaccard` | `true` | Add word-set overlap to fuzzy score |
+| `maxLevenshteinDistance` | `0` | Early-terminate above this distance (`0` = off) |
+
+## Intersection Observer — `intersection$(element, options?)`
+RxJS wrapper around `IntersectionObserver`.
+```typescript
+import { intersection$ } from '@mhmo91/schmancy'
+
+intersection$(this.card, { threshold: 0.5 })
+  .pipe(takeUntil(this.disconnecting))
+  .subscribe(entries => {
+    if (entries[0].isIntersecting) this.loadContent()
+  })
+```
+
+## Overlay Stack — `overlayStack`
+Singleton z-index coordinator used internally by dialogs, sheets, and windows. Ensures overlays stack in open order.
+
+```typescript
+import { overlayStack } from '@mhmo91/schmancy'
+
+// Anonymous (fire-and-forget) — dialogs/sheets
+const z = overlayStack.getNextZIndex()
+// …on close:
+overlayStack.release()
+
+// ID-tracked — windows (supports bringToFront)
+overlayStack.assignZIndex('my-window')
+overlayStack.bringToFront('my-window')
+overlayStack.releaseId('my-window')
+```
+
+Base z-index: `10000`. Counter resets when all overlays close.
+
+## Content Hashing — `hashContent(string)`
+Fast 32-bit FNV-1a style hash, returns a hex string. Used by [`schmancy-delay`](./delay.md) and [`schmancy-typewriter`](./typewriter.md) for session-scoped caching.
+```typescript
+import hashContent from '@mhmo91/schmancy/utils/hashContent'
+const key = hashContent(element.outerHTML)   // stable across renders for identical content
+```
+
+## See Also
+- [rxjs-utils](./rxjs-utils.md) — DOM observation helpers (`waitForElement`, `waitUntil`, etc.)
+- [discovery](./discovery.md) — cross-shadow component discovery

package/skills/schmancy/visually-hidden.md

@@ -0,0 +1,41 @@
+# schmancy-visually-hidden
+
+> Hide content visually while keeping it in the accessibility tree. For screen-reader-only labels, supplemental descriptions, and live-region text.
+
+## Usage
+```html
+<button>
+  <schmancy-icon>close</schmancy-icon>
+  <schmancy-visually-hidden>Close dialog</schmancy-visually-hidden>
+</button>
+```
+
+## Why not `display: none` / `visibility: hidden` / `aria-hidden`?
+Those remove content from assistive tech too. `<schmancy-visually-hidden>` uses the WCAG-recommended clip pattern, so screen readers still read the content while sighted users don't see it.
+
+## Properties
+None. Pure wrapper.
+
+## Examples
+```html
+<!-- Icon-only button label -->
+<schmancy-icon-button>
+  <schmancy-icon>delete</schmancy-icon>
+  <schmancy-visually-hidden>Delete item</schmancy-visually-hidden>
+</schmancy-icon-button>
+```
+
+```html
+<!-- Additional context for links -->
+<a href="/article/42">
+  Read more
+  <schmancy-visually-hidden>about quarterly earnings</schmancy-visually-hidden>
+</a>
+```
+
+```html
+<!-- Live region announcements -->
+<schmancy-visually-hidden role="status" aria-live="polite">
+  ${this.status}
+</schmancy-visually-hidden>
+```

package/skills/schmancy/window.md

@@ -0,0 +1,67 @@
+# schmancy-window
+
+> Floating draggable window with corner snapping, resize, and minimize/maximize states. Replaces deprecated `schmancy-float`.
+
+## Usage
+```html
+<schmancy-window id="chat" corner="bottom-right">
+  <span slot="header">Chat</span>
+  <schmancy-icon slot="icon">chat</schmancy-icon>
+  <div>Window body content…</div>
+</schmancy-window>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `id` | string | `'default'` | Unique window identifier (used by `windowManager` registry) |
+| `open` | boolean | `false` | Body expanded state |
+| `corner` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | `'bottom-right'` | Anchor corner |
+| `freePosition` | boolean | `false` | Keep dragged position instead of snapping to corner |
+| `resizable` | boolean | `false` | Allow user resizing from edges |
+| `visualState` | `'minimized' \| 'normal' \| 'maximized'` | `'normal'` | Reflected state attribute |
+| `expandedWidth` | string | responsive | e.g. `'320px'`, `'24rem'` |
+| `expandedHeight` | string | auto | e.g. `'400px'`, `'50vh'` |
+| `minWidth` | number | `280` | Minimum width px during resize |
+| `minHeight` | number | `200` | Minimum height px during resize |
+| `lowered` | boolean | `false` | Lower elevation shadow in collapsed state |
+
+## Slots
+| Slot | Purpose |
+|------|---------|
+| `icon` | Leading icon in the head (minimized FAB state) |
+| `header` | Header label (visible when expanded) |
+| (default) | Window body content (lazy rendered — not in DOM until first open) |
+
+## Behavior
+- Drag from head to reposition. Release snaps to the nearest corner unless `freePosition`.
+- `windowManager` tracks focused window and resolves overlap between multiple windows.
+- `cursorGlow` applied to head while expanded.
+- Collapsed state uses a clip-path reveal animation; expand uses `SPRING_SMOOTH` physics.
+- Body content mounts lazily on first expand (`_hasOpened`).
+- All animations respect `prefers-reduced-motion` via `reducedMotion$`.
+
+## Examples
+```html
+<!-- Chat-style window docked bottom-right -->
+<schmancy-window id="support" corner="bottom-right">
+  <schmancy-icon slot="icon">support_agent</schmancy-icon>
+  <span slot="header">Support</span>
+  <div class="p-4">How can we help?</div>
+</schmancy-window>
+
+<!-- Resizable, free-position floating panel -->
+<schmancy-window id="inspector" resizable free-position expanded-width="420px" expanded-height="60vh">
+  <span slot="header">Inspector</span>
+  <div>…</div>
+</schmancy-window>
+```
+
+## windowManager
+```typescript
+import { windowManager } from '@mhmo91/schmancy/window'
+
+windowManager.focus('support')       // Bring window to front
+windowManager.getBounds('inspector') // Read tracked bounds
+windowManager.all$ .subscribe(...)    // Observable of registered windows
+```

package/src/audio/emotional-sounds.ts

@@ -78,10 +78,8 @@ export type Feeling =
   | HappyFeeling | SadFeeling | AnxiousFeeling | AngryFeeling
   | TiredFeeling | CalmFeeling | ConnectedFeeling | MixedFeeling
 
-/** Feeling category */
-export type FeelingCategory =
-  | 'happy' | 'sad' | 'anxious' | 'angry'
-  | 'tired' | 'calm' | 'connected' | 'mixed'
+// FeelingCategory is defined in ../types/mood-audio.types.ts and re-exported
+// from ./index.ts — the canonical source.
 
 // ============================================================================
 // SOUND GENERATOR

package/src/autocomplete/autocomplete.ts

@@ -1,7 +1,7 @@
 import { $LitElement } from '@mixins/index'
 import { InputSize, SchmancyInput } from '@schmancy/input'
 import SchmancyOption from '@schmancy/option/option'
-import { html } from 'lit'
+import { html, nothing } from 'lit'
 import { customElement, property, query, queryAssignedElements, state } from 'lit/decorators.js'
 import { classMap } from 'lit/directives/class-map.js'
 import { createRef, ref } from 'lit/directives/ref.js'
@@ -48,6 +48,40 @@ interface FilteredOption {
  */
 @customElement('schmancy-autocomplete')
 export default class SchmancyAutocomplete extends $LitElement(style) {
+    static formAssociated = true
+    internals: ElementInternals | undefined
+
+    constructor() {
+        super()
+        try {
+            this.internals = this.attachInternals()
+        } catch {
+            this.internals = undefined
+        }
+    }
+
+    get form(): HTMLFormElement | null {
+        return this.internals?.form ?? null
+    }
+
+    formResetCallback(): void {
+        if (this.multi) {
+            this._selectedValues$.next([])
+        } else {
+            this._selectedValue$.next('')
+        }
+        this._inputValue = ''
+        this._inputValue$.next('')
+        this.error = false
+        this.validationMessage = ''
+    }
+
+    formDisabledCallback(disabled: boolean): void {
+        // The component does not expose a disabled prop directly; propagate via attribute.
+        if (disabled) this.setAttribute('disabled', '')
+        else this.removeAttribute('disabled')
+    }
+
     // Track whether value/values have been explicitly set
      _valueSet: boolean = false
      _valuesSet: boolean = false
@@ -67,6 +101,8 @@ export default class SchmancyAutocomplete extends $LitElement(style) {
     @property({ type: Boolean }) error = false
     @property({ type: String }) validationMessage = ''
 
+    private readonly _a11yId = `schmancy-autocomplete-${Math.random().toString(36).slice(2, 10)}`
+
     // Values property for multi-select mode
     @property({ type: Array })
     get values() {
@@ -139,6 +175,16 @@ export default class SchmancyAutocomplete extends $LitElement(style) {
         ]).pipe(
             tap(([selectedValue, selectedValues]) => {
                 this._updateOptionSelection(selectedValue, selectedValues)
+                // Keep ElementInternals form value in sync with selection (single and multi).
+                const formValue = this.multi ? selectedValues.join(',') : selectedValue
+                this.internals?.setFormValue(formValue || null)
+                if (this.required) {
+                    const missing = this.multi ? selectedValues.length === 0 : !selectedValue
+                    this.internals?.setValidity(
+                        missing ? { valueMissing: true } : {},
+                        missing ? this.validationMessage || 'Please select an option.' : undefined,
+                    )
+                }
             }),
             takeUntil(this.disconnecting)
         ).subscribe()
@@ -494,6 +540,10 @@ export default class SchmancyAutocomplete extends $LitElement(style) {
                                         .placeholder=${this._selectedValues$.value.length > 0 ? 'Add more...' : this.placeholder}
                                         .value=${this._inputValue}
                                         .autocomplete=${this.autocomplete}
+                                        aria-invalid=${this.error ? 'true' : 'false'}
+                                        aria-required=${this.required ? 'true' : 'false'}
+                                        aria-describedby=${this.error && this.validationMessage ? `${this._a11yId}-err` : nothing}
+                                        aria-label=${!this.label && this.placeholder ? this.placeholder : nothing}
                                         @input=${(e: Event) => {
                                             const value = (e.target as HTMLInputElement).value
                                             this._inputValue = value
@@ -517,7 +567,7 @@ export default class SchmancyAutocomplete extends $LitElement(style) {
 
                                 <!-- Validation message -->
                                 ${when(this.error && this.validationMessage, () => html`
-                                    <div class="mt-1 text-sm text-error-default">
+                                    <div id="${this._a11yId}-err" class="mt-1 text-sm text-error-default" role="alert">
                                         ${this.validationMessage}
                                     </div>
                                 `)}