snice 3.1.0 → 3.2.0

package/docs/components/stepper.md

@@ -0,0 +1,410 @@
+# Stepper Component
+
+A step indicator component for visualizing multi-step processes, wizards, and workflows. Shows progress through a sequence of steps with clear visual states.
+
+## Features
+
+- **Multiple Orientations**: Horizontal and vertical layouts
+- **Status Indicators**: Pending, active, completed, and error states
+- **Interactive Mode**: Optional clickable navigation
+- **Step Descriptions**: Optional descriptive text for each step
+- **Custom Events**: Step change events for navigation integration
+- **Connector Lines**: Visual flow between steps
+- **Flexible Status**: Auto-computed or manually specified step status
+
+## Basic Usage
+
+```html
+<snice-stepper id="basic"></snice-stepper>
+
+<script>
+  const stepper = document.getElementById('basic');
+  stepper.steps = [
+    { label: 'Step 1' },
+    { label: 'Step 2' },
+    { label: 'Step 3' }
+  ];
+  stepper.currentStep = 0;
+</script>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `steps` | `Step[]` | `[]` | Array of step objects |
+| `current-step` | `number` | `0` | Index of the currently active step |
+| `orientation` | `StepperOrientation` | `'horizontal'` | Layout direction ('horizontal' or 'vertical') |
+| `clickable` | `boolean` | `false` | Whether steps can be clicked for navigation |
+
+### Step Object
+
+```typescript
+{
+  label: string;          // Step label (required)
+  description?: string;   // Optional description text
+  status?: StepStatus;    // Override auto-computed status
+}
+```
+
+### Step Status
+
+- `'pending'` - Not yet reached
+- `'active'` - Current step
+- `'completed'` - Already completed
+- `'error'` - Failed or requires attention
+
+## Horizontal Stepper
+
+```html
+<snice-stepper id="checkout"></snice-stepper>
+
+<script>
+  document.getElementById('checkout').steps = [
+    { label: 'Cart' },
+    { label: 'Delivery' },
+    { label: 'Payment' },
+    { label: 'Confirm' }
+  ];
+  document.getElementById('checkout').currentStep = 1;
+</script>
+```
+
+## Vertical Stepper
+
+```html
+<snice-stepper id="onboarding" orientation="vertical"></snice-stepper>
+
+<script>
+  document.getElementById('onboarding').steps = [
+    { label: 'Create Account' },
+    { label: 'Profile Setup' },
+    { label: 'Preferences' },
+    { label: 'Complete' }
+  ];
+  document.getElementById('onboarding').currentStep = 2;
+</script>
+```
+
+## With Descriptions
+
+```html
+<snice-stepper id="detailed"></snice-stepper>
+
+<script>
+  document.getElementById('detailed').steps = [
+    { label: 'Order Details', description: 'Review your items' },
+    { label: 'Shipping', description: 'Enter delivery address' },
+    { label: 'Payment', description: 'Secure checkout' },
+    { label: 'Confirmation', description: 'Order summary' }
+  ];
+  document.getElementById('detailed').currentStep = 1;
+</script>
+```
+
+## Interactive Navigation
+
+```html
+<snice-stepper id="wizard" clickable></snice-stepper>
+
+<script>
+  const wizard = document.getElementById('wizard');
+  wizard.steps = [
+    { label: 'Step 1' },
+    { label: 'Step 2' },
+    { label: 'Step 3' }
+  ];
+
+  wizard.addEventListener('step-change', (e) => {
+    console.log('Previous:', e.detail.previousStep);
+    console.log('Current:', e.detail.currentStep);
+    console.log('Step:', e.detail.step);
+
+    // Prevent navigation if needed
+    // e.preventDefault();
+  });
+</script>
+```
+
+## Error State
+
+```html
+<snice-stepper id="validation"></snice-stepper>
+
+<script>
+  document.getElementById('validation').steps = [
+    { label: 'Upload', status: 'completed' },
+    { label: 'Validate', status: 'error' },
+    { label: 'Process', status: 'pending' },
+    { label: 'Complete', status: 'pending' }
+  ];
+  document.getElementById('validation').currentStep = 1;
+</script>
+```
+
+## Events
+
+### step-change
+
+Emitted when a step is clicked (only in clickable mode).
+
+```javascript
+stepper.addEventListener('step-change', (event) => {
+  const { previousStep, currentStep, step } = event.detail;
+
+  // Validate before allowing change
+  if (!isStepValid(previousStep)) {
+    event.preventDefault();
+    return;
+  }
+
+  // Handle navigation
+  loadStepContent(currentStep);
+});
+```
+
+## Stepper Panels
+
+Use `<snice-stepper-panel>` to create content that automatically shows/hides based on the active step:
+
+```html
+<snice-stepper id="wizard" clickable></snice-stepper>
+
+<snice-stepper-panel>
+  <h3>Step 1 Content</h3>
+  <p>This shows when step 0 is active</p>
+</snice-stepper-panel>
+
+<snice-stepper-panel>
+  <h3>Step 2 Content</h3>
+  <p>This shows when step 1 is active</p>
+</snice-stepper-panel>
+
+<snice-stepper-panel>
+  <h3>Step 3 Content</h3>
+  <p>This shows when step 2 is active</p>
+</snice-stepper-panel>
+
+<script>
+  document.getElementById('wizard').steps = [
+    { label: 'Account' },
+    { label: 'Profile' },
+    { label: 'Complete' }
+  ];
+</script>
+```
+
+Panels automatically sync with the stepper's `currentStep`. They must be direct children of the stepper element.
+
+## Programmatic Navigation
+
+```javascript
+const stepper = document.getElementById('my-stepper');
+
+// Go to next step
+if (stepper.currentStep < stepper.steps.length - 1) {
+  stepper.currentStep++;
+}
+
+// Go to previous step
+if (stepper.currentStep > 0) {
+  stepper.currentStep--;
+}
+
+// Go to specific step
+stepper.currentStep = 2;
+
+// Reset to first step
+stepper.currentStep = 0;
+```
+
+## CSS Parts
+
+Use `::part()` to style internal elements:
+
+```css
+snice-stepper::part(container) {
+  padding: 20px;
+}
+
+snice-stepper::part(step) {
+  margin: 10px 0;
+}
+
+snice-stepper::part(step-indicator) {
+  width: 40px;
+  height: 40px;
+  font-size: 18px;
+}
+
+snice-stepper::part(step-label) {
+  font-weight: 600;
+}
+
+snice-stepper::part(step-description) {
+  font-size: 12px;
+}
+
+snice-stepper::part(step-connector) {
+  background: linear-gradient(to right, #ccc, #999);
+}
+```
+
+## Theming
+
+The component uses these CSS custom properties:
+
+```css
+--snice-color-primary
+--snice-color-success
+--snice-color-danger
+--snice-color-text
+--snice-color-text-secondary
+--snice-color-text-inverse
+--snice-color-background
+--snice-color-border
+--snice-spacing-*
+--snice-font-size-*
+--snice-font-weight-*
+--snice-transition-fast
+```
+
+## Examples
+
+### Checkout Process
+
+```html
+<snice-stepper id="checkout-process" clickable></snice-stepper>
+
+<div id="step-content"></div>
+
+<button onclick="prevStep()">Previous</button>
+<button onclick="nextStep()">Next</button>
+
+<script>
+  const stepper = document.getElementById('checkout-process');
+  stepper.steps = [
+    { label: 'Cart', description: 'Review items' },
+    { label: 'Delivery', description: 'Shipping details' },
+    { label: 'Payment', description: 'Billing info' },
+    { label: 'Confirm', description: 'Place order' }
+  ];
+
+  function nextStep() {
+    if (stepper.currentStep < stepper.steps.length - 1) {
+      stepper.currentStep++;
+    }
+  }
+
+  function prevStep() {
+    if (stepper.currentStep > 0) {
+      stepper.currentStep--;
+    }
+  }
+
+  stepper.addEventListener('step-change', (e) => {
+    document.getElementById('step-content').innerHTML =
+      `<h2>${e.detail.step.label}</h2>`;
+  });
+</script>
+```
+
+### Account Setup Wizard with Panels
+
+```html
+<snice-stepper id="signup" clickable></snice-stepper>
+
+<snice-stepper-panel>
+  <h2>Create Account</h2>
+  <input type="email" placeholder="Email">
+  <input type="password" placeholder="Password">
+</snice-stepper-panel>
+
+<snice-stepper-panel>
+  <h2>Personal Information</h2>
+  <input type="text" placeholder="Full Name">
+  <input type="text" placeholder="Company">
+</snice-stepper-panel>
+
+<snice-stepper-panel>
+  <h2>Preferences</h2>
+  <label><input type="checkbox"> Email notifications</label>
+  <label><input type="checkbox"> Weekly digest</label>
+</snice-stepper-panel>
+
+<snice-stepper-panel>
+  <h2>Complete</h2>
+  <p>You're all set! Click finish to start using the app.</p>
+  <button>Finish</button>
+</snice-stepper-panel>
+
+<script>
+  const signup = document.getElementById('signup');
+  signup.steps = [
+    { label: 'Account' },
+    { label: 'Profile' },
+    { label: 'Preferences' },
+    { label: 'Complete' }
+  ];
+</script>
+```
+
+### Form Validation Flow
+
+```html
+<snice-stepper id="form-validation"></snice-stepper>
+
+<script>
+  const form = document.getElementById('form-validation');
+  const validationStates = {
+    0: true,  // Step 1 valid
+    1: false, // Step 2 has error
+    2: false, // Step 3 pending
+  };
+
+  function updateStepStatuses() {
+    form.steps = form.steps.map((step, index) => ({
+      ...step,
+      status: validationStates[index]
+        ? (index < form.currentStep ? 'completed' : index === form.currentStep ? 'active' : 'pending')
+        : 'error'
+    }));
+  }
+
+  form.steps = [
+    { label: 'Personal Info' },
+    { label: 'Contact Details' },
+    { label: 'Verification' }
+  ];
+
+  updateStepStatuses();
+</script>
+```
+
+## Best Practices
+
+1. **Clear Labels**: Use concise, action-oriented step names
+2. **Logical Flow**: Order steps in natural progression
+3. **Visual Feedback**: Show clear status for each step
+4. **Error Handling**: Highlight steps that need attention
+5. **Save Progress**: Persist current step across sessions
+6. **Validation**: Validate before allowing step advancement
+7. **Orientation**: Use vertical for complex flows with descriptions
+8. **Descriptions**: Add descriptions for clarity in complex workflows
+
+## Accessibility
+
+- Semantic HTML with proper step indicators
+- Clear visual state differentiation
+- Keyboard navigation in clickable mode
+- Screen reader friendly labels and status
+- Sufficient color contrast for all states
+- Focus indicators on interactive steps
+
+## Performance
+
+- Efficient rendering with minimal DOM
+- CSS containment for optimized layout
+- Event delegation for click handling
+- No external dependencies
+- Lightweight status computation

package/docs/components/textarea.md

@@ -0,0 +1,235 @@
+# Textarea Component
+
+The `<snice-textarea>` component provides a multi-line text input with validation, character counting, and optional auto-grow functionality.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [Features](#features)
+- [Examples](#examples)
+
+## Basic Usage
+
+```html
+<snice-textarea
+  label="Comments"
+  placeholder="Enter your comments here"
+  rows="5"
+></snice-textarea>
+```
+
+```typescript
+import 'snice/components/textarea/snice-textarea';
+
+const textarea = document.querySelector('snice-textarea');
+textarea.addEventListener('@snice/textarea-change', (e) => {
+  console.log('Value:', e.detail.value);
+});
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `value` | `string` | `''` | The textarea value |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Size variant |
+| `variant` | `'outlined' \| 'filled' \| 'underlined'` | `'outlined'` | Visual style variant |
+| `resize` | `'none' \| 'vertical' \| 'horizontal' \| 'both'` | `'vertical'` | Resize behavior |
+| `placeholder` | `string` | `''` | Placeholder text |
+| `label` | `string` | `''` | Label text |
+| `helperText` | `string` | `''` | Helper text below textarea |
+| `errorText` | `string` | `''` | Error message (shown when invalid) |
+| `disabled` | `boolean` | `false` | Whether textarea is disabled |
+| `readonly` | `boolean` | `false` | Whether textarea is readonly |
+| `required` | `boolean` | `false` | Whether textarea is required |
+| `invalid` | `boolean` | `false` | Whether to show invalid state |
+| `rows` | `number` | `3` | Number of visible rows |
+| `cols` | `number` | `-1` | Number of visible columns |
+| `maxlength` | `number` | `-1` | Maximum character count |
+| `minlength` | `number` | `-1` | Minimum character count |
+| `autocomplete` | `string` | `''` | Autocomplete attribute value |
+| `name` | `string` | `''` | Form field name |
+| `autoGrow` | `boolean` | `false` | Whether to auto-grow height |
+
+## Methods
+
+### `focus(): void`
+Give focus to the textarea.
+
+```typescript
+textarea.focus();
+```
+
+### `blur(): void`
+Remove focus from the textarea.
+
+```typescript
+textarea.blur();
+```
+
+### `select(): void`
+Select all text in the textarea.
+
+```typescript
+textarea.select();
+```
+
+### `checkValidity(): boolean`
+Check if the textarea passes validation.
+
+```typescript
+const isValid = textarea.checkValidity();
+```
+
+### `reportValidity(): boolean`
+Report validation status to the user.
+
+```typescript
+textarea.reportValidity();
+```
+
+### `setCustomValidity(message: string): void`
+Set a custom validation message.
+
+```typescript
+textarea.setCustomValidity('This field is required');
+```
+
+## Events
+
+### `@snice/textarea-input`
+Fired when the textarea value changes during input.
+
+**Detail**: `{ value: string, textarea: SniceTextareaElement }`
+
+```typescript
+textarea.addEventListener('@snice/textarea-input', (e) => {
+  console.log('Input value:', e.detail.value);
+});
+```
+
+### `@snice/textarea-change`
+Fired when the textarea value is committed (blur or enter).
+
+**Detail**: `{ value: string, textarea: SniceTextareaElement }`
+
+```typescript
+textarea.addEventListener('@snice/textarea-change', (e) => {
+  console.log('Changed to:', e.detail.value);
+});
+```
+
+### `@snice/textarea-focus`
+Fired when the textarea receives focus.
+
+**Detail**: `{ textarea: SniceTextareaElement }`
+
+### `@snice/textarea-blur`
+Fired when the textarea loses focus.
+
+**Detail**: `{ textarea: SniceTextareaElement }`
+
+## Features
+
+- **Form Integration**: Fully form-associated custom element with validation support
+- **Visual Variants**: Three style options (outlined, filled, underlined)
+- **Auto-grow**: Automatically expand height to fit content
+- **Character Counter**: Shows count when maxlength is set
+- **Resize Control**: Four resize modes (none, vertical, horizontal, both)
+- **Validation**: Built-in HTML5 validation with custom messages
+- **Accessibility**: Full keyboard support and ARIA attributes
+
+## Examples
+
+### Basic Textarea
+
+```html
+<snice-textarea
+  label="Description"
+  placeholder="Enter description..."
+  rows="4"
+></snice-textarea>
+```
+
+### With Character Counter
+
+```html
+<snice-textarea
+  label="Bio"
+  maxlength="500"
+  helper-text="Share a brief bio"
+></snice-textarea>
+```
+
+### Auto-grow Textarea
+
+```html
+<snice-textarea
+  label="Notes"
+  auto-grow
+  rows="3"
+  placeholder="Type to expand..."
+></snice-textarea>
+```
+
+### Error State
+
+```html
+<snice-textarea
+  label="Message"
+  invalid
+  error-text="This field is required"
+  required
+></snice-textarea>
+```
+
+### Different Variants
+
+```html
+<snice-textarea variant="outlined" label="Outlined"></snice-textarea>
+<snice-textarea variant="filled" label="Filled"></snice-textarea>
+<snice-textarea variant="underlined" label="Underlined"></snice-textarea>
+```
+
+### Different Sizes
+
+```html
+<snice-textarea size="small" label="Small"></snice-textarea>
+<snice-textarea size="medium" label="Medium"></snice-textarea>
+<snice-textarea size="large" label="Large"></snice-textarea>
+```
+
+### Resize Control
+
+```html
+<snice-textarea resize="none" label="No resize"></snice-textarea>
+<snice-textarea resize="vertical" label="Vertical only"></snice-textarea>
+<snice-textarea resize="horizontal" label="Horizontal only"></snice-textarea>
+<snice-textarea resize="both" label="Both directions"></snice-textarea>
+```
+
+### In a Form
+
+```html
+<form id="feedback-form">
+  <snice-textarea
+    name="feedback"
+    label="Your Feedback"
+    required
+    minlength="10"
+    maxlength="1000"
+    helper-text="Please provide at least 10 characters"
+  ></snice-textarea>
+  <button type="submit">Submit</button>
+</form>
+
+<script>
+document.getElementById('feedback-form').addEventListener('submit', (e) => {
+  e.preventDefault();
+  const formData = new FormData(e.target);
+  console.log('Feedback:', formData.get('feedback'));
+});
+</script>
+```