@mhmo91/schmancy 0.2.195 → 0.2.197

package/ai/theme-button.md

@@ -0,0 +1,173 @@
+# Theme Button Component
+
+A simple, animated button component for theme switching functionality with a rotating palette icon.
+
+## Quick Start
+
+```html
+<!-- Basic theme button -->
+<schmancy-theme-button></schmancy-theme-button>
+
+<!-- In a toolbar -->
+<schmancy-appbar>
+  <h1 slot="title">My App</h1>
+  <schmancy-theme-button slot="actions"></schmancy-theme-button>
+</schmancy-appbar>
+```
+
+## Properties
+
+The component inherits all properties from the base button component through `TailwindElement`.
+
+## Features
+
+### Animated Icon
+The palette icon rotates 360 degrees when clicked:
+
+```javascript
+this.color.animate([
+  { transform: 'rotate(0deg)' },
+  { transform: 'rotate(360deg)' }
+], {
+  duration: 300
+});
+```
+
+### Native Web Animations
+Uses the Web Animations API for smooth, performant animations without external dependencies.
+
+## Examples
+
+### In Navigation Bar
+```html
+<nav class="flex items-center justify-between p-4">
+  <h1>Brand</h1>
+  <div class="flex gap-2">
+    <schmancy-theme-button></schmancy-theme-button>
+    <schmancy-icon-button>settings</schmancy-icon-button>
+  </div>
+</nav>
+```
+
+### With Custom Theme Logic
+```html
+<schmancy-theme-button @click="${() => {
+  // Toggle between themes
+  const currentTheme = document.querySelector('schmancy-theme');
+  currentTheme.scheme = currentTheme.scheme === 'light' ? 'dark' : 'light';
+}}"></schmancy-theme-button>
+```
+
+### In a Settings Panel
+```html
+<schmancy-card>
+  <h3 slot="header">Appearance Settings</h3>
+  
+  <div class="space-y-4">
+    <div class="flex items-center justify-between">
+      <span>Theme</span>
+      <schmancy-theme-button></schmancy-theme-button>
+    </div>
+    
+    <schmancy-divider></schmancy-divider>
+    
+    <schmancy-select label="Color Scheme">
+      <schmancy-option value="auto">Auto</schmancy-option>
+      <schmancy-option value="light">Light</schmancy-option>
+      <schmancy-option value="dark">Dark</schmancy-option>
+    </schmancy-select>
+  </div>
+</schmancy-card>
+```
+
+### With Tooltip
+```html
+<schmancy-tooltip content="Change theme">
+  <schmancy-theme-button></schmancy-theme-button>
+</schmancy-tooltip>
+```
+
+## Implementation Details
+
+The component structure:
+- Uses `schmancy-button` with text variant
+- Contains `schmancy-icon` with palette icon
+- Applies rotation animation on click
+- Maintains reference to icon element via `@query`
+
+## Styling
+
+Since it uses the base button component, all button styling applies:
+
+```css
+/* Custom positioning in toolbar */
+schmancy-theme-button {
+  margin-left: auto;
+}
+
+/* Adjust icon size */
+schmancy-theme-button schmancy-icon {
+  font-size: 1.25rem;
+}
+```
+
+## Animation Customization
+
+You can extend the animation behavior:
+
+```javascript
+// Custom animation options
+{
+  duration: 300,
+  easing: 'ease-out',
+  fill: 'forwards'  // Keep final rotation state
+}
+```
+
+## Integration with Theme System
+
+While the button provides the UI, you'll need to implement the theme switching logic:
+
+```javascript
+// Example theme toggle implementation
+class MyApp extends LitElement {
+  toggleTheme() {
+    const theme = this.shadowRoot.querySelector('schmancy-theme');
+    const themes = ['#6750A4', '#00695C', '#D32F2F', '#1976D2'];
+    const currentIndex = themes.indexOf(theme.color);
+    theme.color = themes[(currentIndex + 1) % themes.length];
+  }
+  
+  render() {
+    return html`
+      <schmancy-theme>
+        <schmancy-theme-button @click="${this.toggleTheme}">
+        </schmancy-theme-button>
+      </schmancy-theme>
+    `;
+  }
+}
+```
+
+## Best Practices
+
+1. **Placement**: Put in consistent location (usually top-right)
+2. **Feedback**: The rotation provides immediate feedback
+3. **Persistence**: Save theme preference to localStorage
+4. **Accessibility**: Include proper ARIA labels
+5. **Mobile**: Ensure adequate touch target size
+
+## Related Components
+
+- [Theme](./theme.md) - The theming system
+- [Button](./button.md) - Base button component
+- [Icon](./icons.md) - Icon system
+- [Tooltip](./tooltip.md) - Help text
+
+## Use Cases
+
+1. **App Headers**: Quick theme toggle in navigation
+2. **Settings Pages**: Part of appearance settings
+3. **Demos**: Showcase theme capabilities
+4. **User Preferences**: Personalization options
+5. **Accessibility**: High contrast mode switching

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