@mhmo91/schmancy 0.2.192 → 0.2.194

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,71 @@
+# 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
+- [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.

package/ai/input.md

@@ -0,0 +1,167 @@
+# Schmancy Input - AI Reference
+
+```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}>
+</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.blur() -> void
+input.validate() -> boolean
+input.setCustomValidity(message) -> void
+input.select() -> void
+
+// Events
+@input // { target: { value: string } }
+@change // { target: { value: string } }
+@focus // { target: HTMLElement }
+@blur // { target: HTMLElement }
+
+// Examples
+// 1. Basic input with validation
+<schmancy-input 
+  name="email"
+  label="Email Address"
+  type="email"
+  required
+  placeholder="Enter your email"
+  @change=${(e) => console.log(e.target.value)}>
+</schmancy-input>
+
+// 2. Input with currency formatting
+<schmancy-input-v2
+  name="amount"
+  label="Amount"
+  type="number"
+  .format=${(value) => `$${value.toFixed(2)}`}
+  .parse=${(value) => parseFloat(value.replace('$', ''))}
+  .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>
+</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>
+</schmancy-input>
+```
+
+## Related Components
+- **[Form](./form.md)**: Container for input and other form components
+- **[Textarea](./textarea.md)**: Multi-line text input fields
+- **[Icons](./icons.md)**: Can be used within input slots
+- **[Autocomplete](./autocomplete.md)**: Extended input with suggestions
+
+## Technical Details
+
+### Slots
+```html
+prefix: Content displayed before the input field
+suffix: Content displayed after the input field
+```
+
+### CSS Custom Properties
+```css
+--schmancy-input-height: /* Controls the input height */
+--schmancy-input-border-color: /* Controls the border color */
+--schmancy-input-focus-color: /* Controls the focus color */
+--schmancy-input-error-color: /* Controls the error state color */
+--schmancy-input-success-color: /* Controls the success state color */
+--schmancy-input-font-size: /* Controls the font size */
+```
+
+### Input v2 Interfaces
+```typescript
+interface InputValidator {
+  (value: any): string | null;
+}
+
+interface InputFormatter {
+  (value: any): string;
+}
+
+interface InputParser {
+  (displayValue: string): any;
+}
+```
+
+### Common Use Cases
+
+1. **Password input with toggle visibility**
+   ```html
+   <schmancy-input
+     type="password"
+     label="Password"
+     name="password">
+     <schmancy-icon 
+       slot="suffix" 
+       icon="eye" 
+       @click=${togglePasswordVisibility}>
+     </schmancy-icon>
+   </schmancy-input>
+   ```
+
+2. **Validating email format**
+   ```html
+   <schmancy-input-v2
+     type="email"
+     label="Email"
+     name="email"
+     .validate=${value => {
+       const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+       return emailRegex.test(value) ? '' : 'Please enter a valid email';
+     }}>
+   </schmancy-input-v2>
+   ```
+
+3. **Input with character count**
+   ```html
+   <schmancy-input
+     label="Message"
+     name="message"
+     maxlength="100"
+     @input=${e => updateCharCount(e.target.value.length)}>
+     <span slot="suffix" id="charCount">0/100</span>
+   </schmancy-input>
+   ```

package/ai/layout.md

@@ -0,0 +1,166 @@
+# Schmancy Layout - AI Reference
+
+```js
+// Grid Layout
+<schmancy-grid
+  columns="3"                    // Number of columns or template
+  rows="auto"                    // Number of rows or template
+  gap="16px"                     // Gap between items
+  column-gap="16px"              // Column-specific gap
+  row-gap="16px"                 // Row-specific gap
+  justify-items="start|center|end|stretch"
+  align-items="start|center|end|stretch"
+  justify-content="start|center|end|space-between|space-around|space-evenly"
+  align-content="start|center|end|space-between|space-around|space-evenly">
+  
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+</schmancy-grid>
+
+// Advanced grid with template
+<schmancy-grid
+  columns="repeat(12, 1fr)"
+  rows="auto auto 1fr"
+  template-areas="
+    'header header header header'
+    'sidebar content content content'
+    'footer footer footer footer'
+  ">
+  <div style="grid-area: header">Header</div>
+  <div style="grid-area: sidebar">Sidebar</div>
+  <div style="grid-area: content">Content</div>
+  <div style="grid-area: footer">Footer</div>
+</schmancy-grid>
+
+// Flex Layout
+<schmancy-flex
+  direction="row|column|row-reverse|column-reverse"
+  wrap="nowrap|wrap|wrap-reverse"
+  justify-content="start|center|end|space-between|space-around|space-evenly"
+  align-items="start|center|end|stretch|baseline"
+  align-content="start|center|end|space-between|space-around|space-evenly"
+  gap="16px"                     // Gap between items
+  column-gap="16px"              // Column-specific gap
+  row-gap="16px">                // Row-specific gap
+  
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div style="flex: 1">Flexible Item</div>
+</schmancy-flex>
+
+// Responsive layouts (using attributes)
+<schmancy-grid
+  columns="1"
+  columns-md="2"
+  columns-lg="3"
+  columns-xl="4"
+  gap="8px"
+  gap-md="16px"
+  gap-lg="24px">
+  
+  <!-- Content -->
+</schmancy-grid>
+
+<schmancy-flex
+  direction="column"
+  direction-md="row"
+  align-items="center"
+  justify-content-md="space-between">
+  
+  <!-- Content -->
+</schmancy-flex>
+
+// Scroll Container
+<schmancy-scroll
+  direction="vertical|horizontal|both"
+  scrollbar="auto|always|hover|none">
+  
+  <!-- Scrollable content -->
+</schmancy-scroll>
+
+// Layout v2 Components (enhanced versions)
+<schmancy-flex-v2
+  display="flex|inline-flex"
+  direction="row|column"
+  wrap="nowrap|wrap|wrap-reverse"
+  justify="flex-start|flex-end|center|space-between|space-around|space-evenly"
+  items="flex-start|flex-end|center|stretch|baseline"
+  content="flex-start|flex-end|center|space-between|space-around|space-evenly"
+  gap="none|xs|sm|md|lg|xl">
+  
+  <!-- Content -->
+</schmancy-flex-v2>
+
+<schmancy-grid-v2
+  display="grid|inline-grid"
+  template-columns="1fr 1fr|repeat(3, 1fr)"
+  template-rows="auto|1fr auto"
+  template-areas="'header header' 'sidebar content' 'footer footer'"
+  gap="none|xs|sm|md|lg|xl"
+  justify-content="start|end|center|stretch|space-around|space-between|space-evenly"
+  align-content="start|end|center|stretch|space-around|space-between|space-evenly"
+  justify-items="start|end|center|stretch"
+  align-items="start|end|center|stretch">
+  
+  <!-- Content -->
+</schmancy-grid-v2>
+
+// Examples
+// Responsive grid layout
+<schmancy-grid 
+  columns="1" 
+  columns-md="2" 
+  columns-lg="4" 
+  gap="16px">
+  <div>Card 1</div>
+  <div>Card 2</div>
+  <div>Card 3</div>
+  <div>Card 4</div>
+</schmancy-grid>
+
+// Flex layout for a form
+<schmancy-flex
+  direction="column"
+  gap="16px">
+  <h2>Contact Form</h2>
+  <schmancy-input label="Name"></schmancy-input>
+  <schmancy-input label="Email"></schmancy-input>
+  <schmancy-textarea label="Message"></schmancy-textarea>
+  
+  <schmancy-flex
+    direction="row"
+    justify-content="end"
+    gap="8px">
+    <schmancy-button kind="secondary">Cancel</schmancy-button>
+    <schmancy-button kind="primary">Submit</schmancy-button>
+  </schmancy-flex>
+</schmancy-flex>
+
+// App layout with header, sidebar and content
+<schmancy-grid
+  style="height: 100vh"
+  template-areas="
+    'header header'
+    'sidebar content'
+  "
+  template-rows="64px 1fr"
+  template-columns="250px 1fr">
+  
+  <div style="grid-area: header">
+    <schmancy-appbar>App Title</schmancy-appbar>
+  </div>
+  
+  <div style="grid-area: sidebar">
+    <schmancy-list>
+      <schmancy-list-item>Dashboard</schmancy-list-item>
+      <schmancy-list-item>Settings</schmancy-list-item>
+      <schmancy-list-item>Profile</schmancy-list-item>
+    </schmancy-list>
+  </div>
+  
+  <schmancy-scroll style="grid-area: content">
+    <!-- Main content -->
+  </schmancy-scroll>
+</schmancy-grid>
+```