snice 3.1.0 → 3.2.0

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

package/docs/ai/components/textarea.md

@@ -0,0 +1,87 @@
+# snice-textarea
+
+Multi-line text input field with auto-grow and character count.
+
+## Properties
+
+```typescript
+value: string = '';
+variant: 'outlined'|'filled'|'underlined' = 'outlined';
+size: 'small'|'medium'|'large' = 'medium';
+resize: 'none'|'vertical'|'horizontal'|'both' = 'vertical';
+placeholder: string = '';
+disabled: boolean = false;
+required: boolean = false;
+invalid: boolean = false;
+readonly: boolean = false;
+label: string = '';
+helperText: string = '';
+errorText: string = '';
+rows: number = 3;
+cols: number = -1;
+minlength: number = -1;
+maxlength: number = -1;
+autocomplete: string = '';
+name: string = '';
+autoGrow: boolean = false;
+```
+
+## Methods
+
+- `focus()` - Focus textarea
+- `blur()` - Blur textarea
+- `select()` - Select text
+
+## Events
+
+- `input` - {value, textarea}
+- `change` - {value, textarea}
+- `focus` - {textarea}
+- `blur` - {textarea}
+
+## Usage
+
+```html
+<!-- Basic -->
+<snice-textarea label="Comments" placeholder="Enter comments"></snice-textarea>
+
+<!-- Variants -->
+<snice-textarea variant="outlined"></snice-textarea>
+<snice-textarea variant="filled"></snice-textarea>
+<snice-textarea variant="underlined"></snice-textarea>
+
+<!-- Rows -->
+<snice-textarea rows="5"></snice-textarea>
+
+<!-- Auto-grow -->
+<snice-textarea auto-grow></snice-textarea>
+
+<!-- Character count -->
+<snice-textarea maxlength="500"></snice-textarea>
+
+<!-- Resize options -->
+<snice-textarea resize="none"></snice-textarea>
+<snice-textarea resize="both"></snice-textarea>
+
+<!-- Sizes -->
+<snice-textarea size="small"></snice-textarea>
+<snice-textarea size="medium"></snice-textarea>
+<snice-textarea size="large"></snice-textarea>
+
+<!-- Helper text -->
+<snice-textarea helper-text="Max 500 characters"></snice-textarea>
+
+<!-- Error state -->
+<snice-textarea invalid error-text="Required field"></snice-textarea>
+```
+
+## Features
+
+- Form-associated custom element
+- 3 visual variants
+- Auto-grow height option
+- Character counter
+- Resizable (4 modes)
+- Helper and error text
+- 3 sizes
+- Keyboard accessible

package/docs/ai/components/timeline.md

@@ -0,0 +1,77 @@
+# snice-timeline
+
+Displays chronological events with markers.
+
+## Properties
+
+```typescript
+orientation: 'vertical'|'horizontal' = 'vertical';
+position: 'left'|'right'|'alternate' = 'left';
+items: TimelineItem[] = [];
+reverse: boolean = false;
+```
+
+## TimelineItem
+
+```typescript
+interface TimelineItem {
+  timestamp?: string;
+  title: string;
+  description?: string;
+  icon?: string;
+  variant?: 'default'|'success'|'warning'|'error'|'info';
+}
+```
+
+## Usage
+
+```html
+<!-- Basic --><snice-timeline id="timeline"></snice-timeline>
+<script>
+timeline.items = [{
+  timestamp: '2024-01-15',
+  title: 'Event',
+  description: 'Details'
+}];
+</script>
+
+<!-- Vertical positions -->
+<snice-timeline position="left"></snice-timeline>
+<snice-timeline position="right"></snice-timeline>
+<snice-timeline position="alternate"></snice-timeline>
+
+<!-- Horizontal -->
+<snice-timeline orientation="horizontal"></snice-timeline>
+
+<!-- Variants -->
+<script>
+timeline.items = [
+  { title: 'Success', variant: 'success' },
+  { title: 'Warning', variant: 'warning' },
+  { title: 'Error', variant: 'error' },
+  { title: 'Info', variant: 'info' }
+];
+</script>
+
+<!-- Custom icons -->
+<script>
+timeline.items = [
+  { title: 'Planning', icon: '📋' },
+  { title: 'Development', icon: '💻' },
+  { title: 'Launch', icon: '🚀' }
+];
+</script>
+
+<!-- Reversed -->
+<snice-timeline reverse></snice-timeline>
+```
+
+## Features
+
+- Vertical and horizontal orientations
+- Left/right/alternate positioning (vertical)
+- 5 item variants with default icons
+- Custom icons supported
+- Timestamps and descriptions optional
+- Connecting lines between items
+- Reversible order

package/docs/components/banner.md

@@ -0,0 +1,106 @@
+# Banner Component
+
+The `<snice-banner>` component displays fixed-position notification banners at the top or bottom of the viewport.
+
+## Basic Usage
+
+```html
+<snice-banner
+  variant="info"
+  message="This is an informational message"
+  open
+></snice-banner>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `variant` | `'info' \| 'success' \| 'warning' \| 'error'` | `'info'` | Visual variant |
+| `position` | `'top' \| 'bottom'` | `'top'` | Position on screen |
+| `message` | `string` | `''` | Banner message |
+| `dismissible` | `boolean` | `true` | Show close button |
+| `icon` | `string` | `''` | Custom icon (default icons per variant) |
+| `actionText` | `string` | `''` | Action button text |
+| `open` | `boolean` | `false` | Banner visibility |
+
+## Methods
+
+### `show(): void`
+Show the banner.
+
+### `hide(): void`
+Hide the banner.
+
+### `toggle(): void`
+Toggle banner visibility.
+
+## Events
+
+### `@snice/banner-open`
+Fired when banner opens.
+
+### `@snice/banner-close`
+Fired when banner closes.
+
+### `@snice/banner-action`
+Fired when action button is clicked.
+
+## Examples
+
+### Variants
+
+```html
+<snice-banner variant="info" message="Info message" open></snice-banner>
+<snice-banner variant="success" message="Success!" open></snice-banner>
+<snice-banner variant="warning" message="Warning" open></snice-banner>
+<snice-banner variant="error" message="Error occurred" open></snice-banner>
+```
+
+### With Action Button
+
+```html
+<snice-banner
+  message="A new version is available"
+  action-text="Update Now"
+  open
+></snice-banner>
+
+<script>
+document.querySelector('snice-banner').addEventListener('@snice/banner-action', () => {
+  console.log('Update clicked');
+});
+</script>
+```
+
+### Bottom Position
+
+```html
+<snice-banner
+  position="bottom"
+  message="Cookie notice"
+  action-text="Accept"
+  open
+></snice-banner>
+```
+
+### Not Dismissible
+
+```html
+<snice-banner
+  message="Maintenance mode active"
+  dismissible="false"
+  variant="warning"
+  open
+></snice-banner>
+```
+
+### Programmatic Control
+
+```html
+<snice-banner id="myBanner" message="Hello"></snice-banner>
+
+<button onclick="myBanner.show()">Show</button>
+<button onclick="myBanner.hide()">Hide</button>
+<button onclick="myBanner.toggle()">Toggle</button>
+```

package/docs/components/color-display.md

@@ -0,0 +1,96 @@
+# Color Display Component
+
+The `<snice-color-display>` component displays colors with a swatch and formatted label.
+
+## Basic Usage
+
+```html
+<snice-color-display value="#3b82f6"></snice-color-display>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `value` | `string` | `''` | Color value (hex format) |
+| `format` | `'hex' \| 'rgb' \| 'hsl'` | `'hex'` | Display format |
+| `showSwatch` | `boolean` | `true` | Show color swatch |
+| `showLabel` | `boolean` | `true` | Show color label |
+| `swatchSize` | `'small' \| 'medium' \| 'large'` | `'medium'` | Swatch size |
+| `label` | `string` | `''` | Custom label text |
+
+## Examples
+
+### Basic Colors
+
+```html
+<snice-color-display value="#ff0000"></snice-color-display>
+<snice-color-display value="#00ff00"></snice-color-display>
+<snice-color-display value="#0000ff"></snice-color-display>
+```
+
+### Color Formats
+
+```html
+<snice-color-display value="#3b82f6" format="hex"></snice-color-display>
+<snice-color-display value="#3b82f6" format="rgb"></snice-color-display>
+<snice-color-display value="#3b82f6" format="hsl"></snice-color-display>
+```
+
+### Swatch Sizes
+
+```html
+<snice-color-display value="#10b981" swatch-size="small"></snice-color-display>
+<snice-color-display value="#10b981" swatch-size="medium"></snice-color-display>
+<snice-color-display value="#10b981" swatch-size="large"></snice-color-display>
+```
+
+### Custom Labels
+
+```html
+<snice-color-display value="#ef4444" label="Error Red"></snice-color-display>
+<snice-color-display value="#10b981" label="Success Green"></snice-color-display>
+```
+
+### Swatch Only
+
+```html
+<snice-color-display
+  value="#3b82f6"
+  show-label="false"
+  swatch-size="large"
+></snice-color-display>
+```
+
+### Label Only
+
+```html
+<snice-color-display
+  value="#3b82f6"
+  show-swatch="false"
+  format="rgb"
+></snice-color-display>
+```
+
+## Styling
+
+```css
+snice-color-display::part(container) {
+  /* Container */
+}
+
+snice-color-display::part(swatch) {
+  /* Color swatch */
+}
+
+snice-color-display::part(label) {
+  /* Color label */
+}
+```
+
+## Notes
+
+- Colors must be provided in hex format (#RRGGBB)
+- The component automatically converts to RGB and HSL formats
+- When no custom label is provided, the formatted color value is used
+- Swatch and label can be shown/hidden independently

package/docs/components/color-picker.md

@@ -0,0 +1,81 @@
+# Color Picker Component
+
+The `<snice-color-picker>` component provides a color selection interface with format conversion and preset colors.
+
+## Basic Usage
+
+```html
+<snice-color-picker
+  label="Brand Color"
+  value="#3b82f6"
+  show-presets
+></snice-color-picker>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `value` | `string` | `'#000000'` | Current color value |
+| `format` | `'hex' \| 'rgb' \| 'hsl'` | `'hex'` | Display format |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Size variant |
+| `label` | `string` | `''` | Label text |
+| `helperText` | `string` | `''` | Helper text |
+| `errorText` | `string` | `''` | Error message |
+| `disabled` | `boolean` | `false` | Disabled state |
+| `required` | `boolean` | `false` | Required state |
+| `invalid` | `boolean` | `false` | Invalid state |
+| `name` | `string` | `''` | Form field name |
+| `showInput` | `boolean` | `true` | Show text input |
+| `showPresets` | `boolean` | `false` | Show preset colors |
+| `presets` | `string[]` | `[...]` | Preset color values |
+
+## Methods
+
+### `focus(): void`
+Focus the color picker.
+
+### `blur(): void`
+Blur the color picker.
+
+## Events
+
+### `@snice/color-picker-change`
+Fired when color changes.
+
+**Detail**: `{ value: string, colorPicker: SniceColorPickerElement }`
+
+## Examples
+
+### Basic
+
+```html
+<snice-color-picker label="Background Color"></snice-color-picker>
+```
+
+### With Presets
+
+```html
+<snice-color-picker
+  label="Theme Color"
+  show-presets
+></snice-color-picker>
+```
+
+### Different Formats
+
+```html
+<snice-color-picker format="hex" label="Hex"></snice-color-picker>
+<snice-color-picker format="rgb" label="RGB"></snice-color-picker>
+<snice-color-picker format="hsl" label="HSL"></snice-color-picker>
+```
+
+### Custom Presets
+
+```html
+<snice-color-picker
+  label="Brand Colors"
+  show-presets
+  presets='["#ff0000", "#00ff00", "#0000ff"]'
+></snice-color-picker>
+```