@mhmo91/schmancy 0.9.4 → 0.9.5

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