@mhmo91/schmancy 0.4.8 → 0.4.10

package/ai/directives.md

@@ -0,0 +1,237 @@
+# Schmancy Directives - AI Reference
+
+## Quick Start
+
+```typescript
+import { ripple, color, height, visibility } from '@mhmo91/schmancy/directives'
+```
+
+## Directives Overview
+
+Lit directives that add common UI behaviors and styling capabilities to any element.
+
+## API
+
+### Ripple Directive
+
+```typescript
+// Add Material Design ripple effect to any element
+<div ${ripple()}></div>
+
+// Ripple automatically triggers on click
+// Uses theme color: var(--schmancy-sys-color-surface-high)
+```
+
+### Color Directive
+
+```typescript
+// Apply dynamic colors to elements
+<div ${color({ 
+  bgColor?: string,  // Background color
+  color?: string     // Text color
+})}></div>
+
+// Examples
+<div ${color({ bgColor: '#ff0000' })}></div>
+<div ${color({ color: 'blue' })}></div>
+<div ${color({ bgColor: 'var(--schmancy-sys-color-primary)', color: 'white' })}></div>
+```
+
+### Height Directive
+
+```typescript
+// Dynamically set element height
+<div ${height(value: string | number)}></div>
+
+// Examples
+<div ${height(200)}></div>           // 200px
+<div ${height('50vh')}></div>        // 50% viewport height
+<div ${height('calc(100% - 64px)')}></div>  // Calculated height
+```
+
+### Visibility Directive
+
+```typescript
+// Control element visibility
+<div ${visibility(isVisible: boolean)}></div>
+
+// When false, sets display: none
+// When true, removes display style
+```
+
+## Examples
+
+### Basic Usage
+
+```typescript
+// Button with ripple effect
+<button ${ripple()} class="px-4 py-2 rounded">
+  Click Me
+</button>
+
+// Colored container
+<div ${color({ bgColor: 'var(--schmancy-sys-color-primary-container)' })} class="p-4">
+  Primary Container
+</div>
+
+// Conditional visibility
+<div ${visibility(showContent)} class="alert">
+  This content is conditionally visible
+</div>
+
+// Dynamic height
+<div ${height(collapsed ? 0 : 'auto')} class="transition-all">
+  Collapsible content
+</div>
+```
+
+### Combined Directives
+
+```typescript
+// Interactive card with multiple directives
+<div 
+  ${ripple()}
+  ${color({ bgColor: 'var(--schmancy-sys-color-surface-container)' })}
+  ${visibility(isActive)}
+  class="p-4 rounded-lg cursor-pointer"
+  @click=${handleClick}>
+  Interactive Card
+</div>
+
+// Animated drawer
+<div 
+  ${height(isOpen ? '300px' : '0')}
+  ${visibility(isOpen)}
+  class="transition-all duration-300 overflow-hidden">
+  Drawer Content
+</div>
+```
+
+### Real-World Examples
+
+```typescript
+// Custom button component
+render() {
+  return html`
+    <button
+      ${ripple()}
+      ${color({ 
+        bgColor: this.variant === 'primary' 
+          ? 'var(--schmancy-sys-color-primary)' 
+          : 'var(--schmancy-sys-color-surface-container)'
+      })}
+      class="px-4 py-2 rounded-full relative overflow-hidden"
+      ?disabled=${this.disabled}>
+      <slot></slot>
+    </button>
+  `
+}
+
+// Expandable panel
+render() {
+  return html`
+    <div class="border rounded-lg overflow-hidden">
+      <div 
+        ${ripple()}
+        class="p-4 cursor-pointer relative"
+        @click=${() => this.expanded = !this.expanded}>
+        <schmancy-typography type="title" token="md">
+          Panel Header
+        </schmancy-typography>
+      </div>
+      <div 
+        ${height(this.expanded ? 'auto' : '0')}
+        class="transition-all duration-300">
+        <div class="p-4">
+          Panel content goes here...
+        </div>
+      </div>
+    </div>
+  `
+}
+
+// Theme-aware container
+render() {
+  const isDark = this.theme === 'dark'
+  return html`
+    <div 
+      ${color({
+        bgColor: isDark 
+          ? 'var(--schmancy-sys-color-surface-dim)' 
+          : 'var(--schmancy-sys-color-surface-bright)',
+        color: 'var(--schmancy-sys-color-on-surface)'
+      })}
+      class="p-6 rounded-lg">
+      <slot></slot>
+    </div>
+  `
+}
+```
+
+## Implementation Details
+
+### Ripple Directive
+- Creates span element with ripple animation
+- Calculates position relative to click coordinates
+- Auto-removes previous ripple before adding new one
+- Uses CSS keyframe animation (600ms duration)
+- Scales from 0 to 4x size while fading out
+
+### Color Directive
+- Directly sets style.backgroundColor and style.color
+- Accepts any valid CSS color value
+- Supports CSS variables
+- Updates immediately on value change
+
+### Height Directive
+- Sets style.height property
+- Accepts numbers (converted to px) or strings
+- Useful for animations and transitions
+- Works with calc() expressions
+
+### Visibility Directive
+- Controls display property
+- When false: display = 'none'
+- When true: removes display style
+- Preserves other display values
+
+## Best Practices
+
+1. **Ripple Usage**: Best on interactive elements (buttons, cards, list items)
+2. **Color Variables**: Prefer theme CSS variables over hardcoded colors
+3. **Height Animations**: Combine with CSS transitions for smooth effects
+4. **Visibility**: Use for simple show/hide; consider v-show for more control
+5. **Performance**: Directives are lightweight but avoid excessive updates
+
+## Common Pitfalls
+
+- **Ripple Overflow**: Parent element needs `position: relative` and `overflow: hidden`
+- **Color Specificity**: Inline styles from color directive override CSS classes
+- **Height Auto**: Transitioning to/from 'auto' requires special handling
+- **Visibility vs Display**: Visibility directive uses display, not visibility property
+
+## Related Components
+
+- **[Button](./button.md)**: Could use ripple directive
+- **[Card](./card.md)**: Interactive cards benefit from ripple
+- **[Surface](./surface.md)**: Color directive for dynamic theming
+- **[Theme](./theme.md)**: Use theme variables with color directive
+
+## TypeScript Types
+
+```typescript
+// Ripple directive
+ripple(): DirectiveResult
+
+// Color directive
+color(config: {
+  bgColor?: string;
+  color?: string;
+}): DirectiveResult
+
+// Height directive  
+height(value: string | number): DirectiveResult
+
+// Visibility directive
+visibility(isVisible: boolean): DirectiveResult
+```

package/ai/input.md

@@ -3,55 +3,54 @@
 ```js
 // Text Input
 <schmancy-input
-  name="field-name"
-  label="Field Label"
-  value="initial value"
-  type="text|password|email|number|tel|url|search|date"
-  placeholder="Placeholder text"
-  required?
-  disabled?
-  readonly?
-  error="Error message"
-  success?
-  size="small|medium|large"
-  @input=${handleInput}
-  @change=${handleChange}
-  @focus=${handleFocus}
-  @blur=${handleBlur}>
+  id?="custom-id"                                      // Auto-generated if not provided
+  name="field-name"                                   // Form field name
+  label="Field Label"                                 // Label text
+  value="initial value"                               // Input value
+  type="text|password|email|number|tel|url|search|date|time|datetime-local" // Input type
+  placeholder="Placeholder text"                      // Placeholder text
+  hint?="Helper text"                                 // Helper text below input
+  align?="left|center|right"                          // Text alignment (default: "left")
+  required?                                            // Required field
+  disabled?                                            // Disabled state
+  readonly?                                            // Read-only state
+  clickable?                                           // Show pointer cursor when readonly
+  error?                                               // Error state (boolean)
+  autofocus?                                           // Auto-focus on render
+  spellcheck?                                          // Enable spellcheck
+  inputmode?="none|text|tel|url|email|numeric|decimal|search" // Virtual keyboard hint
+  autocomplete?="off|on|name|email|tel|etc"          // Autofill hints
+  pattern?="regex"                                    // Validation pattern
+  minlength?="number"                                 // Min character length
+  maxlength?="number"                                 // Max character length
+  min?="number|date"                                  // Min value (number/date)
+  max?="number|date"                                  // Max value (number/date)
+  step?="number|any"                                  // Step increment
+  tabIndex?="number"                                  // Tab order
+  @input=${handleInput}                                // Every keystroke
+  @change=${handleChange}                              // On blur/change
+  @enter=${handleEnter}                                // Enter key pressed
+  @focus=${handleFocus}                                // Focus event
+  @blur=${handleBlur}>                                 // Blur event
 </schmancy-input>
 
-// Input v2 (enhanced version with formatting and validation)
-<schmancy-input-v2
-  name="field-name"
-  label="Field Label"
-  value="initial value"
-  type="text|password|email|number|tel|url|search|date"
-  placeholder="Placeholder text"
-  required?
-  disabled?
-  readonly?
-  error="Error message"
-  success?
-  size="small|medium|large"
-  .format=${(value) => formattedValue}
-  .parse=${(displayValue) => parsedValue}
-  .validate=${(value) => errorMessage}
-  @input=${handleInput}
-  @change=${handleChange}>
-</schmancy-input-v2>
-
 // Input Methods
-input.focus() -> void
+input.focus(options?: FocusOptions) -> void
 input.blur() -> void
-input.validate() -> boolean
-input.setCustomValidity(message) -> void
+input.click() -> void
 input.select() -> void
-
-// Events
-@input // { target: { value: string } }
-@change // { target: { value: string } }
-@focus // { target: HTMLElement }
-@blur // { target: HTMLElement }
+input.checkValidity() -> boolean
+input.reportValidity() -> boolean
+input.setCustomValidity(message: string) -> void
+input.getValidity() -> ValidityState
+
+// Events (Custom Events with detail)
+@input  // CustomEvent<{ value: string }>
+@change // CustomEvent<{ value: string }>
+@enter  // CustomEvent<{ value: string }>
+@focus  // Standard FocusEvent
+@blur   // Standard FocusEvent
+@click  // Standard MouseEvent
 
 // Examples
 // 1. Basic input with validation
@@ -74,16 +73,44 @@ input.select() -> void
   .validate=${(value) => value < 0 ? 'Amount must be positive' : ''}>
 </schmancy-input-v2>
 
-// 3. Input with prefix/suffix
-<schmancy-input label="Price">
-  <span slot="prefix">$</span>
-  <span slot="suffix">.00</span>
+// 3. Password input with visibility toggle
+<schmancy-input 
+  type="password"
+  label="Password"
+  name="password"
+  required
+  minlength="8"
+  @enter=${handleSubmit}>
 </schmancy-input>
 
-// 4. Input with icons
-<schmancy-input label="Search">
-  <schmancy-icon slot="prefix" icon="search"></schmancy-icon>
-  <schmancy-icon slot="suffix" icon="close" @click=${clearInput}></schmancy-icon>
+// 4. Number input with constraints
+<schmancy-input
+  type="number"
+  label="Quantity"
+  name="quantity"
+  min="1"
+  max="100"
+  step="1"
+  value="1">
+</schmancy-input>
+
+// 5. Input with error state and hint
+<schmancy-input
+  label="Username"
+  name="username"
+  ?error=${hasError}
+  hint=${hasError ? "Username already taken" : "Choose a unique username"}
+  pattern="^[a-zA-Z0-9_]+$">
+</schmancy-input>
+
+// 6. Centered readonly input that's clickable
+<schmancy-input
+  label="Invitation Code"
+  value="ABC123XYZ"
+  readonly
+  clickable
+  align="center"
+  @click=${copyToClipboard}>
 </schmancy-input>
 ```
 
@@ -95,9 +122,26 @@ input.select() -> void
 
 ## Technical Details
 
-### Slots
-```html
-prefix: Content displayed before the input field
+### Form Association
+The component is form-associated using ElementInternals API, which means:
+- It participates in form submission
+- Works with form validation
+- Integrates with FormData
+- Supports constraint validation API
+
+### Accessibility Features
+- Auto-generated IDs for label association
+- ARIA attributes (aria-label, aria-required, aria-invalid, etc.)
+- Proper form association
+- Keyboard navigation support
+
+### Validation
+```typescript
+// Built-in HTML5 validation
+input.checkValidity()     // Returns true/false
+input.reportValidity()    // Shows validation message
+input.setCustomValidity('Custom error')  // Set custom message
+input.getValidity()       // Get ValidityState object
 suffix: Content displayed after the input field
 ```
 

package/ai/payment-card-form.md

@@ -0,0 +1,241 @@
+# Schmancy Payment Card Form - AI Reference
+
+## Quick Start
+
+```typescript
+import '@mhmo91/schmancy/components/form-elements'
+```
+
+## Component Overview
+
+A mobile-friendly payment card form component with real-time validation and formatting for credit card information. Uses Cleave.js for intelligent input formatting.
+
+## API
+
+```typescript
+// Payment Card Form Component
+<schmancy-payment-card-form
+  value?="{
+    cardName: string,
+    cardNumber: string,
+    expirationDate: string,
+    cvv: string
+  }"
+  @change=${handleChange}>
+  <!-- Optional additional content -->
+</schmancy-payment-card-form>
+
+// Component Properties
+value: {
+  cardName: string        // Cardholder name
+  cardNumber: string      // Card number (formatted)
+  expirationDate: string  // MM/YY format
+  cvv: string            // 3-4 digits
+}
+
+// Events
+@change  // Fires when any field changes with complete form data
+
+// Methods
+form.checkValidity() -> boolean  // Check if all fields are valid
+form.submit() -> void           // Submit the form
+```
+
+## Examples
+
+### Basic Usage
+
+```typescript
+// Simple payment form
+<schmancy-payment-card-form 
+  @change=${(e) => console.log('Form data:', e.detail)}>
+</schmancy-payment-card-form>
+
+// With initial values
+<schmancy-payment-card-form 
+  .value=${{
+    cardName: 'John Doe',
+    cardNumber: '',
+    expirationDate: '',
+    cvv: ''
+  }}
+  @change=${handlePaymentChange}>
+</schmancy-payment-card-form>
+```
+
+### Form Integration
+
+```typescript
+// Inside a larger form
+<schmancy-form @submit=${handleCheckout}>
+  <schmancy-typography type="headline" token="sm" class="mb-4 block">
+    Payment Information
+  </schmancy-typography>
+  
+  <schmancy-payment-card-form 
+    @change=${(e) => this.paymentData = e.detail}>
+  </schmancy-payment-card-form>
+  
+  <schmancy-button type="submit" variant="filled" class="mt-4">
+    Complete Purchase
+  </schmancy-button>
+</schmancy-form>
+
+// Handling submission
+handleCheckout(e) {
+  const formData = e.detail;
+  const payment = this.paymentData;
+  
+  // Process payment...
+}
+```
+
+### Real-World Examples
+
+```typescript
+// E-commerce checkout
+render() {
+  return html`
+    <schmancy-surface class="p-6 rounded-lg">
+      <schmancy-payment-card-form 
+        .value=${this.paymentInfo}
+        @change=${this.handlePaymentUpdate}>
+        
+        <!-- Additional fields can be added via slot -->
+        <schmancy-input
+          label="Billing ZIP Code"
+          name="zipCode"
+          required
+          pattern="[0-9]{5}"
+          class="mt-4">
+        </schmancy-input>
+      </schmancy-payment-card-form>
+      
+      <div class="flex gap-4 mt-6">
+        <schmancy-button variant="text" @click=${this.goBack}>
+          Back
+        </schmancy-button>
+        <schmancy-button 
+          variant="filled" 
+          @click=${this.processPayment}
+          ?disabled=${!this.isValid}>
+          Pay $${this.total}
+        </schmancy-button>
+      </div>
+    </schmancy-surface>
+  `
+}
+
+// With validation feedback
+class CheckoutForm extends LitElement {
+  @state() errors = {};
+  
+  async processPayment() {
+    const form = this.shadowRoot.querySelector('schmancy-payment-card-form');
+    
+    if (!form.checkValidity()) {
+      this.errors = {
+        payment: 'Please complete all payment fields correctly'
+      };
+      return;
+    }
+    
+    // Process payment...
+  }
+}
+```
+
+## Features
+
+### Automatic Formatting
+- **Card Number**: Spaces added automatically (e.g., "4242 4242 4242 4242")
+- **Expiration Date**: MM/YY format enforced
+- **CVV**: Length adjusted based on card type (3 for most, 4 for Amex)
+
+### Card Type Detection
+- Automatically detects card type from number
+- Supports: Visa, Mastercard, Amex, Discover, JCB, Diners, etc.
+- Shows appropriate card icon
+- Adjusts validation rules per card type
+
+### Real-time Validation
+- Card number validity (Luhn algorithm)
+- Expiration date must be future date
+- CVV length based on card type
+- Name field required
+
+### Mobile Optimized
+- Appropriate input modes for virtual keyboards
+- Large touch targets
+- Clear error states
+- Smooth animations
+
+## Validation Rules
+
+1. **Card Name**: Required, min 2 characters
+2. **Card Number**: 
+   - Valid card number format
+   - Passes Luhn check
+   - Supported card type
+3. **Expiration Date**:
+   - MM/YY format
+   - Must be current or future month
+4. **CVV**:
+   - 3 digits (most cards)
+   - 4 digits (American Express)
+
+## Accessibility
+
+- Proper label associations
+- ARIA attributes for validation states
+- Keyboard navigation support
+- Screen reader announcements for errors
+- High contrast error states
+
+## Best Practices
+
+1. **Security**: Never store raw card data - tokenize on backend
+2. **PCI Compliance**: Use HTTPS and follow PCI-DSS guidelines
+3. **Error Handling**: Show clear, specific error messages
+4. **Loading States**: Disable form during payment processing
+5. **Confirmation**: Show summary before final submission
+
+## Common Pitfalls
+
+- **Test Cards**: Component validates real card numbers only
+- **Date Validation**: MM/YY not MM/YYYY
+- **Auto-submit**: Don't auto-submit on completion
+- **Browser Autofill**: May conflict with Cleave.js formatting
+
+## Related Components
+
+- **[Form](./form.md)**: Parent form container
+- **[Input](./input.md)**: Base input component used internally
+- **[Button](./button.md)**: Submit buttons
+- **[Surface](./surface.md)**: Card containers
+
+## Dependencies
+
+- **Cleave.js**: Handles input formatting and validation
+- Automatically included with component
+
+## TypeScript Interface
+
+```typescript
+interface PaymentCardData {
+  cardName: string;
+  cardNumber: string;
+  expirationDate: string;
+  cvv: string;
+}
+
+interface SchmancyPaymentCardFormElement extends HTMLElement {
+  value: PaymentCardData;
+  checkValidity(): boolean;
+}
+
+// Change event
+interface PaymentCardChangeEvent extends CustomEvent {
+  detail: PaymentCardData;
+}
+```

package/ai/surface.md

@@ -13,7 +13,7 @@
 // Properties
 fill: string          // "all", "width", "height", "auto" (default: "auto")
 rounded: string       // Corner rounding: "none", "top", "left", "right", "bottom", "all" (default: "none")
-type: string          // Surface color variant (default: "surface")
+type: string          // Surface color variant (default: "container")
 elevation: number     // Shadow depth 0-5 (default: 0)
 
 // Surface Types (background colors)