@mhmo91/schmancy 0.2.195 → 0.2.196

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

package/ai/card.md

@@ -1,155 +1,186 @@
 # Schmancy Card - AI Reference
 
 ```js
-// Basic Card
-<schmancy-card>
-  <div>Card content goes here</div>
+// Card Component
+<schmancy-card
+  type="elevated|filled|outlined"
+  elevation="0|1|2|3|4|5">
+  Card content
 </schmancy-card>
 
-// Card with title and content
-<schmancy-card>
-  <schmancy-card-content>
-    <h2>Card Title</h2>
-    <p>Card description text goes here.</p>
-  </schmancy-card-content>
-</schmancy-card>
+// Properties
+type: string          // "elevated", "filled", "outlined" (default: "elevated")
+elevation: number     // Shadow depth 0-5 (default: 0)
 
-// Card with media
-<schmancy-card>
-  <schmancy-card-media
-    image="path/to/image.jpg"
-    alt="Image description"
-    height="200px">
-  </schmancy-card-media>
-  
-  <schmancy-card-content>
-    <h2>Card with Media</h2>
-    <p>Card content below the image.</p>
-  </schmancy-card-content>
-</schmancy-card>
+// Card Types
+"elevated"            // Surface with shadow, uses surface-low color
+"filled"              // Filled background, uses surface-highest color
+"outlined"            // Border outline, uses surface color
 
-// Card with actions
+// Examples
+// 1. Basic elevated card
 <schmancy-card>
-  <schmancy-card-content>
-    <h2>Card Title</h2>
-    <p>Card content with action buttons.</p>
-  </schmancy-card-content>
-  
-  <schmancy-card-actions>
-    <schmancy-button>Action 1</schmancy-button>
-    <schmancy-button>Action 2</schmancy-button>
-  </schmancy-card-actions>
+  <h3>Card Title</h3>
+  <p>Card content goes here</p>
 </schmancy-card>
 
-// Complete card with all components
-<schmancy-card>
-  <schmancy-card-media
-    image="path/to/image.jpg"
-    alt="Image description">
+// 2. Filled card with custom elevation
+<schmancy-card type="filled" elevation="2">
+  <schmancy-card-media>
+    <img src="image.jpg" alt="Card image">
   </schmancy-card-media>
-  
   <schmancy-card-content>
-    <h2>Card Title</h2>
-    <p>Card description text goes here. This can contain any content.</p>
+    <h3>Product Name</h3>
+    <p>Product description</p>
   </schmancy-card-content>
-  
   <schmancy-card-actions>
-    <schmancy-button kind="tertiary">Cancel</schmancy-button>
-    <schmancy-button kind="primary">Submit</schmancy-button>
+    <schmancy-button>Add to Cart</schmancy-button>
   </schmancy-card-actions>
 </schmancy-card>
 
-// Card Properties
-outlined: boolean        // Shows an outline instead of elevation
-elevation: number        // Shadow elevation level (1-5)
-interactive: boolean     // Enables hover and click effects
+// 3. Outlined card
+<schmancy-card type="outlined">
+  <div style="padding: 16px;">
+    <h4>Settings</h4>
+    <p>Configure your preferences</p>
+  </div>
+</schmancy-card>
 
-// Card Media Properties
-image: string           // URL of the image
-alt: string             // Alt text for the image
-height: string          // Height of the media area
-title: string           // Title to display over the media
+// 4. Interactive card with hover effect
+<schmancy-card elevation="1">
+  <a href="/details" style="text-decoration: none; color: inherit;">
+    <div style="padding: 16px;">
+      <h3>Click for Details</h3>
+      <p>This card has hover elevation changes</p>
+    </div>
+  </a>
+</schmancy-card>
+```
 
-// Card Actions Properties
-align: string           // Alignment of actions: "start", "end", "space-between", "center"
-direction: string       // Direction of actions: "row", "column"
+## Related Components
+- **[Surface](./surface.md)**: Base container component with more options
+- **[Card Content](./card.md#content)**: Structured content area
+- **[Card Media](./card.md#media)**: Media container for cards
+- **[Card Actions](./card.md#actions)**: Action button container
 
-// Examples
-// Basic card with content
-<schmancy-card>
-  <schmancy-card-content>
-    <h2>Welcome to Schmancy</h2>
-    <p>A modern component library for web applications.</p>
-  </schmancy-card-content>
-</schmancy-card>
+## Technical Details
 
-// Interactive card
-<schmancy-card 
-  interactive
-  @click=${handleCardClick}>
-  <schmancy-card-content>
-    <h3>Click Me</h3>
-    <p>This entire card is clickable.</p>
-  </schmancy-card-content>
-</schmancy-card>
+### CSS Host Styling
+The component uses `:host` selectors for all styling:
+- No wrapper elements - clean component boundary
+- Type and elevation properties reflect to HTML attributes
+- Automatic hover states for elevated and outlined types
 
-// Outlined card
-<schmancy-card outlined>
-  <schmancy-card-content>
-    <h3>Outlined Card</h3>
-    <p>This card has an outline instead of elevation.</p>
-  </schmancy-card-content>
-</schmancy-card>
+### Theme Integration
+```css
+/* Type-based colors */
+type="elevated"  -> --schmancy-sys-color-surface-low
+type="filled"    -> --schmancy-sys-color-surface-highest  
+type="outlined"  -> --schmancy-sys-color-surface-default
 
-// Product card
-<schmancy-card>
-  <schmancy-card-media
-    image="/products/headphones.jpg"
-    alt="Wireless Headphones"
-    height="180px">
-  </schmancy-card-media>
-  
-  <schmancy-card-content>
-    <h3>Wireless Headphones</h3>
-    <p>Premium sound quality with noise cancellation.</p>
-    <p><strong>$149.99</strong></p>
-  </schmancy-card-content>
-  
-  <schmancy-card-actions>
-    <schmancy-button kind="tertiary">Details</schmancy-button>
-    <schmancy-button kind="primary">Add to Cart</schmancy-button>
-  </schmancy-card-actions>
-</schmancy-card>
+/* Outline color */
+--schmancy-sys-color-outlineVariant
+
+/* Elevation shadows */
+--schmancy-sys-elevation-1 through --schmancy-sys-elevation-5
+```
+
+### Hover Behavior
+- Elevated cards: elevation 1 → 2 on hover
+- Filled cards: no elevation → 1 on hover
+- Outlined cards: no elevation → 1 on hover
+
+## Card Sub-components
+
+### Card Content
+```html
+<schmancy-card-content>
+  <h3>Title</h3>
+  <p>Description text</p>
+</schmancy-card-content>
+```
+
+### Card Media  
+```html
+<schmancy-card-media>
+  <img src="image.jpg" alt="Media">
+</schmancy-card-media>
+```
+
+### Card Actions
+```html
+<schmancy-card-actions>
+  <schmancy-button>Action 1</schmancy-button>
+  <schmancy-button variant="text">Action 2</schmancy-button>
+</schmancy-card-actions>
+```
+
+## Common Use Cases
+
+1. **Product Cards**: E-commerce product display
+   ```html
+   <schmancy-card type="elevated">
+     <schmancy-card-media>
+       <img src="product.jpg" alt="Product">
+     </schmancy-card-media>
+     <schmancy-card-content>
+       <h3>Product Name</h3>
+       <p class="price">$29.99</p>
+       <p class="description">Product description...</p>
+     </schmancy-card-content>
+     <schmancy-card-actions>
+       <schmancy-button variant="filled">Add to Cart</schmancy-button>
+       <schmancy-button variant="text">Details</schmancy-button>
+     </schmancy-card-actions>
+   </schmancy-card>
+   ```
+
+2. **Info Cards**: Dashboard or stats display
+   ```html
+   <schmancy-card type="filled" elevation="0">
+     <div style="padding: 24px;">
+       <schmancy-icon icon="users" size="32"></schmancy-icon>
+       <h2>1,234</h2>
+       <p>Active Users</p>
+     </div>
+   </schmancy-card>
+   ```
+
+3. **Settings Cards**: Options or configuration
+   ```html
+   <schmancy-card type="outlined">
+     <schmancy-card-content>
+       <h4>Notification Settings</h4>
+       <schmancy-form>
+         <schmancy-checkbox>Email notifications</schmancy-checkbox>
+         <schmancy-checkbox>Push notifications</schmancy-checkbox>
+       </schmancy-form>
+     </schmancy-card-content>
+   </schmancy-card>
+   ```
+
+4. **Media Cards**: Image galleries
+   ```html
+   <schmancy-card elevation="2">
+     <schmancy-card-media aspect-ratio="16:9">
+       <img src="gallery-image.jpg" alt="Gallery">
+     </schmancy-card-media>
+     <schmancy-card-content>
+       <p>Image caption or description</p>
+     </schmancy-card-content>
+   </schmancy-card>
+   ```
 
-// Card grid layout
-<schmancy-grid
-  columns="1"
-  columns-md="2"
-  columns-lg="3"
-  gap="16px">
-  
-  ${products.map(product => html`
-    <schmancy-card>
-      <schmancy-card-media
-        image=${product.image}
-        alt=${product.name}>
-      </schmancy-card-media>
-      
-      <schmancy-card-content>
-        <h3>${product.name}</h3>
-        <p>${product.description}</p>
-        <p><strong>${product.price}</strong></p>
-      </schmancy-card-content>
-      
-      <schmancy-card-actions>
-        <schmancy-button @click=${() => viewProduct(product)}>
-          View
-        </schmancy-button>
-        <schmancy-button kind="primary" @click=${() => addToCart(product)}>
-          Add to Cart
-        </schmancy-button>
-      </schmancy-card-actions>
-    </schmancy-card>
-  `)}
-</schmancy-grid>
-```
+5. **List Item Cards**: Clickable list items
+   ```html
+   <schmancy-card type="elevated" elevation="1">
+     <a href="/user/123" style="display: flex; padding: 16px; align-items: center; text-decoration: none; color: inherit;">
+       <schmancy-avatar src="user.jpg"></schmancy-avatar>
+       <div style="margin-left: 16px; flex: 1;">
+         <h4>User Name</h4>
+         <p>user@example.com</p>
+       </div>
+       <schmancy-icon icon="chevron-right"></schmancy-icon>
+     </a>
+   </schmancy-card>
+   ```

package/ai/circular-progress.md

@@ -0,0 +1,91 @@
+# Schmancy Circular Progress - AI Reference
+
+```js
+// Circular Progress Component
+<schmancy-circular-progress
+  size="xs|sm|md|lg|xl|{custom}"
+  indeterminate?>
+</schmancy-circular-progress>
+
+// Properties
+size: string          // "xs", "sm", "md", "lg", "xl", or custom size (default: "md")
+indeterminate: boolean // Whether the progress is indeterminate (default: false)
+
+// Size values
+"xs" = 16px
+"sm" = 24px
+"md" = 32px
+"lg" = 48px
+"xl" = 64px
+
+// Examples
+// 1. Basic medium progress
+<schmancy-circular-progress></schmancy-circular-progress>
+
+// 2. Large indeterminate progress
+<schmancy-circular-progress 
+  size="lg"
+  indeterminate>
+</schmancy-circular-progress>
+
+// 3. Custom size
+<schmancy-circular-progress size="100">
+</schmancy-circular-progress>
+
+// 4. Small progress indicator
+<schmancy-circular-progress size="xs">
+</schmancy-circular-progress>
+```
+
+## Related Components
+- **[Busy](./busy.md)**: Parent component providing spinner functionality
+- **[Button](./button.md)**: Often used with buttons to show loading state
+
+## Technical Details
+
+### Implementation
+- Internally uses `<schmancy-spinner>` component
+- Size can be predefined string or custom CSS value
+- Numeric values are converted to pixels
+- Reflects indeterminate attribute to host element
+
+### CSS Custom Properties
+The component inherits spinner styling from the busy component.
+
+## Common Use Cases
+
+1. **Loading Buttons**: Show progress inside buttons
+   ```html
+   <schmancy-button disabled>
+     <schmancy-circular-progress size="sm"></schmancy-circular-progress>
+     Processing...
+   </schmancy-button>
+   ```
+
+2. **Page Loading**: Full-page loading indicator
+   ```html
+   <div class="loading-overlay">
+     <schmancy-circular-progress 
+       size="xl" 
+       indeterminate>
+     </schmancy-circular-progress>
+   </div>
+   ```
+
+3. **Inline Loading**: Small indicators in lists or tables
+   ```html
+   <td>
+     <schmancy-circular-progress size="xs"></schmancy-circular-progress>
+     Loading data...
+   </td>
+   ```
+
+4. **Card Loading State**: Centered in content areas
+   ```html
+   <schmancy-card>
+     <div class="centered">
+       <schmancy-circular-progress size="lg"></schmancy-circular-progress>
+       <p>Fetching results...</p>
+     </div>
+   </schmancy-card>
+   ```

package/ai/date-range.md

@@ -0,0 +1,142 @@
+# Date Range Component
+
+A sophisticated date range selector that supports both date and datetime selection with presets, manual input, and intelligent range navigation.
+
+## Quick Start
+
+```html
+<!-- Basic date range selector -->
+<schmancy-date-range 
+  .dateFrom="${{ label: 'Start', value: '2024-01-01' }}"
+  .dateTo="${{ label: 'End', value: '2024-12-31' }}"
+></schmancy-date-range>
+
+<!-- DateTime selector with custom presets -->
+<schmancy-date-range 
+  type="datetime-local"
+  .customPresets="${[
+    { label: 'Last Sprint', dateFrom: '2024-01-01', dateTo: '2024-01-14' }
+  ]}"
+></schmancy-date-range>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `type` | `'date' \| 'datetime-local'` | `'date'` | Date input type |
+| `dateFrom` | `{ label: string, value: string }` | `{ label: 'From', value: '' }` | Start date configuration |
+| `dateTo` | `{ label: string, value: string }` | `{ label: 'To', value: '' }` | End date configuration |
+| `minDate` | `string` | - | Minimum selectable date |
+| `maxDate` | `string` | - | Maximum selectable date |
+| `customPresets` | `Array<{ label, dateFrom, dateTo }>` | `[]` | Custom preset ranges |
+| `format` | `string` | - | Date format (defaults based on type) |
+| `disabled` | `boolean` | `false` | Disable the component |
+| `required` | `boolean` | `false` | Mark as required field |
+| `placeholder` | `string` | `'Select date range'` | Placeholder text |
+| `clearable` | `boolean` | `true` | Show clear button |
+
+## Events
+
+### change
+Fired when date range changes.
+
+```typescript
+interface DateRangeChangeEvent {
+  detail: {
+    dateFrom: string;
+    dateTo: string;
+  }
+}
+```
+
+## Examples
+
+### With Form Integration
+```html
+<schmancy-form>
+  <schmancy-date-range
+    name="project-timeline"
+    required
+    .dateFrom="${{ label: 'Project Start', value: '' }}"
+    .dateTo="${{ label: 'Project End', value: '' }}"
+    @change="${(e) => console.log('Timeline:', e.detail)}"
+  ></schmancy-date-range>
+</schmancy-form>
+```
+
+### Analytics Dashboard
+```html
+<!-- Date range for analytics with custom presets -->
+<schmancy-date-range
+  .customPresets="${[
+    { label: 'Holiday Season', dateFrom: '2023-11-24', dateTo: '2024-01-02' },
+    { label: 'Q4 2023', dateFrom: '2023-10-01', dateTo: '2023-12-31' }
+  ]}"
+  @change="${updateAnalytics}"
+></schmancy-date-range>
+```
+
+### DateTime Range for Events
+```html
+<schmancy-date-range
+  type="datetime-local"
+  .dateFrom="${{ label: 'Event Start', value: '2024-03-15T09:00' }}"
+  .dateTo="${{ label: 'Event End', value: '2024-03-15T17:00' }}"
+  minDate="2024-01-01T00:00"
+></schmancy-date-range>
+```
+
+## Features
+
+### Built-in Presets
+The component includes intelligent preset categories:
+- **Days**: Today, Yesterday, Last 7/30/90 Days
+- **Weeks**: This Week, Last Week
+- **Months**: This Month, Last Month
+- **Quarters**: This Quarter, Last Quarter
+- **Years**: This Year, Last Year, Year to Date
+- **Hours** (datetime-local): Last 12/24 Hours
+
+### Smart Navigation
+- Arrow buttons shift ranges intelligently based on duration
+- Maintains full period boundaries (weeks, months, quarters)
+- Automatically detects and preserves preset selections
+
+### Responsive Dropdown
+- Floating UI positioning with automatic adjustments
+- Categorized preset display
+- Manual date inputs with validation
+
+## Styling
+
+The component uses semantic color tokens and supports theming:
+
+```css
+schmancy-date-range {
+  --animation-duration: 200ms;
+  --dropdown-min-width: 16rem;
+  --dropdown-max-width: 24rem;
+}
+```
+
+## Accessibility
+
+- Full keyboard navigation support
+- ARIA labels and roles
+- Focus management
+- Screen reader announcements
+
+## Related Components
+
+- [Input](./input.md) - For single date inputs
+- [Form](./form.md) - Form integration
+- [Button](./button.md) - Used for triggers and actions
+- [Surface](./surface.md) - Dropdown container
+
+## Best Practices
+
+1. **Validation**: Always validate date ranges on the backend
+2. **Timezones**: Consider timezone handling for datetime-local inputs
+3. **Presets**: Add domain-specific presets for better UX
+4. **Loading States**: Show loading indicators when fetching data based on range changes