@mhmo91/schmancy 0.2.195 → 0.2.197

package/ai/option.md

@@ -0,0 +1,173 @@
+# Option Component
+
+A versatile option element designed for use with select dropdowns and autocomplete components, providing accessible and interactive selection items.
+
+## Quick Start
+
+```html
+<!-- Basic option -->
+<schmancy-option value="1">Option One</schmancy-option>
+
+<!-- Option with custom label -->
+<schmancy-option value="us" label="United States"></schmancy-option>
+
+<!-- Option with icon -->
+<schmancy-option value="email" icon="✉️">Email Notifications</schmancy-option>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `value` | `string` | `''` | The value when selected |
+| `label` | `string` | `''` | Display label (defaults to text content) |
+| `selected` | `boolean` | `false` | Whether option is selected |
+| `disabled` | `boolean` | `false` | Whether option is disabled |
+| `group` | `string` | `''` | Optional group name |
+| `icon` | `string` | `''` | Optional icon/emoji |
+
+## Events
+
+### option-select
+Fired when option is clicked or selected via keyboard.
+
+```typescript
+interface OptionSelectEvent {
+  detail: {
+    value: string;
+  }
+}
+```
+
+## Examples
+
+### In Select Component
+```html
+<schmancy-select placeholder="Choose country">
+  <schmancy-option value="us" icon="🇺🇸">United States</schmancy-option>
+  <schmancy-option value="uk" icon="🇬🇧">United Kingdom</schmancy-option>
+  <schmancy-option value="ca" icon="🇨🇦">Canada</schmancy-option>
+  <schmancy-option value="au" icon="🇦🇺">Australia</schmancy-option>
+</schmancy-select>
+```
+
+### Grouped Options
+```html
+<schmancy-select>
+  <!-- North America -->
+  <schmancy-option value="us" group="North America">United States</schmancy-option>
+  <schmancy-option value="ca" group="North America">Canada</schmancy-option>
+  <schmancy-option value="mx" group="North America">Mexico</schmancy-option>
+  
+  <!-- Europe -->
+  <schmancy-option value="uk" group="Europe">United Kingdom</schmancy-option>
+  <schmancy-option value="de" group="Europe">Germany</schmancy-option>
+  <schmancy-option value="fr" group="Europe">France</schmancy-option>
+</schmancy-select>
+```
+
+### With Status Indicators
+```html
+<schmancy-autocomplete>
+  <schmancy-option value="active" icon="🟢">Active</schmancy-option>
+  <schmancy-option value="pending" icon="🟡">Pending</schmancy-option>
+  <schmancy-option value="inactive" icon="🔴">Inactive</schmancy-option>
+  <schmancy-option value="archived" icon="📦" disabled>Archived</schmancy-option>
+</schmancy-autocomplete>
+```
+
+### Dynamic Options
+```html
+${users.map(user => html`
+  <schmancy-option 
+    value="${user.id}"
+    label="${user.name}"
+    ?disabled="${!user.active}"
+  >
+    <span class="flex items-center gap-2">
+      <schmancy-avatar size="xs" name="${user.name}"></schmancy-avatar>
+      <span>
+        <div>${user.name}</div>
+        <div class="text-xs opacity-70">${user.email}</div>
+      </span>
+    </span>
+  </schmancy-option>
+`)}
+```
+
+## Features
+
+### Automatic Value Assignment
+- If no value is provided, uses text content
+- If no label is provided, uses text content or value
+
+### Keyboard Navigation
+- `Space` or `Enter` to select
+- Full keyboard accessibility
+
+### Visual States
+- Hover highlighting
+- Selected state with checkmark
+- Disabled state with reduced opacity
+- Focus ring for keyboard navigation
+
+### Unique IDs
+Automatically generates unique IDs for accessibility if not provided.
+
+## Styling
+
+The component uses semantic design tokens:
+
+```css
+/* Default state */
+.hover:bg-surface-high
+
+/* Selected state */
+.bg-primary-container
+.text-primary-onContainer
+
+/* Custom styling */
+schmancy-option {
+  --option-padding-y: 0.5rem;
+  --option-padding-x: 0.75rem;
+  --option-border-radius: 0.25rem;
+}
+```
+
+## Accessibility
+
+- `role="option"` for semantic meaning
+- `aria-selected` state management
+- `aria-disabled` for disabled options
+- Keyboard event handling
+- Focus management
+
+## Integration
+
+Options are designed to work seamlessly with:
+- `schmancy-select` - Dropdown selection
+- `schmancy-autocomplete` - Filtered selection
+- Custom dropdown components
+
+## Best Practices
+
+1. **Clear Values**: Use meaningful, unique values
+2. **Icons**: Use icons to improve scannability
+3. **Groups**: Group related options together
+4. **Labels**: Provide clear, concise labels
+5. **Disabled State**: Clearly indicate why options are disabled
+
+## Related Components
+
+- [Select](./select.md) - Dropdown selector
+- [Autocomplete](./autocomplete.md) - Searchable selector
+- [List](./list.md) - Similar list item pattern
+- [Menu](./menu.md) - Menu items
+
+## Use Cases
+
+1. **Form Selects**: Country, state, category selection
+2. **Settings**: Preference options
+3. **Filters**: Data filtering options
+4. **Status Selection**: Workflow states
+5. **User Selection**: Team member pickers

package/ai/slider.md

@@ -0,0 +1,227 @@
+# Slider Component
+
+A smooth, touch-friendly carousel component for displaying content in slides with navigation controls and indicators.
+
+## Quick Start
+
+```html
+<!-- Basic image slider -->
+<schmancy-slider>
+  <schmancy-slide type="image" src="/image1.jpg" alt="Slide 1"></schmancy-slide>
+  <schmancy-slide type="image" src="/image2.jpg" alt="Slide 2"></schmancy-slide>
+  <schmancy-slide type="image" src="/image3.jpg" alt="Slide 3"></schmancy-slide>
+</schmancy-slider>
+
+<!-- Content slider -->
+<schmancy-slider showArrows>
+  <schmancy-slide>
+    <schmancy-card>
+      <h3>Feature One</h3>
+      <p>Description of the first feature...</p>
+    </schmancy-card>
+  </schmancy-slide>
+  <schmancy-slide>
+    <schmancy-card>
+      <h3>Feature Two</h3>
+      <p>Description of the second feature...</p>
+    </schmancy-card>
+  </schmancy-slide>
+</schmancy-slider>
+```
+
+## Components
+
+### schmancy-slider
+The main container that handles slide navigation and controls.
+
+**Properties:**
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `showArrows` | `boolean` | `true` | Show navigation arrows |
+
+**Events:**
+- `slide-changed`: Fired when active slide changes with `{ detail: { index: number } }`
+
+### schmancy-slide
+Individual slide component supporting various content types.
+
+**Properties:**
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `type` | `'image' \| 'video' \| 'content'` | `'content'` | Slide content type |
+| `src` | `string` | `''` | Source for image/video |
+| `alt` | `string` | `''` | Alt text for images |
+| `controls` | `boolean` | `true` | Show video controls |
+| `autoplay` | `boolean` | `false` | Autoplay video |
+| `loop` | `boolean` | `false` | Loop video |
+| `muted` | `boolean` | `false` | Mute video |
+| `fit` | `'cover' \| 'contain' \| 'fill' \| 'scale-down' \| 'none'` | `'cover'` | Object fit style |
+
+## Examples
+
+### Product Gallery
+```html
+<schmancy-slider class="h-96">
+  ${products.map(product => html`
+    <schmancy-slide type="image" 
+      src="${product.image}" 
+      alt="${product.name}"
+      fit="contain"
+    ></schmancy-slide>
+  `)}
+</schmancy-slider>
+```
+
+### Testimonials Carousel
+```html
+<schmancy-slider showArrows>
+  ${testimonials.map(testimonial => html`
+    <schmancy-slide>
+      <div class="p-8 text-center">
+        <schmancy-avatar 
+          src="${testimonial.avatar}" 
+          name="${testimonial.name}"
+          size="lg"
+          class="mx-auto mb-4"
+        ></schmancy-avatar>
+        <blockquote class="text-lg italic mb-4">
+          "${testimonial.quote}"
+        </blockquote>
+        <cite class="text-sm">
+          - ${testimonial.name}, ${testimonial.role}
+        </cite>
+      </div>
+    </schmancy-slide>
+  `)}
+</schmancy-slider>
+```
+
+### Video Showcase
+```html
+<schmancy-slider>
+  <schmancy-slide 
+    type="video" 
+    src="/demo-video-1.mp4"
+    controls
+    muted
+    autoplay
+  ></schmancy-slide>
+  <schmancy-slide 
+    type="video" 
+    src="/demo-video-2.mp4"
+    controls
+  ></schmancy-slide>
+</schmancy-slider>
+```
+
+### Mixed Content Slider
+```html
+<schmancy-slider>
+  <!-- Welcome slide -->
+  <schmancy-slide>
+    <div class="flex items-center justify-center h-full p-8">
+      <div class="text-center">
+        <h1 class="text-4xl mb-4">Welcome</h1>
+        <p>Swipe to explore our features</p>
+      </div>
+    </div>
+  </schmancy-slide>
+  
+  <!-- Feature image -->
+  <schmancy-slide type="image" src="/feature.jpg" alt="Main Feature"></schmancy-slide>
+  
+  <!-- Video demo -->
+  <schmancy-slide type="video" src="/demo.mp4" controls></schmancy-slide>
+  
+  <!-- Call to action -->
+  <schmancy-slide>
+    <div class="flex items-center justify-center h-full">
+      <schmancy-button variant="filled" size="lg">
+        Get Started
+      </schmancy-button>
+    </div>
+  </schmancy-slide>
+</schmancy-slider>
+```
+
+## Features
+
+### Smooth Scrolling
+- Native scroll behavior with CSS scroll-snap
+- Touch and mouse support
+- Keyboard navigation ready
+
+### Navigation Controls
+- Previous/Next arrow buttons
+- Automatic disable at bounds
+- Dot indicators showing current position
+
+### Responsive Design
+- Slides automatically fill container width
+- Hidden scrollbars for clean appearance
+- Works on all device sizes
+
+### Performance
+- Lazy loading for images
+- Throttled scroll events
+- Efficient slide position detection
+
+## Styling
+
+```css
+/* Container styling */
+schmancy-slider {
+  height: 400px; /* Set explicit height */
+}
+
+/* Custom arrow positioning */
+schmancy-slider::part(prev-button) {
+  left: 1rem;
+}
+
+schmancy-slider::part(next-button) {
+  right: 1rem;
+}
+
+/* Indicator customization */
+schmancy-slider::part(indicators) {
+  bottom: 2rem;
+}
+```
+
+## Navigation Methods
+
+```javascript
+// Get slider element
+const slider = document.querySelector('schmancy-slider');
+
+// Listen for slide changes
+slider.addEventListener('slide-changed', (e) => {
+  console.log('Current slide:', e.detail.index);
+});
+
+// Programmatically navigate (if exposed)
+// slider.goToSlide(2);
+```
+
+## Best Practices
+
+1. **Height**: Always set explicit height on slider container
+2. **Images**: Optimize images for web delivery
+3. **Accessibility**: Provide meaningful alt text
+4. **Performance**: Limit number of slides for better performance
+5. **Touch**: Ensure adequate touch targets on mobile
+
+## Related Components
+
+- [Card](./card.md) - Content containers for slides
+- [Button](./button.md) - Navigation controls
+- [Surface](./surface.md) - Slide backgrounds
+
+## Use Cases
+
+1. **Product Galleries**: E-commerce product images
+2. **Hero Sections**: Landing page carousels
+3. **Testimonials**: Customer feedback showcase
+4. **Tutorials**: Step-by-step guides
+5. **Media Galleries**: Photo and video collections

package/ai/steps.md

@@ -0,0 +1,231 @@
+# Steps Component
+
+A powerful stepper component for guiding users through multi-step processes with progress tracking, navigation control, and flexible content management.
+
+## Quick Start
+
+```html
+<!-- Basic steps -->
+<schmancy-steps-container currentStep="1">
+  <schmancy-step position="1" title="Account Setup">
+    <schmancy-input label="Email" type="email"></schmancy-input>
+    <schmancy-input label="Password" type="password"></schmancy-input>
+  </schmancy-step>
+  
+  <schmancy-step position="2" title="Profile Details">
+    <schmancy-input label="Full Name"></schmancy-input>
+    <schmancy-input label="Phone"></schmancy-input>
+  </schmancy-step>
+  
+  <schmancy-step position="3" title="Review">
+    <p>Review your information and submit</p>
+    <schmancy-button variant="filled">Complete</schmancy-button>
+  </schmancy-step>
+</schmancy-steps-container>
+```
+
+## Components
+
+### schmancy-steps-container
+The parent container managing step state and navigation.
+
+**Properties:**
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `currentStep` | `number` | `1` | Currently active step (1-based) |
+
+### schmancy-step
+Individual step component with content and metadata.
+
+**Properties:**
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `position` | `number` | `1` | Step position (1-based) |
+| `title` | `string` | `''` | Step title |
+| `description` | `string` | `''` | Optional step description |
+| `completed` | `boolean` | `false` | Explicitly mark as complete |
+| `lockBack` | `boolean` | `false` | Prevent navigation to previous steps |
+
+## Examples
+
+### Checkout Process
+```html
+<schmancy-steps-container currentStep="2">
+  <schmancy-step position="1" title="Cart" description="Review your items">
+    <schmancy-list>
+      ${cartItems.map(item => html`
+        <schmancy-list-item>
+          ${item.name} - $${item.price}
+        </schmancy-list-item>
+      `)}
+    </schmancy-list>
+  </schmancy-step>
+  
+  <schmancy-step position="2" title="Shipping" description="Enter delivery address">
+    <schmancy-form>
+      <schmancy-input label="Street Address"></schmancy-input>
+      <schmancy-input label="City"></schmancy-input>
+      <schmancy-select label="State">
+        <!-- State options -->
+      </schmancy-select>
+      <schmancy-input label="ZIP Code"></schmancy-input>
+    </schmancy-form>
+  </schmancy-step>
+  
+  <schmancy-step position="3" title="Payment" description="Payment information">
+    <schmancy-payment-card-form></schmancy-payment-card-form>
+  </schmancy-step>
+  
+  <schmancy-step position="4" title="Confirm" description="Review and place order">
+    <div class="summary">
+      <!-- Order summary -->
+    </div>
+    <schmancy-button variant="filled" @click="${placeOrder}">
+      Place Order
+    </schmancy-button>
+  </schmancy-step>
+</schmancy-steps-container>
+```
+
+### Onboarding Flow
+```html
+<schmancy-steps-container>
+  <schmancy-step position="1" title="Welcome" completed>
+    <div class="text-center p-8">
+      <h2>Welcome to Our Platform!</h2>
+      <p>Let's get you set up in just a few steps.</p>
+      <schmancy-button @click="${nextStep}">Get Started</schmancy-button>
+    </div>
+  </schmancy-step>
+  
+  <schmancy-step position="2" title="Connect Accounts" lockBack>
+    <p>Connect your social accounts for better integration:</p>
+    <div class="space-y-2">
+      <schmancy-button variant="outlined" width="full">
+        <schmancy-icon slot="start">facebook</schmancy-icon>
+        Connect Facebook
+      </schmancy-button>
+      <schmancy-button variant="outlined" width="full">
+        <schmancy-icon slot="start">twitter</schmancy-icon>
+        Connect Twitter
+      </schmancy-button>
+    </div>
+  </schmancy-step>
+  
+  <schmancy-step position="3" title="Preferences">
+    <h3>Customize your experience:</h3>
+    <schmancy-checkbox label="Email notifications"></schmancy-checkbox>
+    <schmancy-checkbox label="Weekly digest"></schmancy-checkbox>
+    <schmancy-checkbox label="Product updates"></schmancy-checkbox>
+  </schmancy-step>
+</schmancy-steps-container>
+```
+
+### Form Wizard
+```html
+<schmancy-steps-container currentStep="1">
+  <schmancy-step position="1" title="Basic Info">
+    <schmancy-form>
+      <schmancy-input label="Company Name" required></schmancy-input>
+      <schmancy-select label="Industry" required>
+        <schmancy-option value="tech">Technology</schmancy-option>
+        <schmancy-option value="finance">Finance</schmancy-option>
+        <schmancy-option value="healthcare">Healthcare</schmancy-option>
+      </schmancy-select>
+      <schmancy-textarea label="Description"></schmancy-textarea>
+    </schmancy-form>
+  </schmancy-step>
+  
+  <schmancy-step position="2" title="Contact Details">
+    <schmancy-form>
+      <schmancy-input label="Contact Name"></schmancy-input>
+      <schmancy-input label="Email" type="email"></schmancy-input>
+      <schmancy-input label="Phone" type="tel"></schmancy-input>
+    </schmancy-form>
+  </schmancy-step>
+  
+  <schmancy-step position="3" title="Additional Info">
+    <schmancy-form>
+      <schmancy-date-range
+        .dateFrom="${{ label: 'Founded', value: '' }}"
+        .dateTo="${{ label: 'Current', value: '' }}"
+      ></schmancy-date-range>
+      <schmancy-input label="Number of Employees" type="number"></schmancy-input>
+    </schmancy-form>
+  </schmancy-step>
+</schmancy-steps-container>
+```
+
+## Features
+
+### Visual States
+- **Complete**: Checkmark icon, can navigate back
+- **Current**: Active indicator, expanded content
+- **Upcoming**: Grayed out, not clickable
+
+### Navigation Control
+- Click completed steps to go back
+- `lockBack` prevents backward navigation
+- Automatic step expansion/collapse
+
+### Flexible Layout
+- Steps grow to show content when active
+- Smooth transitions between steps
+- Responsive design
+
+### Context System
+Uses Lit Context API for state management between container and steps.
+
+## Styling
+
+```css
+/* Custom step styling */
+schmancy-step {
+  --step-connector-color: var(--schmancy-sys-color-tertiary-default);
+  --step-inactive-color: #9CA3AF;
+  --step-icon-size: 1.25rem;
+}
+
+/* Active step content spacing */
+schmancy-step[position="2"] {
+  --step-content-padding: 2rem;
+}
+```
+
+## Programmatic Control
+
+```javascript
+// Get container reference
+const stepsContainer = document.querySelector('schmancy-steps-container');
+
+// Change current step
+stepsContainer.currentStep = 3;
+
+// Listen for step changes
+stepsContainer.addEventListener('step-change', (e) => {
+  console.log('Step changed to:', e.detail.step);
+});
+```
+
+## Best Practices
+
+1. **Clear Titles**: Use descriptive, action-oriented titles
+2. **Progress Saving**: Save user progress between sessions
+3. **Validation**: Validate before allowing step progression
+4. **Mobile**: Ensure steps work well on small screens
+5. **Accessibility**: Provide clear navigation cues
+
+## Related Components
+
+- [Form](./form.md) - Form integration
+- [Button](./button.md) - Navigation controls
+- [List](./list.md) - Step content lists
+- [Typography](./typography.md) - Step labels
+
+## Use Cases
+
+1. **Checkout Flows**: E-commerce purchase process
+2. **Onboarding**: New user setup
+3. **Form Wizards**: Complex multi-page forms
+4. **Tutorials**: Step-by-step guides
+5. **Configuration**: Multi-step setup processes