@mhmo91/schmancy 0.8.4 → 0.9.2

package/src/types/mood-audio.types.ts

@@ -0,0 +1,220 @@
+/**
+ * Types for mood-based audio generation
+ * Local copy for Schmancy package to avoid external dependency
+ */
+
+/**
+ * Puff sound parameters - soft air/breath sounds
+ */
+export interface PuffParams {
+	/** Start time offset in seconds */
+	startTime: number
+	/** Duration in seconds (typically 0.04 - 0.45) */
+	duration: number
+	/** Frequency in Hz (typically 400 - 3500) */
+	frequency: number
+	/** Volume level (0.0 - 1.0, typically 0.1 - 0.35) */
+	volume: number
+}
+
+/**
+ * Tone sound parameters - musical tones
+ */
+export interface ToneParams {
+	/** Start time offset in seconds */
+	startTime: number
+	/** Duration in seconds (typically 0.08 - 0.5) */
+	duration: number
+	/** Frequency in Hz (musical note, typically 262 - 1319 Hz) */
+	frequency: number
+	/** Volume level (0.0 - 1.0, typically 0.1 - 0.3) */
+	volume: number
+	/** Oscillator type */
+	type: 'sine' | 'triangle' | 'square' | 'sawtooth'
+	/** Optional ending frequency for pitch bends */
+	frequencyEnd?: number
+	/** Optional filter frequency for warm tones */
+	filterFrequency?: number
+}
+
+/**
+ * Complete audio sequence generated by AI
+ */
+export interface AudioSequence {
+	/** Array of puff (breath/air) sounds */
+	puffs: PuffParams[]
+	/** Array of tone (musical) sounds */
+	tones: ToneParams[]
+	/** Overall volume modifier (0.0 - 1.0) */
+	masterVolume: number
+	/** Description of the emotional quality */
+	emotionalDescription: string
+}
+
+/**
+ * Request to generate mood audio
+ */
+export interface GenerateMoodAudioRequest {
+	/** User's description of their mood */
+	moodText: string
+	/** Current theme color in hex format */
+	themeColor: string
+	/** Current color scheme */
+	scheme: 'dark' | 'light' | 'auto'
+}
+
+/**
+ * Response from mood audio generation
+ */
+export interface GenerateMoodAudioResponse {
+	/** Whether generation was successful */
+	success: boolean
+	/** Generated audio sequence (null if failed) */
+	audioSequence: AudioSequence | null
+	/** Detected mood from the text */
+	detectedMood: string
+	/** Confidence level (0-1) */
+	confidence: number
+	/** Error message if failed */
+	error?: string
+}
+
+// ============================================================================
+// SOUND THEME TYPES
+// ============================================================================
+
+/** Feeling category names */
+export type FeelingCategory = 'happy' | 'sad' | 'anxious' | 'angry' | 'tired' | 'calm' | 'connected' | 'mixed'
+
+/** Happy / Pleasant feelings */
+export type HappyFeeling =
+	| 'joyful' | 'content' | 'excited' | 'proud' | 'hopeful'
+	| 'relieved' | 'grateful' | 'peaceful' | 'playful' | 'amused'
+	| 'curious' | 'inspired' | 'confident' | 'loved' | 'comforted' | 'energized'
+	| 'celebrated'
+
+/** Sad / Low feelings */
+export type SadFeeling =
+	| 'sad' | 'lonely' | 'disappointed' | 'heartbroken' | 'grieving'
+	| 'hopeless' | 'empty' | 'discouraged' | 'melancholic' | 'homesick'
+	| 'hurt' | 'miserable' | 'regretful' | 'ashamed' | 'inferior'
+
+/** Anxious / Fearful feelings */
+export type AnxiousFeeling =
+	| 'anxious' | 'worried' | 'afraid' | 'terrified' | 'panicked'
+	| 'nervous' | 'uneasy' | 'insecure' | 'overwhelmed' | 'stressed'
+	| 'tense' | 'apprehensive' | 'startled' | 'suspicious' | 'vulnerable'
+
+/** Angry / Frustrated feelings */
+export type AngryFeeling =
+	| 'annoyed' | 'irritated' | 'frustrated' | 'angry' | 'enraged'
+	| 'bitter' | 'resentful' | 'jealous' | 'envious' | 'indignant'
+	| 'impatient' | 'hostile' | 'contemptuous'
+
+/** Tired / Drained feelings */
+export type TiredFeeling =
+	| 'tired' | 'exhausted' | 'drained' | 'burnedOut' | 'numb'
+	| 'bored' | 'unmotivated' | 'apathetic' | 'restless'
+
+/** Calm / Grounded feelings */
+export type CalmFeeling =
+	| 'calm' | 'relaxed' | 'atEase' | 'balanced' | 'stable'
+	| 'secure' | 'safe' | 'centered' | 'grounded' | 'accepting'
+
+/** Connected / Social feelings */
+export type ConnectedFeeling =
+	| 'connected' | 'accepted' | 'included' | 'belonging' | 'appreciated'
+	| 'valued' | 'respected' | 'supported' | 'protective' | 'compassionate' | 'empathetic'
+
+/** Mixed / Complicated feelings */
+export type MixedFeeling =
+	| 'conflicted' | 'confused' | 'ambivalent' | 'nostalgic' | 'guilty'
+	| 'embarrassed' | 'surprised' | 'shocked' | 'awestruck' | 'skeptical'
+
+/** All feeling types */
+export type Feeling =
+	| HappyFeeling | SadFeeling | AnxiousFeeling | AngryFeeling
+	| TiredFeeling | CalmFeeling | ConnectedFeeling | MixedFeeling
+
+/**
+ * Sound definition for a single feeling
+ * Contains the puffs and tones that make up the emotional sound
+ */
+export interface FeelingSound {
+	/** Puff sounds (breath/air) for this feeling */
+	puffs: PuffParams[]
+	/** Tone sounds (musical) for this feeling */
+	tones: ToneParams[]
+	/** Optional description of the sound character */
+	description?: string
+}
+
+/**
+ * Complete Sound Theme - like a color palette but for sounds
+ * Defines how each emotion sounds
+ */
+export interface SoundTheme {
+	/** Theme identifier */
+	name: string
+	/** Human-readable description */
+	description: string
+	/** Master volume modifier (0.0 - 1.0) */
+	masterVolume: number
+	/** Sound definitions for each feeling - partial allows overriding specific feelings */
+	feelings: Partial<Record<Feeling, FeelingSound>>
+	/** Category-level defaults - used when specific feeling not defined */
+	categoryDefaults?: Partial<Record<FeelingCategory, FeelingSound>>
+	/** Metadata about the theme origin */
+	metadata?: {
+		/** Source color that inspired this theme */
+		sourceColor?: string
+		/** Source mood text */
+		sourceMood?: string
+		/** Color scheme when generated */
+		scheme?: 'dark' | 'light' | 'auto'
+		/** When the theme was generated */
+		generatedAt?: string
+		/** AI model that generated it */
+		generatedBy?: string
+	}
+}
+
+/**
+ * Sound theme settings stored in context
+ */
+export interface SoundThemeSettings {
+	/** Current active sound theme (null = use defaults) */
+	theme: SoundTheme | null
+	/** Global volume (0.0 - 1.0) */
+	volume: number
+	/** Whether sounds are muted */
+	muted: boolean
+}
+
+/**
+ * Request to generate a sound theme from AI
+ */
+export interface GenerateSoundThemeRequest {
+	/** User's mood description */
+	moodText: string
+	/** Theme color in hex */
+	themeColor: string
+	/** Color scheme */
+	scheme: 'dark' | 'light' | 'auto'
+	/** Which feelings to generate sounds for (optional - default all) */
+	feelings?: Feeling[]
+	/** Which categories to prioritize */
+	priorityCategories?: FeelingCategory[]
+}
+
+/**
+ * Response from sound theme generation
+ */
+export interface GenerateSoundThemeResponse {
+	/** Whether generation succeeded */
+	success: boolean
+	/** Generated sound theme */
+	theme: SoundTheme | null
+	/** Error message if failed */
+	error?: string
+}

package/src/types/surface.ts

@@ -0,0 +1,52 @@
+/**
+ * Luminous Glass surface types.
+ *
+ * Structural types control depth via blur intensity and opacity.
+ * Nothing is opaque — every layer is translucent glass:
+ * - `solid`    — Dense glass, barely translucent (highest readability, 2px blur)
+ * - `subtle`   — Frosted glass panel (8px blur, 65% opacity)
+ * - `glass`    — Full frosted glass with shimmer highlight (16px blur, 30% opacity)
+ * - `luminous` — Glass + animated glow halo for hero panels (24px blur, 22% opacity)
+ *
+ * Semantic types apply tinted glass for status/role:
+ * - `primary`, `secondary`, `tertiary`, `error`, `success`, `warning`, `info`
+ *
+ * Utility types:
+ * - `transparent` — No background
+ * - `outlined`    — Border only with luminous hover
+ */
+
+/** New Luminous Glass types */
+export type TSurfaceColorNew =
+	| 'solid'
+	| 'subtle'
+	| 'glass'
+	| 'luminous'
+	| 'transparent'
+	| 'outlined'
+	| 'primary'
+	| 'secondary'
+	| 'tertiary'
+	| 'error'
+	| 'success'
+	| 'warning'
+	| 'info'
+
+/**
+ * @deprecated Legacy M3 types — mapped to new Luminous Glass equivalents.
+ * - surface, surfaceDim, surfaceBright, containerLowest → solid
+ * - containerLow, container → subtle
+ * - containerHigh, containerHighest, glassOforim → glass
+ */
+export type TSurfaceColorLegacy =
+	| 'surface'
+	| 'surfaceDim'
+	| 'surfaceBright'
+	| 'containerLowest'
+	| 'containerLow'
+	| 'container'
+	| 'containerHigh'
+	| 'containerHighest'
+	| 'glassOforim'
+
+export type TSurfaceColor = TSurfaceColorNew | TSurfaceColorLegacy

package/src/typewriter/IMPROVEMENTS.md

@@ -0,0 +1,174 @@
+# Schmancy Typewriter - v2.0 Improvements
+
+## Overview
+The typewriter component has been significantly enhanced with a cleaner, more intuitive API that eliminates manual character counting and makes cycling text effortless.
+
+## Key Improvements
+
+### 1. **Cycle API - No More Manual Counting! 🎉**
+
+**Before (Error-prone):**
+```html
+<schmancy-typewriter>
+  We are developers
+  <span action="delete" value="10"></span>  <!-- Had to count: "developers" = 10 chars -->
+  designers
+  <span action="delete" value="9"></span>   <!-- Had to count: "designers" = 9 chars -->
+  innovators
+</schmancy-typewriter>
+```
+
+**After (Clean & Simple):**
+```html
+<schmancy-typewriter>
+  We are <span cycle="developers | designers | innovators"></span>
+</schmancy-typewriter>
+```
+
+**Benefits:**
+- ✅ Automatic character deletion
+- ✅ No counting required
+- ✅ Less error-prone
+- ✅ Easier to maintain
+- ✅ More readable
+
+### 2. **Infinite Looping Support**
+
+```html
+<schmancy-typewriter loop>
+  <span cycle="Amazing | Incredible | Fantastic"></span>
+</schmancy-typewriter>
+```
+
+The animation now supports infinite cycling - perfect for hero sections and attention-grabbing headlines.
+
+### 3. **Flexible Pause Controls**
+
+```html
+<!-- Global pause for all cycles -->
+<schmancy-typewriter cyclePause="2000">
+  <span cycle="Fast | Secure | Reliable"></span>
+</schmancy-typewriter>
+
+<!-- Override pause for specific cycle -->
+<span cycle="Option1 | Option2 | Option3" pause="800"></span>
+```
+
+### 4. **Backward Compatible**
+
+All old features still work:
+- `action="pause"`
+- `action="delete"`
+- All existing properties
+
+## New Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `cyclePause` | `number` | `1500` | Default pause between cycle items (ms) |
+| `loop` | `boolean` | `false` | Loop animation infinitely |
+
+## New Attributes (on `<span>` elements)
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `cycle` | `string` | Pipe-separated list of text to cycle through |
+| `pause` | `number` | Override cyclePause for this specific cycle |
+
+## Real-World Example
+
+**Samwa Homepage - Before:**
+```html
+<schmancy-typewriter speed="80" delay="500">
+  Building systems that are
+  <span action="pause" value="800"></span>
+  <br />
+  Trustless
+  <span action="pause" value="1200"></span>
+  <span action="delete" value="9"></span>
+  Permissionless
+  <span action="pause" value="1200"></span>
+  <span action="delete" value="14"></span>
+  Transparent
+  <span action="pause" value="1200"></span>
+  <span action="delete" value="11"></span>
+  Borderless
+  <span action="pause" value="1200"></span>
+  <span action="delete" value="10"></span>
+  Resilient
+  <span action="pause" value="1500"></span>
+  <br />
+  empowering everyone to operate freely.
+</schmancy-typewriter>
+```
+
+**Samwa Homepage - After:**
+```html
+<schmancy-typewriter speed="80" delay="500" cyclePause="1200">
+  Building systems that are
+  <span action="pause" value="800"></span>
+  <br />
+  <span cycle="Trustless | Permissionless | Transparent | Borderless | Resilient" pause="1500"></span>
+  <br />
+  empowering everyone to operate freely.
+</schmancy-typewriter>
+```
+
+**Line reduction:** 20 lines → 10 lines (50% reduction!)
+
+## Migration Guide
+
+### Simple Cycle Pattern
+
+```diff
+- We are developers
+- <span action="delete" value="10"></span>
+- designers
+- <span action="delete" value="9"></span>
+- innovators
++ We are <span cycle="developers | designers | innovators"></span>
+```
+
+### With Pauses
+
+```diff
+- Feature 1
+- <span action="pause" value="1500"></span>
+- <span action="delete" value="9"></span>
+- Feature 2
+- <span action="pause" value="1500"></span>
+- <span action="delete" value="9"></span>
+- Feature 3
++ <span cycle="Feature 1 | Feature 2 | Feature 3" pause="1500"></span>
+```
+
+## Use Cases
+
+Perfect for:
+1. **Hero headlines** - Rotating value propositions
+2. **Product features** - Cycling through benefits
+3. **Job postings** - Dynamic role descriptions
+4. **Testimonials** - Rotating quotes
+5. **Brand values** - Cycling through company values
+
+## Technical Details
+
+### Implementation
+- Auto-calculates string lengths for deletion
+- Respects global `cyclePause` or element-specific `pause`
+- Integrates seamlessly with TypeIt library
+- Supports `loop` mode for infinite cycling
+- Maintains backward compatibility
+
+### Performance
+- No performance impact
+- Same TypeIt engine underneath
+- Just smarter API on top
+
+## Testing
+
+See `test-typewriter.html` for interactive examples.
+
+## Documentation
+
+Full documentation updated in `/packages/schmancy/ai/typewriter.md`

package/src/typewriter/QUICK_REFERENCE.md

@@ -0,0 +1,166 @@
+# Typewriter Quick Reference
+
+## Basic Usage
+
+```html
+<!-- Simple typing -->
+<schmancy-typewriter>
+  Hello, World!
+</schmancy-typewriter>
+
+<!-- With speed and delay -->
+<schmancy-typewriter speed="80" delay="500">
+  This starts typing after 500ms at 80ms per character
+</schmancy-typewriter>
+```
+
+## Cycling Text (NEW! ⭐)
+
+```html
+<!-- Simple cycle -->
+<span cycle="Option1 | Option2 | Option3"></span>
+
+<!-- With custom pause -->
+<span cycle="Fast | Quick | Rapid" pause="800"></span>
+
+<!-- Complete example -->
+<schmancy-typewriter speed="80" cyclePause="1200">
+  We are <span cycle="developers | designers | innovators"></span>
+</schmancy-typewriter>
+```
+
+## Looping (NEW! ⭐)
+
+```html
+<!-- Cycle forever -->
+<schmancy-typewriter loop>
+  <span cycle="Amazing | Incredible | Fantastic"></span>
+</schmancy-typewriter>
+
+<!-- With cursor -->
+<schmancy-typewriter loop cursorChar="|">
+  <span cycle="Fast ⚡ | Secure 🔒 | Reliable ✅"></span>
+</schmancy-typewriter>
+```
+
+## Actions (Classic API)
+
+```html
+<!-- Pause -->
+<span action="pause" value="1000"></span>
+
+<!-- Manual delete -->
+<span action="delete" value="5"></span>
+
+<!-- Combined -->
+<schmancy-typewriter>
+  Type this first.
+  <span action="pause" value="1000"></span>
+  Then this after a pause.
+</schmancy-typewriter>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `speed` | number | 50 | Typing speed (ms per char) |
+| `delay` | number | 0 | Initial delay (ms) |
+| `deleteSpeed` | number | 25 | Delete speed (ms per char) |
+| `cyclePause` | number | 1500 | Pause between cycles (ms) |
+| `cursorChar` | string | '' | Cursor character (empty = none) |
+| `loop` | boolean | false | Loop infinitely |
+| `once` | boolean | true | Only animate once per session |
+| `autoStart` | boolean | true | Start automatically |
+
+## Common Patterns
+
+### Hero Headline
+```html
+<schmancy-typewriter speed="100" delay="300">
+  Welcome to the <span cycle="Future | Innovation | Revolution"></span>
+</schmancy-typewriter>
+```
+
+### Product Features
+```html
+<schmancy-typewriter cyclePause="2000">
+  Our product is <span cycle="Fast ⚡ | Secure 🔒 | Reliable ✅ | Modern 🚀"></span>
+</schmancy-typewriter>
+```
+
+### Job Posting
+```html
+<h2>
+  We're hiring <span cycle="Frontend Developers | Backend Engineers | UI/UX Designers"></span>
+</h2>
+```
+
+### Value Propositions
+```html
+<schmancy-typewriter speed="80" cyclePause="1200">
+  Building systems that are
+  <br />
+  <span cycle="Trustless | Permissionless | Transparent | Borderless | Resilient" pause="1500"></span>
+  <br />
+  empowering everyone to operate freely.
+</schmancy-typewriter>
+```
+
+### Terminal Effect
+```html
+<schmancy-typewriter cursorChar="|" speed="30">
+  $ npm install schmancy-ui
+  <span action="pause" value="500"></span>
+  <p>Installing dependencies...</p>
+  <span action="pause" value="1000"></span>
+  <p>✓ Installation complete!</p>
+</schmancy-typewriter>
+```
+
+## Events
+
+```javascript
+element.addEventListener('typeit-complete', () => {
+  console.log('Typing finished!');
+});
+```
+
+## Tips
+
+1. **Speed**: 40-80ms for comfortable reading
+2. **Delays**: Use pauses for emphasis
+3. **Cycling**: Use for rotating content
+4. **Looping**: Great for hero sections
+5. **Cursor**: Only use when needed (terminal effects)
+
+## When to Use What
+
+| Use Case | Recommended API |
+|----------|----------------|
+| Rotating words | `cycle` attribute |
+| Simple pause | `action="pause"` |
+| Manual delete | `action="delete"` |
+| Forever animation | `loop` property |
+| Hero headlines | `cycle` + `cyclePause` |
+| Complex timing | Classic `action` API |
+
+## Migration Examples
+
+### Before (Manual counting)
+```html
+Fast
+<span action="pause" value="1500"></span>
+<span action="delete" value="4"></span>
+Secure
+<span action="pause" value="1500"></span>
+<span action="delete" value="6"></span>
+Reliable
+```
+
+### After (Automatic)
+```html
+<span cycle="Fast | Secure | Reliable" pause="1500"></span>
+```
+
+**Lines reduced:** 7 → 1 (86% reduction!)

package/src/typewriter/index.ts

@@ -0,0 +1 @@
+export * from './typewriter';