snice 2.5.4 → 3.2.0

package/docs/ai/components/select.md

@@ -0,0 +1,92 @@
+# snice-select
+
+Customizable dropdown selection with single/multiple selection, search, and icons.
+
+## Components
+
+### snice-select (Container)
+
+```typescript
+value: string = '';                 // Selected value (comma-separated for multiple)
+disabled: boolean = false;          // Disabled state
+required: boolean = false;          // Required for form validation
+invalid: boolean = false;           // Invalid state styling
+readonly: boolean = false;          // Readonly state
+multiple: boolean = false;          // Allow multiple selection
+searchable: boolean = false;        // Show search input
+clearable: boolean = false;         // Show clear button
+open: boolean = false;              // Dropdown open state
+size: 'small'|'medium'|'large' = 'medium';
+name: string = '';                  // Form field name
+label: string = '';                 // Label text
+placeholder: string = 'Select an option';
+maxHeight: string = '200px';        // Max dropdown height
+```
+
+**Methods:**
+```typescript
+selectOption(value: string)  // Select option by value
+clear()                      // Clear selection
+openDropdown()               // Open dropdown
+closeDropdown()              // Close dropdown
+toggleDropdown()             // Toggle dropdown
+focus()                      // Focus trigger
+blur()                       // Blur and close
+```
+
+**Events:**
+```typescript
+'@snice/select-change'  // { value, option, select }
+'@snice/select-open'    // { select }
+'@snice/select-close'   // { select }
+```
+
+### snice-option (Option Item)
+
+```typescript
+value: string = '';           // Option value (defaults to label)
+label: string = '';           // Option label (defaults to textContent)
+disabled: boolean = false;    // Disabled state
+selected: boolean = false;    // Initially selected
+icon: string = '';            // Icon URL
+```
+
+**Getter:**
+```typescript
+optionData  // { value, label, disabled, selected, icon }
+```
+
+## Usage
+
+```html
+<snice-select label="Choose" name="choice">
+  <snice-option value="1">Option 1</snice-option>
+  <snice-option value="2">Option 2</snice-option>
+</snice-select>
+```
+
+```typescript
+select.addEventListener('@snice/select-change', (e) => {
+  console.log(e.detail.value);
+});
+
+select.selectOption('1');
+```
+
+## Features
+
+- Single and multiple selection
+- Search filtering
+- Keyboard navigation
+- Form integration
+- Icons in options
+- Clearable selection
+- Disabled options
+
+## Notes
+
+- Options must be direct children of select
+- Multiple selection values are comma-separated
+- Hidden native select for form submission
+- Dropdown closes outside click
+- Search shows in dropdown when open

package/docs/ai/components/skeleton.md

@@ -0,0 +1,57 @@
+# snice-skeleton
+
+Loading placeholder with animated shimmer effect.
+
+## Properties
+
+```typescript
+variant: 'text'|'circular'|'rectangular'|'rounded' = 'text';
+width: string = '';
+height: string = '';
+animation: 'pulse'|'wave'|'none' = 'pulse';
+count: number = 1;
+spacing: string = '8px';
+```
+
+## Usage
+
+```html
+<!-- Text placeholder -->
+<snice-skeleton variant="text"></snice-skeleton>
+<snice-skeleton variant="text" width="200px"></snice-skeleton>
+
+<!-- Circular (avatar) -->
+<snice-skeleton variant="circular" width="40px" height="40px"></snice-skeleton>
+
+<!-- Rectangular -->
+<snice-skeleton variant="rectangular" width="100%" height="200px"></snice-skeleton>
+
+<!-- Rounded (card) -->
+<snice-skeleton variant="rounded" width="300px" height="150px"></snice-skeleton>
+
+<!-- Multiple lines -->
+<snice-skeleton variant="text" count="3"></snice-skeleton>
+<snice-skeleton variant="text" count="5" spacing="12px"></snice-skeleton>
+
+<!-- Animation types -->
+<snice-skeleton animation="pulse"></snice-skeleton>
+<snice-skeleton animation="wave"></snice-skeleton>
+<snice-skeleton animation="none"></snice-skeleton>
+
+<!-- Complex layout -->
+<div style="display: flex; gap: 16px;">
+  <snice-skeleton variant="circular" width="48px" height="48px"></snice-skeleton>
+  <div style="flex: 1;">
+    <snice-skeleton variant="text" width="40%"></snice-skeleton>
+    <snice-skeleton variant="text" width="60%"></snice-skeleton>
+  </div>
+</div>
+```
+
+## Features
+
+- 4 shape variants (text/circular/rectangular/rounded)
+- 3 animation styles (pulse/wave/none)
+- Custom dimensions
+- Multiple skeleton elements with spacing
+- Mimics loading content shapes

package/docs/ai/components/slider.md

@@ -0,0 +1,87 @@
+# snice-slider
+
+Range slider for numeric value selection.
+
+## Properties
+
+```typescript
+value: number = 0;
+min: number = 0;
+max: number = 100;
+step: number = 1;
+variant: 'default'|'primary'|'success'|'warning'|'danger' = 'default';
+size: 'small'|'medium'|'large' = 'medium';
+disabled: boolean = false;
+required: boolean = false;
+invalid: boolean = false;
+readonly: boolean = false;
+label: string = '';
+helperText: string = '';
+errorText: string = '';
+name: string = '';
+showValue: boolean = false;
+showTicks: boolean = false;
+vertical: boolean = false;
+```
+
+## Methods
+
+- `focus()` - Focus slider thumb
+- `blur()` - Blur slider thumb
+
+## Events
+
+- `input` - {value, slider} - During drag
+- `change` - {value, slider} - After drag complete
+
+## Usage
+
+```html
+<!-- Basic -->
+<snice-slider label="Volume" min="0" max="100"></snice-slider>
+
+<!-- With value display -->
+<snice-slider show-value value="50"></snice-slider>
+
+<!-- With ticks -->
+<snice-slider show-ticks min="0" max="10" step="1"></snice-slider>
+
+<!-- Variants -->
+<snice-slider variant="primary"></snice-slider>
+<snice-slider variant="success"></snice-slider>
+<snice-slider variant="warning"></snice-slider>
+<snice-slider variant="danger"></snice-slider>
+
+<!-- Sizes -->
+<snice-slider size="small"></snice-slider>
+<snice-slider size="medium"></snice-slider>
+<snice-slider size="large"></snice-slider>
+
+<!-- Vertical -->
+<snice-slider vertical></snice-slider>
+
+<!-- Step increments -->
+<snice-slider min="0" max="100" step="5" value="50"></snice-slider>
+
+<!-- Events -->
+<snice-slider id="slider"></snice-slider>
+<script>
+const slider = document.querySelector('#slider');
+slider.addEventListener('@snice/slider-change', (e) => {
+  console.log('Value:', e.detail.value);
+});
+</script>
+```
+
+## Features
+
+- Form-associated custom element
+- Mouse and touch support
+- Keyboard navigation (arrows, home/end, page up/down)
+- 5 color variants
+- 3 sizes
+- Vertical orientation
+- Optional value display
+- Optional tick marks
+- Step increments
+- Accessible

package/docs/ai/components/sparkline.md

@@ -0,0 +1,168 @@
+# snice-sparkline
+
+Compact inline chart for visualizing trends and patterns. For dashboards, tables, data-dense interfaces.
+
+## Properties
+
+```typescript
+data: number[] = []                     // Values to visualize
+type: SparklineType = 'line'            // 'line' | 'bar' | 'area'
+color: SparklineColor = 'primary'       // 'primary' | 'success' | 'warning' | 'danger' | 'muted'
+customColor?: string                    // Any CSS color (overrides color)
+width: number = 100                     // Chart width in pixels
+height: number = 30                     // Chart height in pixels
+strokeWidth: number = 2                 // Line/dot stroke width
+showDots: boolean = false               // Show dots on data points (line charts)
+showArea: boolean = false               // Show area fill (line charts)
+smooth: boolean = false                 // Use smooth bezier curves
+min?: number                            // Min value for scaling (auto if unset)
+max?: number                            // Max value for scaling (auto if unset)
+```
+
+## Usage
+
+```html
+<!-- Basic -->
+<snice-sparkline id="chart"></snice-sparkline>
+<script>
+  document.getElementById('chart').data = [10, 20, 15, 25, 30];
+</script>
+
+<!-- Line chart -->
+<snice-sparkline id="line" type="line"></snice-sparkline>
+
+<!-- Bar chart -->
+<snice-sparkline id="bar" type="bar"></snice-sparkline>
+
+<!-- Area chart -->
+<snice-sparkline id="area" type="area"></snice-sparkline>
+
+<!-- Smooth curves -->
+<snice-sparkline id="smooth" smooth></snice-sparkline>
+
+<!-- With dots -->
+<snice-sparkline id="dots" show-dots></snice-sparkline>
+
+<!-- With area fill -->
+<snice-sparkline id="fill" show-area></snice-sparkline>
+
+<!-- Colors -->
+<snice-sparkline color="primary"></snice-sparkline>
+<snice-sparkline color="success"></snice-sparkline>
+<snice-sparkline color="warning"></snice-sparkline>
+<snice-sparkline color="danger"></snice-sparkline>
+<snice-sparkline color="muted"></snice-sparkline>
+
+<!-- Custom colors -->
+<snice-sparkline custom-color="#9333ea"></snice-sparkline>
+<snice-sparkline custom-color="rgb(147, 51, 234)"></snice-sparkline>
+<snice-sparkline custom-color="hsl(270, 80%, 60%)"></snice-sparkline>
+
+<!-- Sizing -->
+<snice-sparkline width="200" height="50"></snice-sparkline>
+
+<!-- Custom scale -->
+<snice-sparkline min="0" max="100"></snice-sparkline>
+
+<!-- Combined features -->
+<snice-sparkline
+  id="advanced"
+  type="line"
+  color="primary"
+  width="150"
+  height="40"
+  smooth
+  show-area
+  min="0">
+</snice-sparkline>
+```
+
+## CSS Parts
+
+```css
+::part(container)  /* Container div */
+::part(svg)        /* SVG element */
+::part(line)       /* Line/path element */
+::part(area)       /* Area polygon/path */
+::part(bar)        /* Bar rect */
+::part(dot)        /* Dot circle */
+```
+
+## Styling
+
+```css
+--snice-color-primary
+--snice-color-success
+--snice-color-warning
+--snice-color-danger
+--snice-color-text-secondary
+```
+
+## In Tables
+
+```html
+<snice-table id="table"></snice-table>
+<script>
+  document.getElementById('table').data = [
+    {
+      product: 'A',
+      trend: [10, 15, 12, 18, 22, 25]
+    }
+  ];
+
+  document.getElementById('table').columns = [
+    { key: 'product', label: 'Product' },
+    {
+      key: 'trend',
+      label: 'Trend',
+      render: (value) => {
+        const sparkline = document.createElement('snice-sparkline');
+        sparkline.data = value;
+        sparkline.width = 80;
+        sparkline.height = 25;
+        sparkline.color = 'primary';
+        return sparkline;
+      }
+    }
+  ];
+</script>
+```
+
+## Common Patterns
+
+```html
+<!-- Website traffic -->
+<snice-sparkline
+  id="traffic"
+  color="primary"
+  width="150"
+  height="40"
+  smooth
+  show-area>
+</snice-sparkline>
+
+<!-- Sales bars -->
+<snice-sparkline
+  id="sales"
+  type="bar"
+  color="success"
+  width="150"
+  height="40">
+</snice-sparkline>
+
+<!-- Response time with dots -->
+<snice-sparkline
+  id="response"
+  color="warning"
+  smooth
+  show-dots>
+</snice-sparkline>
+
+<!-- Error rate -->
+<snice-sparkline
+  id="errors"
+  type="area"
+  color="danger"
+  min="0">
+</snice-sparkline>
+```

package/docs/ai/components/spinner.md

@@ -0,0 +1,47 @@
+# snice-spinner
+
+Animated loading spinner.
+
+## Properties
+
+```typescript
+size: 'small'|'medium'|'large'|'xl' = 'medium';
+color: 'primary'|'success'|'warning'|'error'|'info' = 'primary';
+label: string = '';
+thickness: number = 4;
+```
+
+## Usage
+
+```html
+<!-- Basic -->
+<snice-spinner></snice-spinner>
+
+<!-- Sizes -->
+<snice-spinner size="small"></snice-spinner>
+<snice-spinner size="medium"></snice-spinner>
+<snice-spinner size="large"></snice-spinner>
+<snice-spinner size="xl"></snice-spinner>
+
+<!-- Colors -->
+<snice-spinner color="primary"></snice-spinner>
+<snice-spinner color="success"></snice-spinner>
+<snice-spinner color="warning"></snice-spinner>
+<snice-spinner color="error"></snice-spinner>
+<snice-spinner color="info"></snice-spinner>
+
+<!-- With label -->
+<snice-spinner label="Loading..."></snice-spinner>
+
+<!-- Custom thickness -->
+<snice-spinner thickness="6"></snice-spinner>
+```
+
+## Features
+
+- Smooth circular animation
+- 4 sizes
+- 5 color variants
+- Optional label
+- Accessible (role=status, aria-label)
+- Lightweight SVG-based

package/docs/ai/components/stepper.md

@@ -0,0 +1,216 @@
+# snice-stepper
+
+Step indicator for multi-step processes, wizards, workflows. Shows progress with pending/active/completed/error states.
+
+## Properties
+
+```typescript
+steps: Step[] = []                          // Array of step objects
+currentStep: number = 0                     // Current active step index
+orientation: StepperOrientation = 'horizontal' // 'horizontal' | 'vertical'
+clickable: boolean = false                  // Enable click navigation
+
+// Step object:
+{
+  label: string;           // Step label (required)
+  description?: string;    // Optional description
+  status?: StepStatus;     // Override auto status: 'pending' | 'active' | 'completed' | 'error'
+}
+```
+
+## Usage
+
+```html
+<!-- Basic horizontal -->
+<snice-stepper id="basic"></snice-stepper>
+<script>
+  document.getElementById('basic').steps = [
+    { label: 'Step 1' },
+    { label: 'Step 2' },
+    { label: 'Step 3' }
+  ];
+  document.getElementById('basic').currentStep = 1;
+</script>
+
+<!-- With panels (auto show/hide) -->
+<snice-stepper id="wizard" clickable></snice-stepper>
+<snice-stepper-panel>Step 1 content</snice-stepper-panel>
+<snice-stepper-panel>Step 2 content</snice-stepper-panel>
+<snice-stepper-panel>Step 3 content</snice-stepper-panel>
+<script>
+  document.getElementById('wizard').steps = [
+    { label: 'Account' },
+    { label: 'Profile' },
+    { label: 'Complete' }
+  ];
+</script>
+
+<!-- Vertical with descriptions -->
+<snice-stepper id="vertical" orientation="vertical"></snice-stepper>
+<script>
+  document.getElementById('vertical').steps = [
+    { label: 'Account', description: 'Create your account' },
+    { label: 'Profile', description: 'Personal info' },
+    { label: 'Complete', description: 'Finish setup' }
+  ];
+</script>
+
+<!-- Clickable navigation -->
+<snice-stepper id="wizard" clickable></snice-stepper>
+<script>
+  const wizard = document.getElementById('wizard');
+  wizard.steps = [
+    { label: 'Cart' },
+    { label: 'Delivery' },
+    { label: 'Payment' },
+    { label: 'Confirm' }
+  ];
+
+  wizard.addEventListener('step-change', (e) => {
+    console.log(e.detail.previousStep); // Previous step index
+    console.log(e.detail.currentStep);  // New step index
+    console.log(e.detail.step);         // Step object
+    // e.preventDefault(); to cancel navigation
+  });
+</script>
+
+<!-- Error state -->
+<snice-stepper id="validation"></snice-stepper>
+<script>
+  document.getElementById('validation').steps = [
+    { label: 'Upload', status: 'completed' },
+    { label: 'Validate', status: 'error' },
+    { label: 'Process', status: 'pending' }
+  ];
+</script>
+
+<!-- Programmatic navigation -->
+<script>
+  const stepper = document.getElementById('my-stepper');
+  stepper.currentStep++; // Next
+  stepper.currentStep--; // Previous
+  stepper.currentStep = 2; // Go to step 3
+</script>
+```
+
+## Events
+
+```javascript
+// step-change (only in clickable mode)
+stepper.addEventListener('step-change', (e) => {
+  const { previousStep, currentStep, step } = e.detail;
+  e.preventDefault(); // Cancel navigation if needed
+});
+```
+
+## CSS Parts
+
+```css
+::part(container)       /* Main container */
+::part(step)            /* Individual step */
+::part(step-indicator)  /* Circular indicator */
+::part(step-content)    /* Label + description wrapper */
+::part(step-label)      /* Step label text */
+::part(step-description) /* Description text */
+::part(step-connector)  /* Line between steps */
+```
+
+## Styling
+
+```css
+--snice-color-primary       /* Active state */
+--snice-color-success       /* Completed state */
+--snice-color-danger        /* Error state */
+--snice-color-text
+--snice-color-text-secondary /* Pending state */
+--snice-color-text-inverse  /* Indicator text */
+--snice-color-background
+--snice-color-border
+--snice-spacing-xs
+--snice-spacing-sm
+--snice-spacing-md
+--snice-spacing-lg
+--snice-font-size-xs
+--snice-font-size-sm
+--snice-font-weight-medium
+--snice-font-weight-semibold
+--snice-transition-fast
+```
+
+## Common Patterns
+
+```html
+<!-- Checkout flow -->
+<snice-stepper id="checkout" clickable></snice-stepper>
+<button onclick="document.getElementById('checkout').currentStep--">Back</button>
+<button onclick="document.getElementById('checkout').currentStep++">Next</button>
+<script>
+  document.getElementById('checkout').steps = [
+    { label: 'Cart', description: 'Review items' },
+    { label: 'Delivery', description: 'Shipping address' },
+    { label: 'Payment', description: 'Billing info' },
+    { label: 'Confirm', description: 'Place order' }
+  ];
+</script>
+
+<!-- Onboarding wizard (vertical) -->
+<snice-stepper id="onboarding" orientation="vertical" clickable></snice-stepper>
+<script>
+  document.getElementById('onboarding').steps = [
+    { label: 'Welcome' },
+    { label: 'Profile Setup' },
+    { label: 'Preferences' },
+    { label: 'Get Started' }
+  ];
+</script>
+
+<!-- Form validation -->
+<snice-stepper id="form"></snice-stepper>
+<script>
+  document.getElementById('form').steps = [
+    { label: 'Personal Info', status: 'completed' },
+    { label: 'Address', status: 'error' },  // Has validation error
+    { label: 'Review', status: 'pending' }
+  ];
+</script>
+
+<!-- Progress tracker -->
+<snice-stepper id="upload"></snice-stepper>
+<script>
+  const upload = document.getElementById('upload');
+  upload.steps = [
+    { label: 'Upload', status: 'completed' },
+    { label: 'Process', status: 'active' },
+    { label: 'Complete', status: 'pending' }
+  ];
+  upload.currentStep = 1;
+</script>
+```
+
+## Stepper Panels
+
+```html
+<!-- Panels auto show/hide based on currentStep -->
+<snice-stepper id="wizard"></snice-stepper>
+<snice-stepper-panel>Content for step 0</snice-stepper-panel>
+<snice-stepper-panel>Content for step 1</snice-stepper-panel>
+<snice-stepper-panel>Content for step 2</snice-stepper-panel>
+```
+
+- Panels must be direct children of stepper
+- Panel index matches order (first panel = step 0, etc.)
+- Automatically activated when stepper.currentStep changes
+- Only active panel is visible (display: block), others hidden
+
+## Notes
+
+- Status auto-computed from currentStep if not explicitly set:
+  - Steps before currentStep: 'completed' (shows ✓)
+  - Step at currentStep: 'active'
+  - Steps after currentStep: 'pending'
+- Completed steps show checkmark (✓) instead of number
+- Connector lines auto-hidden on last step
+- Click events only work when clickable=true
+- step-change event is cancelable via preventDefault()
+- Orientation affects layout but not behavior
+- Panels sync automatically via @watch decorator on currentStep