@mhmo91/schmancy 0.8.6 → 0.9.3

package/ai/typography.md

@@ -1,306 +1,53 @@
-# Schmancy Typography - AI Reference
+# schmancy-typography
 
-```js
-// Component Tag
-<schmancy-typography
-  type="display|headline|title|subtitle|label|body"      // Typography scale type
-  token="xl|lg|md|sm|xs"                                 // Size token within type
-  align?="left|center|justify|right"                     // Text alignment
-  weight?="normal|medium|bold"                           // Font weight override
-  transform?="uppercase|lowercase|capitalize|normal"     // Text transformation
-  maxLines?="1|2|3|4|5|6"                               // Truncate with ellipsis
-  class?="additional-tailwind-classes"                   // Additional styling
-  @click=${handler}>                                     // Click handler
-  <!-- Text content or HTML -->
-</schmancy-typography>
-
-// Import
-import '@schmancy/index'  // For all Schmancy components
-// Or specific import: import '@schmancy/typography'
-
-// Typography Scale Reference (size/line-height)
-// Display: xl (72/80), lg (57/64), md (45/52), sm (36/44), xs (28/36)
-// Headline: xl (36/44), lg (32/40), md (28/36), sm (24/32), xs (20/28)
-// Title: xl (24/32), lg (22/28), md (16/24), sm (14/20), xs (12/16)
-// Subtitle: xl (20/28), lg (18/24), md (16/24), sm (14/20), xs (12/16)
-// Label: xl (16/22), lg (14/20), md (12/16), sm (11/16), xs (10/14)
-// Body: xl (18/28), lg (16/24), md (14/20), sm (12/16), xs (10/14)
-
-// Examples
-// 1. Page heading (Display)
-<schmancy-typography type="display" token="lg">
-  Welcome to Schmancy
-</schmancy-typography>
-
-// 2. Section heading (Headline)
-<schmancy-typography type="headline" token="md">
-  Getting Started
-</schmancy-typography>
-
-// 3. Card title
-<schmancy-typography type="title" token="lg">
-  User Profile Settings
-</schmancy-typography>
-
-// 4. Form label
-<schmancy-typography type="label" token="md">
-  Email Address
-</schmancy-typography>
-
-// 5. Body text
-<schmancy-typography type="body" token="md">
-  This is the main content paragraph with medium body text.
-</schmancy-typography>
-
-// 6. With additional styling
-<schmancy-typography type="headline" token="sm" class="mb-4">
-  Section Title
-</schmancy-typography>
-
-// 7. Centered uppercase title
-<schmancy-typography type="title" token="lg" align="center" transform="uppercase">
-  Section Header
-</schmancy-typography>
-
-// 8. Clickable text (wrap in surface or use native link)
-<schmancy-surface type="primaryContainer" class="inline-block px-2 py-1 rounded cursor-pointer" @click="${handleClick}">
-  <schmancy-typography type="body" token="md">
-    Click me for more information
-  </schmancy-typography>
-</schmancy-surface>
-
-// 9. Truncated text with ellipsis
-<schmancy-typography type="body" token="md" maxLines="2">
-  This is a long description that will be truncated after two lines with an ellipsis if it exceeds the available space...
-</schmancy-typography>
-
-// 10. Multiple typography in a card
-<schmancy-card class="p-6">
-  <schmancy-typography type="headline" token="sm" class="block mb-2">
-    Card Title
-  </schmancy-typography>
-  <schmancy-typography type="body" token="md" class="block mb-4">
-    This is a description that provides more context about the card content.
-  </schmancy-typography>
-  <schmancy-surface type="primaryContainer" class="inline-block px-2 py-1 rounded">
-    <schmancy-typography type="label" token="lg">
-      View Details →
-    </schmancy-typography>
-  </schmancy-surface>
-</schmancy-card>
-```
-
-## Related Components
-- **[Card](./card.md)**: Often used within cards for titles and content
-- **[Button](./button.md)**: Typography can be used within buttons for custom text
-- **[Surface](./surface.md)**: Typography inherits color from surface containers
-- **[Form](./form.md)**: Labels and helper text in forms
-- **[Table](./table.md)**: Headers and cell content formatting
-
-## Technical Details
-
-### Typography Scale System
-Material Design 3 typography scale with 6 types, each with 5 sizes:
-
-**Display** - Largest text for big statements (weight: 400)
-- `xl`: 72px/80px line-height
-- `lg`: 57px/64px line-height
-- `md`: 45px/52px line-height
-- `sm`: 36px/44px line-height
-- `xs`: 28px/36px line-height
-
-**Headline** - Section headers and important titles (weight: 400)
-- `xl`: 36px/44px line-height
-- `lg`: 32px/40px line-height
-- `md`: 28px/36px line-height
-- `sm`: 24px/32px line-height
-- `xs`: 20px/28px line-height
-
-**Title** - Smaller titles and subtitles (weight: 400)
-- `xl`: 24px/32px line-height (weight: 400)
-- `lg`: 22px/28px line-height (weight: 400)
-- `md`: 16px/24px line-height (weight: 500)
-- `sm`: 14px/20px line-height (weight: 500)
-- `xs`: 12px/16px line-height (weight: 500)
-
-**Subtitle** - Secondary headings (weight: 500)
-- `xl`: 20px/28px line-height
-- `lg`: 18px/24px line-height
-- `md`: 16px/24px line-height
-- `sm`: 14px/20px line-height
-- `xs`: 12px/16px line-height
+> Typography component with type scale tokens, editable mode, and line clamping.
 
-**Label** - UI labels and buttons (weight: 500)
-- `xl`: 16px/22px line-height
-- `lg`: 14px/20px line-height
-- `md`: 12px/16px line-height
-- `sm`: 11px/16px line-height
-- `xs`: 10px/14px line-height
-
-**Body** - Main content text (weight: 400)
-- `xl`: 18px/28px line-height
-- `lg`: 16px/24px line-height
-- `md`: 14px/20px line-height
-- `sm`: 12px/16px line-height
-- `xs`: 10px/14px line-height
-
-### Additional Properties
-
-**Text Alignment** (`align`)
-- `left`: Align text to the left
-- `center`: Center the text
-- `justify`: Justify text
-- `right`: Align text to the right
-
-**Font Weight** (`weight`)
-- `normal`: 400 weight
-- `medium`: 500 weight
-- `bold`: 700 weight
-
-**Text Transform** (`transform`)
-- `uppercase`: Convert to uppercase
-- `lowercase`: Convert to lowercase
-- `capitalize`: Capitalize first letter of each word
-- `normal`: No transformation
-
-**Line Clamping** (`maxLines`)
-- Truncates text after specified number of lines
-- Adds ellipsis (...) at the end
-- Values: 1-6 lines
-
-### Theme Integration
-Typography automatically inherits colors from the theme:
-- Uses `color: var(--schmancy-sys-color-surface-on)` by default
-- Automatically inherits the correct text color from parent surfaces
-- WARNING: Avoid overriding with Tailwind color classes when inside surfaces
-
-### Color Inheritance
-
-## 🚨 ABSOLUTE RULE: NEVER PUT COLOR CLASSES ON SCHMANCY-TYPOGRAPHY
-
-**Typography MUST inherit its color from the parent surface. NO EXCEPTIONS.**
-
-### Why This Rule Exists
-- `schmancy-typography` automatically gets the correct contrast color from its parent surface
-- Adding `text-*` classes breaks the design system's color inheritance
-- It causes visual inconsistency when themes change
-- It violates Material Design 3's surface/on-color relationship
-
-### ❌ FORBIDDEN - Color Classes on Typography
+## Usage
 ```html
-<!-- ALL OF THESE ARE WRONG - NEVER DO THIS -->
-<schmancy-typography type="headline" token="md" class="text-error">Wrong</schmancy-typography>
-<schmancy-typography type="body" token="sm" class="text-success">Wrong</schmancy-typography>
-<schmancy-typography type="title" token="lg" class="text-primary">Wrong</schmancy-typography>
-<schmancy-typography type="label" token="md" class="text-warning">Wrong</schmancy-typography>
-<schmancy-typography class="text-surface-onVariant">Wrong</schmancy-typography>
+<schmancy-typography type="headline" token="lg">Page Title</schmancy-typography>
 ```
 
-### ✅ CORRECT - Use Surfaces to Control Color
+## 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
-<!-- Need error text? Use error surface -->
-<schmancy-surface type="error" class="px-2 py-1 rounded">
-  <schmancy-typography type="body" token="sm">
-    Error message here (automatically gets on-error color)
-  </schmancy-typography>
-</schmancy-surface>
-
-<!-- Need primary-colored text? Use primary surface -->
-<schmancy-surface type="primary" class="px-2 py-1 rounded">
-  <schmancy-typography type="label" token="md">
-    Primary text (automatically gets on-primary color)
-  </schmancy-typography>
-</schmancy-surface>
-
-<!-- Normal text inside container -->
-<schmancy-surface type="container" class="p-4">
-  <schmancy-typography type="headline" token="md">
-    This text automatically uses the correct contrast color
-  </schmancy-typography>
-</schmancy-surface>
-```
+<!-- Responsive sizing with Tailwind (set token="") -->
+<schmancy-typography type="display" token="" class="text-2xl md:text-4xl">
+  Responsive Title
+</schmancy-typography>
 
-### ❌ ALSO FORBIDDEN - Spans with Colors Inside Typography
-```html
-<!-- WRONG - No color classes inside typography either! -->
-<schmancy-typography type="body" token="md">
-  Total: <span class="text-error">-€338.89</span>  <!-- WRONG -->
+<!-- Editable text -->
+<schmancy-typography type="title" token="lg" editable .value=${'Click to edit'}
+  @change=${(e) => save(e.detail.value)}>
 </schmancy-typography>
-```
 
-### ✅ CORRECT - Always Wrap with Surface
-```html
-<!-- For colored values, wrap the typography in a surface -->
-<schmancy-surface type="errorContainer" class="px-2 py-0.5 rounded inline-block">
-  <schmancy-typography type="body" token="md">-€338.89</schmancy-typography>
-</schmancy-surface>
+<!-- Clamped to 2 lines -->
+<schmancy-typography type="body" token="md" maxLines="2">
+  Long text that will be truncated after two lines...
+</schmancy-typography>
 ```
-
-### Available Surface Types for Colored Text
-| Need This Color | Use This Surface |
-|-----------------|------------------|
-| Error/Red text | `type="error"` or `type="errorContainer"` |
-| Success/Green text | `type="success"` or `type="successContainer"` |
-| Warning/Amber text | `type="warning"` or `type="warningContainer"` |
-| Primary accent | `type="primary"` or `type="primaryContainer"` |
-| Secondary accent | `type="secondary"` or `type="secondaryContainer"` |
-| Tertiary accent | `type="tertiary"` or `type="tertiaryContainer"` |
-
-### The Principle
-**Surfaces define the background AND automatically provide the correct text color.**
-- `schmancy-surface type="error"` → red background, white text (automatic)
-- `schmancy-surface type="errorContainer"` → light red background, dark red text (automatic)
-- Trust the design system - don't override it with color classes
-
-### Implementation Details
-- Uses Shadow DOM with encapsulated styles
-- All typography values are hardcoded in the component
-- Renders with `display: block` by default
-- Font family inherits from parent
-- All properties reflect to HTML attributes for CSS targeting
-
-## Common Use Cases
-
-1. **Page Layout**
-   ```html
-   <schmancy-typography type="display" token="md" class="block mb-4">
-     Dashboard
-   </schmancy-typography>
-   <schmancy-typography type="body" token="lg" class="block">
-     Welcome back! Here's your activity summary.
-   </schmancy-typography>
-   ```
-
-2. **Form Fields**
-   ```html
-   <schmancy-typography type="label" token="md" class="block mb-2">
-     Username
-   </schmancy-typography>
-   <schmancy-input placeholder="Enter username"></schmancy-input>
-   ```
-
-3. **Data Display**
-   ```html
-   <schmancy-surface type="primaryContainer" class="inline-block px-3 py-2 rounded">
-     <schmancy-typography type="headline" token="md" class="block">
-       $1,234.56
-     </schmancy-typography>
-   </schmancy-surface>
-   <schmancy-typography type="label" token="sm">
-     Total Revenue
-   </schmancy-typography>
-   ```
-
-4. **List Items**
-   ```html
-   <div class="space-y-4">
-     <div>
-       <schmancy-typography type="title" token="md" class="block">
-         Feature One
-       </schmancy-typography>
-       <schmancy-typography type="body" token="sm" class="block">
-         Description of the first feature
-       </schmancy-typography>
-     </div>
-   </div>
-   ```

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