@mhmo91/schmancy 0.2.193 → 0.2.195

package/ai/dropdown.md

@@ -0,0 +1,238 @@
+# Schmancy Dropdown - AI Reference
+
+```js
+// Basic Dropdown
+<schmancy-dropdown>
+  <schmancy-button slot="trigger">
+    Open Dropdown
+  </schmancy-button>
+  
+  <div slot="content">
+    <div>Dropdown content goes here</div>
+  </div>
+</schmancy-dropdown>
+
+// Dropdown with position
+<schmancy-dropdown
+  position="bottom-start|bottom-end|top-start|top-end|left-start|left-end|right-start|right-end">
+  <schmancy-button slot="trigger">
+    Open Dropdown
+  </schmancy-button>
+  
+  <div slot="content">
+    <div>Positioned dropdown content</div>
+  </div>
+</schmancy-dropdown>
+
+// Dropdown with menu items
+<schmancy-dropdown>
+  <schmancy-button slot="trigger">
+    Options
+  </schmancy-button>
+  
+  <schmancy-menu slot="content">
+    <schmancy-menu-item @click=${handleEdit}>Edit</schmancy-menu-item>
+    <schmancy-menu-item @click=${handleDuplicate}>Duplicate</schmancy-menu-item>
+    <schmancy-menu-item @click=${handleArchive}>Archive</schmancy-menu-item>
+    <schmancy-menu-item disabled>Share</schmancy-menu-item>
+    <schmancy-divider></schmancy-divider>
+    <schmancy-menu-item variant="danger" @click=${handleDelete}>Delete</schmancy-menu-item>
+  </schmancy-menu>
+</schmancy-dropdown>
+
+// Dropdown with custom width and offset
+<schmancy-dropdown
+  width="300px"
+  offset="5">
+  <schmancy-button slot="trigger">
+    Wide Dropdown
+  </schmancy-button>
+  
+  <div slot="content" style="padding: 16px;">
+    <h3>Custom Content</h3>
+    <p>This dropdown has custom width and offset.</p>
+  </div>
+</schmancy-dropdown>
+
+// Dropdown Properties
+position: string        // Position relative to trigger: "bottom-start" (default), "top-end", etc.
+width: string           // Width of the dropdown content
+offset: number          // Distance between trigger and content (pixels)
+open: boolean           // Whether the dropdown is open
+disabled: boolean       // Disable the dropdown
+closeOnSelect: boolean  // Close dropdown when an item inside is selected
+closeOnClickOutside: boolean // Close dropdown when clicking outside
+matchTriggerWidth: boolean   // Make content width match trigger width
+
+// Dropdown Events
+@open    // Fires when dropdown opens
+@close   // Fires when dropdown closes
+@select  // Fires when an item is selected (if using menu items)
+
+// Dropdown Methods
+dropdown.open() -> void    // Programmatically open the dropdown
+dropdown.close() -> void   // Programmatically close the dropdown
+dropdown.toggle() -> void  // Toggle the dropdown state
+
+// Examples
+// Basic dropdown menu
+<schmancy-dropdown>
+  <schmancy-button slot="trigger">
+    <span>Actions</span>
+    <schmancy-icon slot="suffix" icon="chevron-down"></schmancy-icon>
+  </schmancy-button>
+  
+  <schmancy-menu slot="content">
+    <schmancy-menu-item @click=${viewItem}>
+      <schmancy-icon slot="prefix" icon="eye"></schmancy-icon>
+      View
+    </schmancy-menu-item>
+    
+    <schmancy-menu-item @click=${editItem}>
+      <schmancy-icon slot="prefix" icon="edit"></schmancy-icon>
+      Edit
+    </schmancy-menu-item>
+    
+    <schmancy-divider></schmancy-divider>
+    
+    <schmancy-menu-item variant="danger" @click=${deleteItem}>
+      <schmancy-icon slot="prefix" icon="trash"></schmancy-icon>
+      Delete
+    </schmancy-menu-item>
+  </schmancy-menu>
+</schmancy-dropdown>
+
+// Profile dropdown
+<schmancy-dropdown position="bottom-end">
+  <div slot="trigger" style="cursor: pointer;">
+    <schmancy-avatar
+      src="path/to/avatar.jpg"
+      size="medium">
+    </schmancy-avatar>
+  </div>
+  
+  <div slot="content">
+    <div style="padding: 16px; text-align: center;">
+      <schmancy-avatar
+        src="path/to/avatar.jpg"
+        size="large">
+      </schmancy-avatar>
+      <h3>John Doe</h3>
+      <p>john@example.com</p>
+    </div>
+    
+    <schmancy-divider></schmancy-divider>
+    
+    <schmancy-menu>
+      <schmancy-menu-item @click=${viewProfile}>
+        <schmancy-icon slot="prefix" icon="user"></schmancy-icon>
+        Profile
+      </schmancy-menu-item>
+      
+      <schmancy-menu-item @click=${openSettings}>
+        <schmancy-icon slot="prefix" icon="settings"></schmancy-icon>
+        Settings
+      </schmancy-menu-item>
+      
+      <schmancy-divider></schmancy-divider>
+      
+      <schmancy-menu-item @click=${signOut}>
+        <schmancy-icon slot="prefix" icon="logout"></schmancy-icon>
+        Sign Out
+      </schmancy-menu-item>
+    </schmancy-menu>
+  </div>
+</schmancy-dropdown>
+
+// Dropdown with form
+<schmancy-dropdown>
+  <schmancy-button slot="trigger">
+    Add User
+  </schmancy-button>
+  
+  <div slot="content" style="padding: 16px; width: 300px;">
+    <h3>Add User</h3>
+    <schmancy-form @submit=${(e) => {
+      addUser(e.detail.values);
+      dropdown.close();
+    }}>
+      <schmancy-input
+        name="name"
+        label="Name"
+        required>
+      </schmancy-input>
+      
+      <schmancy-input
+        name="email"
+        label="Email"
+        type="email"
+        required>
+      </schmancy-input>
+      
+      <div style="display: flex; justify-content: flex-end; gap: 8px; margin-top: 16px;">
+        <schmancy-button
+          type="button"
+          variant="tertiary"
+          @click=${() => dropdown.close()}>
+          Cancel
+        </schmancy-button>
+        
+        <schmancy-button
+          type="submit"
+          variant="primary">
+          Add
+        </schmancy-button>
+      </div>
+    </schmancy-form>
+  </div>
+</schmancy-dropdown>
+
+// Icon button dropdown
+<schmancy-dropdown>
+  <schmancy-icon-button
+    slot="trigger"
+    icon="more-vertical">
+  </schmancy-icon-button>
+  
+  <schmancy-menu slot="content">
+    <schmancy-menu-item>Option 1</schmancy-menu-item>
+    <schmancy-menu-item>Option 2</schmancy-menu-item>
+    <schmancy-menu-item>Option 3</schmancy-menu-item>
+  </schmancy-menu>
+</schmancy-dropdown>
+
+// Filter dropdown
+<schmancy-dropdown>
+  <schmancy-button slot="trigger" variant="tertiary">
+    <schmancy-icon slot="prefix" icon="filter"></schmancy-icon>
+    Filter
+  </schmancy-button>
+  
+  <div slot="content" style="padding: 16px; width: 250px;">
+    <h3>Filters</h3>
+    
+    <div style="margin-bottom: 16px;">
+      <label>Status</label>
+      <schmancy-radio-group>
+        <schmancy-radio-button value="all" label="All"></schmancy-radio-button>
+        <schmancy-radio-button value="active" label="Active"></schmancy-radio-button>
+        <schmancy-radio-button value="inactive" label="Inactive"></schmancy-radio-button>
+      </schmancy-radio-group>
+    </div>
+    
+    <div style="margin-bottom: 16px;">
+      <label>Categories</label>
+      <schmancy-checkbox label="Products"></schmancy-checkbox>
+      <schmancy-checkbox label="Services"></schmancy-checkbox>
+      <schmancy-checkbox label="Resources"></schmancy-checkbox>
+    </div>
+    
+    <schmancy-button 
+      variant="primary" 
+      style="width: 100%;"
+      @click=${applyFilters}>
+      Apply Filters
+    </schmancy-button>
+  </div>
+</schmancy-dropdown>
+```

package/ai/form.md

@@ -0,0 +1,148 @@
+# Schmancy Form - AI Reference
+
+```js
+// Form Container
+<schmancy-form
+  @submit=${handleSubmit}
+  @validate=${handleValidation}
+  @change=${handleChange}>
+  <!-- Form fields go here -->
+</schmancy-form>
+
+// Form v2 (enhanced version with model binding)
+<schmancy-form-v2
+  .model=${formData}
+  .validators=${validators}
+  @submit=${handleSubmit}
+  @change=${handleChange}>
+  <!-- Form fields go here -->
+</schmancy-form-v2>
+
+// Form Methods
+form.submit() -> Promise<any>
+form.reset() -> void
+form.validate() -> Promise<boolean>
+form.setErrors({fieldName: errorMessage}) -> void
+form.getValues() -> Object
+
+// Events
+@submit // { detail: { values: Object, isValid: boolean } }
+@validate // { detail: { errors: Object, isValid: boolean } }
+@change // { detail: { name: string, value: any, values: Object } }
+
+// Examples
+// 1. Basic form with validation
+<schmancy-form @submit=${(e) => {
+  const values = e.detail.values;
+  console.log('Form submitted:', values);
+}}>
+  <schmancy-input 
+    name="email"
+    label="Email Address"
+    required
+    error=${emailError}>
+  </schmancy-input>
+  
+  <schmancy-button type="submit">Submit</schmancy-button>
+</schmancy-form>
+
+// 2. Form v2 with model binding and validators
+<schmancy-form-v2
+  .model=${{
+    username: '',
+    password: ''
+  }}
+  .validators=${{
+    username: (value) => value ? '' : 'Username is required',
+    password: (value) => value.length >= 8 ? '' : 'Password must be at least 8 characters'
+  }}
+  @submit=${(e) => console.log('Valid data:', e.detail.values)}>
+  
+  <schmancy-input name="username" label="Username"></schmancy-input>
+  <schmancy-input name="password" label="Password" type="password"></schmancy-input>
+  
+  <schmancy-button type="submit">Login</schmancy-button>
+</schmancy-form-v2>
+```
+
+## Related Components
+- **[Input](./input.md)**: Form input fields for text entry
+- **[Textarea](./textarea.md)**: Multi-line text input fields
+- **[Select](./select.md)**: Dropdown selection fields
+- **[Checkbox](./checkbox.md)**: Boolean selection controls
+- **[Radio-Group](./radio-group.md)**: Exclusive option selection controls
+- **[Button](./button.md)**: Action triggers for form submission
+
+## Technical Details
+
+### Form Field Common Attributes
+All form fields (input, textarea, select, checkbox, radio) support these attributes:
+```js
+name="field-name"       // Field identifier
+label="Field Label"     // Display label
+required?               // Makes field required
+disabled?               // Disables the field
+readonly?               // Makes field read-only
+value="initial value"   // Sets initial value
+error="Error message"   // Shows validation error
+success?                // Shows success state
+placeholder="Text"      // Placeholder text (where applicable)
+```
+
+### Form v2 Interfaces
+```typescript
+interface FormModel {
+  [key: string]: any;
+}
+
+interface FormValidators {
+  [key: string]: (value: any, allValues: FormModel) => string | null;
+}
+
+interface FormErrors {
+  [key: string]: string;
+}
+```
+
+### Common Use Cases
+
+1. **Multi-step forms**: Create wizard-like experiences
+   ```html
+   <schmancy-form id="step1" @submit=${nextStep}>
+     <!-- Step 1 fields -->
+   </schmancy-form>
+   
+   <schmancy-form id="step2" @submit=${submitAll} style="display: none;">
+     <!-- Step 2 fields -->
+   </schmancy-form>
+   ```
+
+2. **Dynamic form fields**: Add or remove fields based on user input
+   ```js
+   <schmancy-form-v2
+     .model=${dynamicModel}
+     .validators=${dynamicValidators}>
+     ${dynamicFields.map(field => html`
+       <schmancy-input name=${field.name} label=${field.label}></schmancy-input>
+     `)}
+     <button type="button" @click=${addField}>Add Field</button>
+   </schmancy-form-v2>
+   ```
+
+3. **Form with server validation**: Handle backend validation errors
+   ```js
+   async function submitForm(e) {
+     try {
+       const response = await fetch('/api/submit', {
+         method: 'POST',
+         body: JSON.stringify(e.detail.values)
+       });
+       const data = await response.json();
+       if (!data.success) {
+         formRef.setErrors(data.errors);
+       }
+     } catch (error) {
+       console.error(error);
+     }
+   }
+   ```

package/ai/icons.md

@@ -0,0 +1,147 @@
+# Schmancy Icons - AI Reference
+
+```js
+// Basic Icon
+<schmancy-icon
+  icon="icon-name"
+  size="small|medium|large|x-large"
+  color="primary|secondary|success|warning|danger|info|currentColor">
+</schmancy-icon>
+
+// Icon with custom size
+<schmancy-icon
+  icon="home"
+  size="24px">
+</schmancy-icon>
+
+// Icon with custom color
+<schmancy-icon
+  icon="star"
+  color="#f5a623">
+</schmancy-icon>
+
+// Icon Properties
+icon: string         // Icon name to display
+size: string         // Size: "small" (16px), "medium" (24px), "large" (32px), "x-large" (48px), or custom size
+color: string        // Color: semantic colors, CSS color values, or "currentColor"
+rotate: number       // Rotation in degrees
+flip: string         // Flip transformation: "horizontal", "vertical", "both"
+spin: boolean        // Apply a spinning animation
+clickable: boolean   // Make icon clickable with hover effects
+
+// Icon Events
+@click   // Fires when icon is clicked
+
+// Available Icons
+// The library includes a comprehensive set of icons. Some common ones:
+// - UI Actions: "add", "remove", "edit", "delete", "search", "close", "check", "menu"
+// - Navigation: "home", "back", "forward", "up", "down", "download", "upload"
+// - Communication: "mail", "chat", "phone", "notification", "share"
+// - Media: "play", "pause", "stop", "volume", "camera", "image"
+// - Objects: "file", "folder", "document", "calendar", "clock", "location"
+// - Social: "user", "group", "like", "star", "settings"
+// - Alerts: "info", "warning", "error", "success"
+// - Arrows: "arrow-up", "arrow-right", "arrow-down", "arrow-left"
+// - Chevrons: "chevron-up", "chevron-right", "chevron-down", "chevron-left"
+
+// Examples
+// Basic icon usage
+<schmancy-icon icon="home"></schmancy-icon>
+
+// Icons with different sizes
+<div>
+  <schmancy-icon icon="star" size="small"></schmancy-icon>
+  <schmancy-icon icon="star" size="medium"></schmancy-icon>
+  <schmancy-icon icon="star" size="large"></schmancy-icon>
+  <schmancy-icon icon="star" size="x-large"></schmancy-icon>
+  <schmancy-icon icon="star" size="64px"></schmancy-icon>
+</div>
+
+// Icons with different colors
+<div>
+  <schmancy-icon icon="info" color="info"></schmancy-icon>
+  <schmancy-icon icon="check" color="success"></schmancy-icon>
+  <schmancy-icon icon="warning" color="warning"></schmancy-icon>
+  <schmancy-icon icon="error" color="danger"></schmancy-icon>
+  <schmancy-icon icon="help" color="primary"></schmancy-icon>
+  <schmancy-icon icon="settings" color="secondary"></schmancy-icon>
+  <schmancy-icon icon="star" color="#f5a623"></schmancy-icon>
+</div>
+
+// Icon in a button
+<schmancy-button>
+  <schmancy-icon slot="prefix" icon="download"></schmancy-icon>
+  Download
+</schmancy-button>
+
+<schmancy-icon-button icon="edit"></schmancy-icon-button>
+
+// Icon with rotation and flip
+<div>
+  <schmancy-icon icon="arrow-right" rotate="45"></schmancy-icon>
+  <schmancy-icon icon="arrow-right" rotate="90"></schmancy-icon>
+  <schmancy-icon icon="arrow-right" rotate="180"></schmancy-icon>
+  <schmancy-icon icon="arrow-right" rotate="270"></schmancy-icon>
+  <schmancy-icon icon="arrow-right" flip="horizontal"></schmancy-icon>
+  <schmancy-icon icon="arrow-right" flip="vertical"></schmancy-icon>
+</div>
+
+// Spinning icon
+<schmancy-icon icon="refresh" spin></schmancy-icon>
+
+// Loading state with icon
+<div>
+  <schmancy-icon icon="refresh" spin></schmancy-icon>
+  <span>Loading...</span>
+</div>
+
+// Icon in form fields
+<schmancy-input>
+  <schmancy-icon slot="prefix" icon="search"></schmancy-icon>
+</schmancy-input>
+
+<schmancy-input type="password">
+  <schmancy-icon 
+    slot="suffix" 
+    icon=${passwordVisible ? "eye-off" : "eye"}
+    clickable
+    @click=${togglePasswordVisibility}>
+  </schmancy-icon>
+</schmancy-input>
+
+// Navigation menu with icons
+<schmancy-list interactive>
+  <schmancy-list-item>
+    <schmancy-icon slot="start" icon="home"></schmancy-icon>
+    Home
+  </schmancy-list-item>
+  <schmancy-list-item>
+    <schmancy-icon slot="start" icon="user"></schmancy-icon>
+    Profile
+  </schmancy-list-item>
+  <schmancy-list-item>
+    <schmancy-icon slot="start" icon="settings"></schmancy-icon>
+    Settings
+  </schmancy-list-item>
+  <schmancy-list-item>
+    <schmancy-icon slot="start" icon="help"></schmancy-icon>
+    Help
+  </schmancy-list-item>
+</schmancy-list>
+
+// Status indicators with icons
+<div>
+  <div style="display: flex; align-items: center; gap: 8px;">
+    <schmancy-icon icon="check-circle" color="success"></schmancy-icon>
+    <span>Completed</span>
+  </div>
+  <div style="display: flex; align-items: center; gap: 8px;">
+    <schmancy-icon icon="clock" color="warning"></schmancy-icon>
+    <span>Pending</span>
+  </div>
+  <div style="display: flex; align-items: center; gap: 8px;">
+    <schmancy-icon icon="x-circle" color="danger"></schmancy-icon>
+    <span>Failed</span>
+  </div>
+</div>
+```

package/ai/index.md

@@ -0,0 +1,72 @@
+# Schmancy Component Library - AI Reference
+
+This directory contains concise reference documentation for the Schmancy component library, formatted for AI assistance.
+
+## Components
+
+- [Area](./area.md) - Routing and subscription API for application areas
+- [Button](./button.md) - Primary, secondary, and tertiary buttons with various states
+- [Content Drawer](./content-drawer.md) - Sliding panel system for navigation and overlays
+- [Dialog](./dialog.md) - Modal dialog boxes for confirmations and custom content
+- [Form](./form.md) - Form containers with validation capabilities
+- [Input](./input.md) - Text input fields with various types and features
+- [Layout](./layout.md) - Flex and grid layout components
+- [List](./list.md) - Interactive lists with selection support
+- [Notification](./notification.md) - Toast notifications and alerts
+- [Sheet](./sheet.md) - Side panels and drawers
+- [Store](./store.md) - State management system
+- [Tabs](./tabs.md) - Tabbed interface components
+
+## Reference Format
+
+Each reference file follows a consistent pattern:
+
+```js
+// Component name and basic usage
+<component-name attribute="value" boolean-attribute>
+  Content or children
+</component-name>
+
+// Component variations and options
+<component-name 
+  option1="value"
+  option2>
+  <!-- Structure examples -->
+</component-name>
+
+// Component methods and events
+component.method() -> returnType
+@event // Event description with { detail: { properties } }
+
+// Examples of common usage patterns (numbered for clarity)
+// 1. Basic usage
+<component-name attribute="value">
+  Example content
+</component-name>
+
+// 2. Advanced configuration
+<component-name attribute="value" advanced-config="true">
+  Complex example
+</component-name>
+```
+
+Each component documentation also includes:
+
+- **Related Components**: Links to related components with relationship descriptions
+- **Technical Details**: Interfaces, types, CSS custom properties
+- **Common Use Cases**: Practical examples with explanations
+
+This format is designed to quickly convey:
+1. Component tag names and attributes
+2. Available options and variations
+3. Component methods and events
+4. Relationships to other components
+5. Practical usage patterns
+
+For detailed documentation guidelines, see [template.md](./template.md).
+
+## Library Structure
+
+The Schmancy library is organized into individual component directories under `/src`, each exporting its components through an `index.ts` file. The main library entry point is `/src/index.ts` which re-exports all components.
+
+Most components follow LitElement patterns with TypeScript typing and are designed to be used with a reactive rendering system like lit-html.