@mhmo91/schmancy 0.2.194 → 0.2.196

package/ai/theme.md

@@ -0,0 +1,241 @@
+# Theme Component
+
+A powerful theming system that generates Material Design 3 color schemes from a source color, with automatic dark/light mode support and CSS custom property injection.
+
+## Quick Start
+
+```html
+<!-- Basic theme with auto color -->
+<schmancy-theme>
+  <div class="my-app">
+    <!-- All children inherit theme -->
+  </div>
+</schmancy-theme>
+
+<!-- Custom color theme -->
+<schmancy-theme color="#6750A4" scheme="light">
+  <schmancy-card>
+    <h2>Themed Content</h2>
+  </schmancy-card>
+</schmancy-theme>
+
+<!-- Root-level theme -->
+<schmancy-theme color="#00695C" root>
+  <!-- Theme applies to entire document -->
+</schmancy-theme>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `color` | `string` | `random` | Source color for theme generation |
+| `scheme` | `'dark' \| 'light' \| 'auto'` | `'auto'` | Color scheme mode |
+| `root` | `boolean` | `false` | Apply theme to document root |
+| `theme` | `Partial<TSchmancyTheme>` | `{}` | Custom theme overrides |
+
+## Material Design 3 Integration
+
+The component uses Google's Material Color Utilities to generate a complete color system:
+
+```typescript
+import { argbFromHex, themeFromSourceColor } from '@material/material-color-utilities';
+
+// Generates full MD3 color palette
+const theme = themeFromSourceColor(argbFromHex('#6750A4'));
+```
+
+## Examples
+
+### App-Wide Theme
+```html
+<!-- In your app root -->
+<schmancy-theme color="#1976D2" root>
+  <schmancy-app>
+    <!-- Entire app uses this theme -->
+  </schmancy-app>
+</schmancy-theme>
+```
+
+### Component-Level Theming
+```html
+<!-- Different sections with different themes -->
+<div class="dashboard">
+  <schmancy-theme color="#00897B">
+    <section class="analytics">
+      <!-- Teal theme -->
+    </section>
+  </schmancy-theme>
+  
+  <schmancy-theme color="#E53935">
+    <section class="alerts">
+      <!-- Red theme for alerts -->
+    </section>
+  </schmancy-theme>
+</div>
+```
+
+### Dark Mode Support
+```html
+<!-- Automatic dark/light switching -->
+<schmancy-theme scheme="auto">
+  <schmancy-surface>
+    <p>Adapts to system preferences</p>
+  </schmancy-surface>
+</schmancy-theme>
+
+<!-- Force dark mode -->
+<schmancy-theme scheme="dark" color="#673AB7">
+  <schmancy-card>
+    <h3>Always Dark</h3>
+  </schmancy-card>
+</schmancy-theme>
+```
+
+### Theme Overrides
+```html
+<schmancy-theme 
+  color="#FF5722"
+  .theme="${{
+    sys: {
+      color: {
+        primary: {
+          default: '#FF5722',
+          onDefault: '#FFFFFF'
+        }
+      }
+    }
+  }}"
+>
+  <schmancy-button variant="filled">
+    Custom Themed Button
+  </schmancy-button>
+</schmancy-theme>
+```
+
+## Generated CSS Properties
+
+The theme generates a comprehensive set of CSS custom properties:
+
+```css
+/* Primary colors */
+--schmancy-sys-color-primary-default
+--schmancy-sys-color-primary-onDefault
+--schmancy-sys-color-primary-container
+--schmancy-sys-color-primary-onContainer
+
+/* Secondary colors */
+--schmancy-sys-color-secondary-default
+--schmancy-sys-color-secondary-onDefault
+--schmancy-sys-color-secondary-container
+--schmancy-sys-color-secondary-onContainer
+
+/* Tertiary colors */
+--schmancy-sys-color-tertiary-default
+--schmancy-sys-color-tertiary-onDefault
+
+/* Surface colors */
+--schmancy-sys-color-surface-default
+--schmancy-sys-color-surface-on
+--schmancy-sys-color-surface-container
+--schmancy-sys-color-surface-containerHigh
+--schmancy-sys-color-surface-containerHighest
+
+/* And many more... */
+```
+
+## Auto Color Scheme Detection
+
+```javascript
+// Automatically detects system preference
+const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+
+// Reactive updates when system preference changes
+scheme === 'auto' && mediaQuery.addEventListener('change', updateTheme);
+```
+
+## Random Color Generation
+
+When no color is specified, generates a random color:
+
+```javascript
+generateRandomColor() {
+  const randomColor = Math.floor(Math.random() * 16777215).toString(16);
+  return '#' + randomColor.padStart(6, '0');
+}
+```
+
+## Context Provider
+
+The theme component provides its theme via Lit Context:
+
+```javascript
+import { consume } from '@lit/context';
+import { themeContext } from '@schmancy/theme';
+
+// In child components
+@consume({ context: themeContext })
+theme: TSchmancyTheme;
+```
+
+## Advanced Usage
+
+### Nested Themes
+```html
+<schmancy-theme color="#2196F3" scheme="light">
+  <div class="main-content">
+    <!-- Blue light theme -->
+    
+    <schmancy-theme color="#F44336" scheme="dark">
+      <aside class="sidebar">
+        <!-- Red dark theme -->
+      </aside>
+    </schmancy-theme>
+  </div>
+</schmancy-theme>
+```
+
+### Dynamic Theme Changes
+```javascript
+const themeEl = document.querySelector('schmancy-theme');
+
+// Change color
+themeEl.color = '#9C27B0';
+
+// Switch scheme
+themeEl.scheme = 'dark';
+
+// Apply custom overrides
+themeEl.theme = {
+  sys: {
+    color: {
+      error: {
+        default: '#FF0000'
+      }
+    }
+  }
+};
+```
+
+## Best Practices
+
+1. **Root Theme**: Use one root theme for consistency
+2. **Color Choice**: Pick colors with good contrast ratios
+3. **Scheme Handling**: Respect user preferences with 'auto'
+4. **Performance**: Limit nested themes
+5. **Accessibility**: Test themes with contrast checkers
+
+## Related Components
+
+- [Theme Button](./theme-button.md) - Theme switcher
+- [Surface](./surface.md) - Themed containers
+- [Button](./button.md) - Themed interactions
+- [Card](./card.md) - Themed content
+
+## Use Cases
+
+1. **App Theming**: Consistent app-wide styling
+2. **White-Label**: Dynamic branding
+3. **User Preferences**: Personalized themes
+4. **Section Theming**: Different themes for app sections
+5. **A/B Testing**: Theme variations for testing

package/ai/typewriter.md

@@ -0,0 +1,217 @@
+# Typewriter Component
+
+An engaging text animation component that simulates typing effects with customizable speed, delays, and advanced sequencing capabilities.
+
+## Quick Start
+
+```html
+<!-- Basic typewriter effect -->
+<schmancy-typewriter>
+  Hello, World! This text will be typed out character by character.
+</schmancy-typewriter>
+
+<!-- With custom speed -->
+<schmancy-typewriter speed="30" delay="500">
+  Fast typing with a delay before starting.
+</schmancy-typewriter>
+
+<!-- With actions -->
+<schmancy-typewriter>
+  Type this first.
+  <span action="pause" value="1000"></span>
+  Then type this after a pause.
+  <span action="delete" value="10"></span>
+  And finally this!
+</schmancy-typewriter>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `speed` | `number` | `50` | Typing speed (ms per character) |
+| `delay` | `number` | `0` | Initial delay before typing starts |
+| `autoStart` | `boolean` | `true` | Start typing automatically |
+| `cursorChar` | `string` | `''` | Custom cursor character |
+| `deleteSpeed` | `number` | `25` | Speed for deletion (ms per character) |
+| `once` | `boolean` | `true` | Only animate once per session |
+
+## Events
+
+### typeit-complete
+Fired when typing animation completes.
+
+```javascript
+element.addEventListener('typeit-complete', () => {
+  console.log('Typing finished!');
+});
+```
+
+## Examples
+
+### Hero Section
+```html
+<div class="hero">
+  <h1>
+    <schmancy-typewriter speed="100" delay="300">
+      Welcome to the Future
+    </schmancy-typewriter>
+  </h1>
+  <p>
+    <schmancy-typewriter delay="2000" speed="40">
+      Where innovation meets possibility.
+    </schmancy-typewriter>
+  </p>
+</div>
+```
+
+### Multi-line Typing
+```html
+<schmancy-typewriter speed="60">
+  <p>First paragraph of text.</p>
+  <p>Second paragraph appears on a new line.</p>
+  <p>Third paragraph continues the story.</p>
+</schmancy-typewriter>
+```
+
+### Terminal Effect
+```html
+<div class="terminal">
+  <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>
+</div>
+```
+
+### Dynamic Typing Sequence
+```html
+<schmancy-typewriter>
+  We are
+  <span action="pause" value="500"></span>
+  developers
+  <span action="delete" value="10"></span>
+  designers
+  <span action="delete" value="9"></span>
+  innovators
+  <span action="pause" value="1000"></span>
+  !
+</schmancy-typewriter>
+```
+
+### Code Tutorial
+```html
+<schmancy-typewriter speed="40">
+  <code>
+    function greet(name) {
+      <span action="pause" value="300"></span>
+      return `Hello, ${name}!`;
+      <span action="pause" value="300"></span>
+    }
+  </code>
+</schmancy-typewriter>
+```
+
+## Actions System
+
+Special action elements control typing behavior:
+
+| Action | Value | Description |
+|--------|-------|-------------|
+| `pause` | milliseconds | Pause typing for specified duration |
+| `delete` | character count | Delete specified number of characters |
+
+```html
+<span action="pause" value="1000"></span> <!-- 1 second pause -->
+<span action="delete" value="5"></span> <!-- Delete 5 characters -->
+```
+
+## Features
+
+### Session Memory
+When `once` is true, remembers completion state per session:
+- Uses sessionStorage with content hash
+- Skips animation on repeat views
+- Clears on session end
+
+### Context Integration
+Inherits delay from parent `schmancy-delay` components:
+
+```html
+<schmancy-delay delay="1000">
+  <schmancy-typewriter> <!-- Inherits 1000ms delay -->
+    This starts typing after 1 second
+  </schmancy-typewriter>
+</schmancy-delay>
+```
+
+### Intersection Observer
+Only starts typing when element is in viewport:
+- Efficient performance
+- Better user experience
+- Automatic trigger on scroll
+
+### TypeIt Integration
+Powered by the TypeIt library for smooth, reliable animations.
+
+## Styling
+
+```css
+/* Hide cursor after completion */
+schmancy-typewriter {
+  --ti-cursor-display: none;
+}
+
+/* Custom cursor styling */
+schmancy-typewriter .ti-cursor {
+  color: var(--schmancy-sys-color-primary-default);
+  font-weight: normal;
+}
+```
+
+## Advanced Configuration
+
+```javascript
+// TypeIt options passed through
+const typeItOptions = {
+  speed: this.speed,
+  startDelay: this.delay,
+  cursor: !!this.cursorChar,
+  cursorChar: this.cursorChar,
+  deleteSpeed: this.deleteSpeed,
+  afterComplete: () => {
+    // Custom completion logic
+  }
+};
+```
+
+## Accessibility
+
+- Uses `aria-live="polite"` for screen reader support
+- Completed text remains in DOM
+- Semantic HTML structure maintained
+
+## Best Practices
+
+1. **Speed**: 40-80ms for comfortable reading speed
+2. **Delays**: Use pauses for emphasis
+3. **Content**: Keep animations short and meaningful
+4. **Performance**: Limit concurrent typewriters
+5. **Mobile**: Test on various devices
+
+## Related Components
+
+- [Animated Text](./animated-text.md) - Word/letter animations
+- [Delay](./delay.md) - Coordinated delays
+- [Typography](./typography.md) - Text styling
+
+## Use Cases
+
+1. **Landing Pages**: Engaging hero text
+2. **Tutorials**: Step-by-step code examples
+3. **Storytelling**: Narrative experiences
+4. **Loading States**: Entertaining wait messages
+5. **Terminal UIs**: Command-line interfaces

package/dist/_headers

@@ -0,0 +1,2 @@
+/*
+  Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-eval' 'unsafe-inline' https://cdn.jsdelivr.net/npm/ https://www.claudeusercontent.com https://cdnjs.cloudflare.com https://cdn.jsdelivr.net/pyodide/; style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net/npm/; font-src 'self' data: https://cdn.jsdelivr.net/npm/; img-src 'self' data: https: blob:; connect-src 'self' https:

package/dist/ai/animated-text.md

@@ -0,0 +1,114 @@
+# Schmancy Animated Text - AI Reference
+
+```js
+// Animated Text Component
+<schmancy-animated-text
+  ease="outExpo"
+  delay="0"
+  stagger="50"
+  duration="750"
+  scale="[0, 1]"
+  opacity="[0, 1]"
+  translateX="['0.55em', '0em']"
+  translateY="['1.1em', '0em']"
+  rotate3d="[0, 0, 1, 45]">
+  Text to animate
+</schmancy-animated-text>
+
+// Animation Properties
+ease: string           // Animation easing function (default: "outExpo")
+delay: number          // Initial delay in milliseconds (default: 0)
+stagger: number        // Delay between letter animations (default: 50)
+duration: number       // Animation duration in milliseconds (default: 750)
+scale: number[]        // Scale transformation [from, to] (default: [0, 1])
+opacity: number[]      // Opacity transition [from, to] (default: [0, 1])
+translateX: string[]   // X translation ["from", "to"] (default: ['0.55em', '0em'])
+translateY: string[]   // Y translation ["from", "to"] (default: ['1.1em', '0em'])
+rotate3d: number[]     // 3D rotation [x, y, z, angle] (default: [0, 0, 1, 45])
+
+// Examples
+// 1. Basic fade in
+<schmancy-animated-text>
+  Welcome to our application
+</schmancy-animated-text>
+
+// 2. Custom stagger effect
+<schmancy-animated-text
+  stagger="100"
+  duration="1000"
+  translateY="['2em', '0em']">
+  Cascading Letters
+</schmancy-animated-text>
+
+// 3. Scale and rotate effect
+<schmancy-animated-text
+  scale="[0.5, 1]"
+  rotate3d="[0, 1, 0, 180]"
+  duration="1500">
+  Dramatic Entrance
+</schmancy-animated-text>
+
+// 4. No translation effect
+<schmancy-animated-text
+  translateX="['0em', '0em']"
+  translateY="['0em', '0em']"
+  opacity="[0, 1]">
+  Fade Only
+</schmancy-animated-text>
+```
+
+## Related Components
+- **[Typography](./typography.md)**: Base text styling component
+- **[Typewriter](./typewriter.md)**: Alternative text animation with typing effect
+
+## Technical Details
+
+### Animation Behavior
+- Text is split into individual letter spans
+- Each letter animates with the specified stagger delay
+- Uses Web Animations API for performance
+- Animations trigger on component mount and when text changes
+- Responsive to viewport visibility
+
+### CSS Classes
+- `.ml7`: Main wrapper class
+- `.text-wrapper`: Container for animated text
+- `.letter`: Individual animated letter span
+
+## Common Use Cases
+
+1. **Hero Text**: Large headings with dramatic entrance animations
+   ```html
+   <h1>
+     <schmancy-animated-text duration="2000" scale="[0.3, 1]">
+       Welcome to Schmancy
+     </schmancy-animated-text>
+   </h1>
+   ```
+
+2. **Loading Messages**: Staggered letter animations for loading states
+   ```html
+   <schmancy-animated-text stagger="100" translateY="['1em', '0em']">
+     Loading...
+   </schmancy-animated-text>
+   ```
+
+3. **Notifications**: Subtle fade-in for status messages
+   ```html
+   <schmancy-animated-text 
+     duration="500" 
+     translateX="['0em', '0em']"
+     translateY="['0em', '0em']">
+     Operation completed successfully
+   </schmancy-animated-text>
+   ```
+
+4. **Interactive Reveals**: Combined with visibility triggers
+   ```html
+   <schmancy-animated-text 
+     delay="500"
+     stagger="75"
+     opacity="[0, 1]">
+     Scroll to reveal this text
+   </schmancy-animated-text>
+   ```