@mhmo91/schmancy 0.8.6 → 0.9.3

package/ai/audio.md

@@ -1,241 +1,69 @@
-# Schmancy Emotional Sound Library - AI Reference
+# Schmancy Audio
 
-## Overview
-
-A curated collection of soft, elegant sounds organized by emotional categories. Each sound is designed to be non-intrusive, emotionally evocative, and beautiful - inspired by the gentle sounds of nature like soft air puffs and warm tones.
-
-## Quick Start
+> Emotional sound service — synthesizes short, empathetic sounds via Web Audio API keyed on feelings (joyful, tense, calm, etc.). No assets. No external players. Just tones + puffs generated on demand.
 
+## Usage
 ```typescript
-// Import from the main Schmancy package
-import { $sounds } from '@mhmo91/schmancy'
-
-// Play a feeling
-$sounds.play('joyful')
-$sounds.play('relieved')
-$sounds.play('curious')
+import { sound } from '@mhmo91/schmancy'
 
-// Adjust volume (0.0 - 1.0)
-$sounds.setVolume(0.2)
-
-// Mute/unmute
-$sounds.mute()
-$sounds.unmute()
+sound.play('joyful')     // trigger a feeling sound
+sound.setVolume(0.2)     // 0..1
+sound.setMuted(true)
+sound.resetTheme()       // back to defaults
 ```
 
-## Feeling Categories
-
-### 1. Happy / Pleasant
-```typescript
-type HappyFeeling =
-  | 'joyful' | 'content' | 'excited' | 'proud' | 'hopeful'
-  | 'relieved' | 'grateful' | 'peaceful' | 'playful' | 'amused'
-  | 'curious' | 'inspired' | 'confident' | 'loved' | 'comforted' | 'energized'
-
-// Examples
-$sounds.play('joyful')     // Double puff + rising happy tones
-$sounds.play('content')    // Gentle satisfied sigh + warm tones
-$sounds.play('excited')    // Quick ascending puffs + sparkly tones
-$sounds.play('curious')    // Questioning puff + rising tone
-$sounds.play('relieved')   // Long exhale + descending release
-```
-
-### 2. Sad / Low
-```typescript
-type SadFeeling =
-  | 'sad' | 'lonely' | 'disappointed' | 'heartbroken' | 'grieving'
-  | 'hopeless' | 'empty' | 'discouraged' | 'melancholic' | 'homesick'
-  | 'hurt' | 'miserable' | 'regretful' | 'ashamed' | 'inferior'
-
-// Examples
-$sounds.play('sad')           // Heavy sigh + descending tone
-$sounds.play('disappointed')  // Deflating puff + falling tone
-$sounds.play('melancholic')   // Wistful puff + bittersweet tones
-```
-
-### 3. Anxious / Fearful
-```typescript
-type AnxiousFeeling =
-  | 'anxious' | 'worried' | 'afraid' | 'terrified' | 'panicked'
-  | 'nervous' | 'uneasy' | 'insecure' | 'overwhelmed' | 'stressed'
-  | 'tense' | 'apprehensive' | 'startled' | 'suspicious' | 'vulnerable'
-
-// Examples
-$sounds.play('anxious')   // Tight quick puffs + uncertain wobble
-$sounds.play('nervous')   // Quick shallow puffs + trembling tone
-$sounds.play('startled')  // Quick sharp puff + high tone
-```
-
-### 4. Angry / Frustrated
-```typescript
-type AngryFeeling =
-  | 'annoyed' | 'irritated' | 'frustrated' | 'angry' | 'enraged'
-  | 'bitter' | 'resentful' | 'jealous' | 'envious' | 'indignant'
-  | 'impatient' | 'hostile' | 'contemptuous'
-
-// Examples
-$sounds.play('annoyed')     // Short frustrated puff + low rumble
-$sounds.play('frustrated')  // Tense puff + blocked feeling
-$sounds.play('impatient')   // Quick tapping puffs + urgent tone
-```
-
-### 5. Tired / Drained
-```typescript
-type TiredFeeling =
-  | 'tired' | 'exhausted' | 'drained' | 'burnedOut' | 'numb'
-  | 'bored' | 'unmotivated' | 'apathetic' | 'restless'
-
-// Examples
-$sounds.play('tired')     // Heavy slow puff + drooping tone
-$sounds.play('exhausted') // Very slow heavy exhale + descending fade
-$sounds.play('bored')     // Flat sigh + monotone
-```
-
-### 6. Calm / Grounded
-```typescript
-type CalmFeeling =
-  | 'calm' | 'relaxed' | 'atEase' | 'balanced' | 'stable'
-  | 'secure' | 'safe' | 'centered' | 'grounded' | 'accepting'
-
-// Examples
-$sounds.play('calm')      // Slow peaceful puff + sustained gentle tone
-$sounds.play('relaxed')   // Long soft exhale + gentle descending
-$sounds.play('grounded')  // Deep centered puff + low stable tone
-$sounds.play('safe')      // Soft enveloping puff + warm embracing tones
-```
-
-### 7. Connected / Social
-```typescript
-type ConnectedFeeling =
-  | 'connected' | 'accepted' | 'included' | 'belonging' | 'appreciated'
-  | 'valued' | 'respected' | 'supported' | 'protective' | 'compassionate' | 'empathetic'
-
-// Examples
-$sounds.play('connected')   // Warm shared breath + harmonious tones
-$sounds.play('appreciated') // Touched puff + warm ascending
-$sounds.play('supported')   // Held puff + stable harmonies
-```
-
-### 8. Mixed / Complicated
-```typescript
-type MixedFeeling =
-  | 'conflicted' | 'confused' | 'ambivalent' | 'nostalgic' | 'guilty'
-  | 'embarrassed' | 'surprised' | 'shocked' | 'awestruck' | 'skeptical'
-
-// Examples
-$sounds.play('nostalgic')  // Wistful distant puff + bittersweet memory tones
-$sounds.play('surprised')  // Quick gasp + rising tone
-$sounds.play('awestruck')  // Wonder-filled breath + ascending shimmer
-$sounds.play('confused')   // Uncertain puff + questioning wobble
-```
-
-## API Reference
+## Feelings
+Organized by emotional category:
 
+| Category | Feelings |
+|----------|----------|
+| Happy | `joyful`, `content`, `excited`, `grateful`, `proud`, `loved` |
+| Sad | `sad`, `disappointed`, `hurt`, `lonely`, `melancholy` |
+| Anxious | `worried`, `nervous`, `overwhelmed`, `tense` |
+| Angry | `frustrated`, `angry`, `annoyed` |
+| Tired | `tired`, `drained`, `bored` |
+| Calm | `calm`, `peaceful`, `relaxed`, `focused` |
+| Connected | `connected`, `supported`, `welcomed` |
+| Mixed | `confused`, `nostalgic`, `bittersweet` |
+
+(See `mood-audio.types.ts` for the authoritative list.)
+
+## Observable API
 ```typescript
-class EmotionalSoundGenerator {
-  // Play any feeling
-  play(feeling: Feeling): void
-
-  // Volume control (0.0 - 1.0, default 0.15)
-  setVolume(vol: number): void
-  getVolume(): number
-
-  // Mute control
-  mute(): void
-  unmute(): void
-  isMuted(): boolean
-
-  // Cleanup
-  dispose(): void
-}
-
-// Singleton instance
-export const $sounds: EmotionalSoundGenerator
+sound.theme$.subscribe(theme => console.log(theme?.name ?? 'default'))
+sound.volume$.subscribe(v => {})
+sound.muted$.subscribe(m => {})
 ```
 
-## Sound Design Philosophy
-
-All sounds are built from these core primitives:
-
-1. **Puff** - Filtered white noise creating soft air sounds
-2. **Tone** - Simple sine wave with gentle envelope
-3. **Warm Tone** - Low-pass filtered tone for warmth
-4. **Shimmer** - Multiple harmonically related tones
-
-Each feeling combines these primitives with:
-- Quick attack (15-30ms) for responsiveness
-- Gentle exponential release for softness
-- Low default volume (0.15) for subtlety
-- Short duration (0.2-0.5s) for non-intrusiveness
-
-## Use Cases
+## Settings Persistence
+Volume, mute, and custom theme persist to `localStorage` under key `schmancy-sound-settings` (via `createContext`).
 
+## AI-Generated Themes
 ```typescript
-// Form validation feedback
-onValidationError() {
-  $sounds.play('disappointed')
-}
-
-onValidationSuccess() {
-  $sounds.play('relieved')
-}
-
-// User actions
-onSaveComplete() {
-  $sounds.play('content')
-}
-
-onDelete() {
-  $sounds.play('sad')
-}
-
-// Navigation
-onPageLoad() {
-  $sounds.play('curious')
-}
-
-// Achievements
-onMilestoneReached() {
-  $sounds.play('proud')
-}
-
-// Connections
-onFriendJoined() {
-  $sounds.play('connected')
+import type { SoundTheme } from '@mhmo91/schmancy'
+
+const customTheme: SoundTheme = {
+  name: 'ocean',
+  sounds: {
+    joyful: { puffs: [...], tones: [...] },
+    // partial override — falls through to defaults for anything omitted
+  }
 }
 
-// Waiting states
-onLoadingTimeout() {
-  $sounds.play('impatient')
-}
+sound.setTheme(customTheme)
 ```
 
-## Type Exports
+Each `FeelingSound` consists of:
+- **puffs** — short bursts (air/noise, e.g. `{ startTime, duration, frequency, volume }`)
+- **tones** — oscillators (`sine`/`triangle`/`square`/`sawtooth` with envelope)
 
-```typescript
-import type {
-  Feeling,
-  FeelingCategory,
-  HappyFeeling,
-  SadFeeling,
-  AnxiousFeeling,
-  AngryFeeling,
-  TiredFeeling,
-  CalmFeeling,
-  ConnectedFeeling,
-  MixedFeeling,
-} from '@mhmo91/schmancy'
-```
+## Built-in Feedback Hooks
+Other Schmancy components play these automatically:
+- [`schmancy-connectivity-status`](./connectivity.md) on offline/online.
+- Some success/error paths in notifications and dialogs via the `$sounds` legacy helper.
 
-## All 88 Feelings at a Glance
+## Legacy API
+- `$sounds` — older generator exported for compatibility.
+- `EmotionalSoundGenerator` — underlying class.
 
-| Category | Feelings |
-|----------|----------|
-| **Happy** | joyful, content, excited, proud, hopeful, relieved, grateful, peaceful, playful, amused, curious, inspired, confident, loved, comforted, energized |
-| **Sad** | sad, lonely, disappointed, heartbroken, grieving, hopeless, empty, discouraged, melancholic, homesick, hurt, miserable, regretful, ashamed, inferior |
-| **Anxious** | anxious, worried, afraid, terrified, panicked, nervous, uneasy, insecure, overwhelmed, stressed, tense, apprehensive, startled, suspicious, vulnerable |
-| **Angry** | annoyed, irritated, frustrated, angry, enraged, bitter, resentful, jealous, envious, indignant, impatient, hostile, contemptuous |
-| **Tired** | tired, exhausted, drained, burnedOut, numb, bored, unmotivated, apathetic, restless |
-| **Calm** | calm, relaxed, atEase, balanced, stable, secure, safe, centered, grounded, accepting |
-| **Connected** | connected, accepted, included, belonging, appreciated, valued, respected, supported, protective, compassionate, empathetic |
-| **Mixed** | conflicted, confused, ambivalent, nostalgic, guilty, embarrassed, surprised, shocked, awestruck, skeptical |
+Prefer `sound` for new code.

package/ai/autocomplete.md

@@ -1,171 +1,53 @@
-# Schmancy Autocomplete - AI Reference
+# schmancy-autocomplete
 
-## Overview
-A searchable dropdown component with fuzzy search, keyboard navigation, and multi-select support. Uses similarity scoring for intelligent option filtering.
+> Searchable input with fuzzy filtering, single/multi-select, and inline chip display.
 
-```js
-// Basic Autocomplete (Single-Select)
-<schmancy-autocomplete
-  label="Select an option"
-  placeholder="Type to search..."
-  value="selected-value"
-  size="sm|md|lg"
-  required?
-  maxHeight="300px"
-  @change=${handleChange}>
-  
-  <schmancy-option value="option1">Option 1</schmancy-option>
-  <schmancy-option value="option2">Option 2</schmancy-option>
-  <schmancy-option value="option3">Option 3</schmancy-option>
-</schmancy-autocomplete>
-
-// Multi-Select Autocomplete
-<schmancy-autocomplete
-  label="Select multiple options"
-  placeholder="Type to search..."
-  multi
-  .values=${['option1', 'option3']} // Array of selected values (preferred for multi-select)
-  @change=${handleMultiChange}>
-  
-  <schmancy-option value="option1">Option 1</schmancy-option>
-  <schmancy-option value="option2">Option 2</schmancy-option>
-  <schmancy-option value="option3">Option 3</schmancy-option>
-</schmancy-autocomplete>
-
-// Autocomplete with Custom Trigger
-<schmancy-autocomplete>
-  <button slot="trigger">Open Options</button>
-  
-  <schmancy-option value="option1" label="Option 1"></schmancy-option>
-  <schmancy-option value="option2" label="Option 2"></schmancy-option>
-</schmancy-autocomplete>
-
-// Autocomplete Properties
-value: string              // Selected value for single-select, comma-separated string for multi-select (legacy API)
-values: string[]           // Array of selected values for multi-select (preferred API for multi-select)
-multi: boolean             // Enable multi-select mode
-label: string              // Input label
-placeholder: string        // Input placeholder
-required: boolean          // Mark as required for validation
-size: string               // Input size: "sm", "md", "lg"
-maxHeight: string          // Maximum height of dropdown (default: "300px")
-debounceMs: number         // Debounce delay in milliseconds for filtering (default: 200)
-similarityThreshold: number // Minimum similarity score to show option (0-1, default: 0.3)
-autocomplete: string       // Value for input's autocomplete attribute
-description: string        // Description for screen readers
-name: string               // Form field name for form submission
-
-// Autocomplete Events
-@change   // Fires when selection changes with { detail: { value, values? } }
-
-// Autocomplete Methods
-checkValidity() -> boolean    // Check if the input is valid
-reportValidity() -> boolean   // Show validation state and return validity
-
-// Examples
-// Basic usage
-<schmancy-autocomplete
-  label="Country"
-  placeholder="Select country"
-  @change=${(e) => selectedCountry = e.detail.value}>
-  
-  <schmancy-option value="us">United States</schmancy-option>
-  <schmancy-option value="ca">Canada</schmancy-option>
-  <schmancy-option value="mx">Mexico</schmancy-option>
-  <schmancy-option value="fr">France</schmancy-option>
-  <schmancy-option value="de">Germany</schmancy-option>
+## Usage
+```html
+<schmancy-autocomplete label="Assignee" placeholder="Search...">
+  <schmancy-option value="alice" label="Alice"></schmancy-option>
+  <schmancy-option value="bob" label="Bob"></schmancy-option>
 </schmancy-autocomplete>
+```
 
-// Multi-select with preferred API
-<schmancy-autocomplete
-  label="Programming Languages"
-  placeholder="Select languages"
-  multi
-  .values=${selectedLanguages}
-  @change=${(e) => {
-    selectedLanguages = e.detail.values; // Use the new values array property
-  }}>
-  
-  <schmancy-option value="js">JavaScript</schmancy-option>
-  <schmancy-option value="ts">TypeScript</schmancy-option>
-  <schmancy-option value="py">Python</schmancy-option>
-  <schmancy-option value="java">Java</schmancy-option>
-  <schmancy-option value="go">Go</schmancy-option>
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| value | string | `''` | Selected value (single) or comma-separated (multi) |
+| values | string[] | `[]` | Selected values (multi-select) |
+| label | string | `''` | Label text |
+| placeholder | string | `''` | Placeholder text |
+| name | string | `''` | Form submission name |
+| required | boolean | `false` | Whether selection is required |
+| multi | boolean | `false` | Enable multi-select with inline chips |
+| size | `'xs'\|'sm'\|'md'\|'lg'` | `'md'` | Input height |
+| maxHeight | string | `'300px'` | Max dropdown height |
+| debounceMs | number | `200` | Search debounce in ms |
+| similarityThreshold | number | `0.3` | Minimum fuzzy match score (0-1) |
+| error | boolean | `false` | Error state |
+| validationMessage | string | `''` | Validation message |
+| description | string | `''` | Screen reader description |
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| change | `{ value: string \| string[], values?: string[] }` | When selection changes |
+
+## Examples
+```html
+<!-- Multi-select with chips -->
+<schmancy-autocomplete label="Skills" multi placeholder="Type to search...">
+  <schmancy-option value="ts" label="TypeScript"></schmancy-option>
+  <schmancy-option value="lit" label="Lit"></schmancy-option>
+  <schmancy-option value="rxjs" label="RxJS"></schmancy-option>
 </schmancy-autocomplete>
 
-// Handling the change event
-handleChange(e) {
-  if (e.target.multi) {
-    const selectedValues = e.detail.values; // Array of values (preferred)
-    const legacyValue = e.detail.value;     // Comma-separated string (legacy)
-    console.log('Selected:', selectedValues);
-  } else {
-    const selectedValue = e.detail.value;   // Single value
-    console.log('Selected:', selectedValue);
-  }
-}
-
-// Dynamic options from data
-<schmancy-autocomplete
-  label="Select Item"
-  .value=${selectedItem}>
-  
-  ${items.map(item => html`
-    <schmancy-option value=${item.id}>
-      ${item.name}
-    </schmancy-option>
-  `)}
+<!-- Single select, auto-selects best match on blur -->
+<schmancy-autocomplete label="City" placeholder="Search city..."
+  @change=${(e) => console.log(e.detail.value)}>
+  <schmancy-option value="berlin" label="Berlin"></schmancy-option>
+  <schmancy-option value="munich" label="Munich"></schmancy-option>
 </schmancy-autocomplete>
-
-// In a form
-<schmancy-form @submit=${handleSubmit}>
-  <schmancy-input
-    name="name"
-    label="Name"
-    required>
-  </schmancy-input>
-  
-  <schmancy-autocomplete
-    name="department"
-    label="Department"
-    required>
-    <schmancy-option value="hr">Human Resources</schmancy-option>
-    <schmancy-option value="eng">Engineering</schmancy-option>
-    <schmancy-option value="fin">Finance</schmancy-option>
-  </schmancy-autocomplete>
-  
-  <schmancy-button type="submit">Submit</schmancy-button>
-</schmancy-form>
 ```
 
-## Key Features
-
-### Fuzzy Search
-- Uses similarity scoring algorithm to find best matches
-- Searches both option labels and values
-- Configurable similarity threshold (0-1)
-- Options are sorted by relevance score
-
-### Keyboard Navigation
-- `ArrowDown/ArrowUp` - Navigate through options
-- `Enter/Space` - Select focused option
-- `Escape` - Close dropdown
-- `Tab` - Move to next field and close dropdown
-- `Home/End` - Jump to first/last option
-
-### Auto-Select on Blur
-- In single-select mode, automatically selects the best matching option when input loses focus
-- Only triggers if there's a search term and a good match
-- Helps with quick data entry
-
-### Accessibility
-- Full ARIA support with proper roles and attributes
-- Screen reader announcements for option counts and selections
-- Keyboard-only navigation support
-- Focus management
-
-### Performance
-- Debounced search input (configurable delay)
-- Efficient RxJS-based state management
-- Virtual scrolling for large option lists
-- Options are only filtered when dropdown is open
+Children must be `<schmancy-option>` elements. In multi mode, selected items appear as removable chips.