snice 2.5.4 → 3.2.0

package/docs/components/slider.md

@@ -0,0 +1,297 @@
+# Slider Component
+
+The `<snice-slider>` component provides an interactive range slider for selecting numeric values with mouse, touch, and keyboard support.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [Keyboard Navigation](#keyboard-navigation)
+- [Features](#features)
+- [Examples](#examples)
+
+## Basic Usage
+
+```html
+<snice-slider
+  label="Volume"
+  min="0"
+  max="100"
+  value="50"
+  show-value
+></snice-slider>
+```
+
+```typescript
+import 'snice/components/slider/snice-slider';
+
+const slider = document.querySelector('snice-slider');
+slider.addEventListener('@snice/slider-change', (e) => {
+  console.log('Value:', e.detail.value);
+});
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `value` | `number` | `0` | Current slider value |
+| `min` | `number` | `0` | Minimum value |
+| `max` | `number` | `100` | Maximum value |
+| `step` | `number` | `1` | Step increment |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Size variant |
+| `variant` | `'default' \| 'primary' \| 'success' \| 'warning' \| 'danger'` | `'default'` | Color variant |
+| `label` | `string` | `''` | Label text |
+| `helperText` | `string` | `''` | Helper text below slider |
+| `errorText` | `string` | `''` | Error message (shown when invalid) |
+| `disabled` | `boolean` | `false` | Whether slider is disabled |
+| `readonly` | `boolean` | `false` | Whether slider is readonly |
+| `required` | `boolean` | `false` | Whether slider is required |
+| `invalid` | `boolean` | `false` | Whether to show invalid state |
+| `name` | `string` | `''` | Form field name |
+| `showValue` | `boolean` | `false` | Display current value |
+| `showTicks` | `boolean` | `false` | Show tick marks |
+| `vertical` | `boolean` | `false` | Vertical orientation |
+
+## Methods
+
+### `focus(): void`
+Give focus to the slider thumb.
+
+```typescript
+slider.focus();
+```
+
+### `blur(): void`
+Remove focus from the slider thumb.
+
+```typescript
+slider.blur();
+```
+
+### `checkValidity(): boolean`
+Check if the slider passes validation.
+
+```typescript
+const isValid = slider.checkValidity();
+```
+
+### `reportValidity(): boolean`
+Report validation status to the user.
+
+```typescript
+slider.reportValidity();
+```
+
+### `setCustomValidity(message: string): void`
+Set a custom validation message.
+
+```typescript
+slider.setCustomValidity('Value must be between 10 and 90');
+```
+
+## Events
+
+### `@snice/slider-input`
+Fired continuously while dragging the slider.
+
+**Detail**: `{ value: number, slider: SniceSliderElement }`
+
+```typescript
+slider.addEventListener('@snice/slider-input', (e) => {
+  console.log('Current value:', e.detail.value);
+});
+```
+
+### `@snice/slider-change`
+Fired when the slider value is committed (after drag ends or keyboard input).
+
+**Detail**: `{ value: number, slider: SniceSliderElement }`
+
+```typescript
+slider.addEventListener('@snice/slider-change', (e) => {
+  console.log('Final value:', e.detail.value);
+});
+```
+
+## Keyboard Navigation
+
+The slider supports full keyboard navigation:
+
+| Key | Action |
+|-----|--------|
+| `←` / `↓` | Decrease by step |
+| `→` / `↑` | Increase by step |
+| `Home` | Jump to minimum |
+| `End` | Jump to maximum |
+| `Page Down` | Decrease by 10× step |
+| `Page Up` | Increase by 10× step |
+
+## Features
+
+- **Input Devices**: Full mouse, touch, and keyboard support
+- **Form Integration**: Form-associated custom element with validation
+- **Visual Variants**: Five color options (default, primary, success, warning, danger)
+- **Orientations**: Horizontal (default) or vertical layout
+- **Value Display**: Optional current value indicator
+- **Tick Marks**: Optional visual step indicators
+- **Step Control**: Configure increment size
+- **Accessibility**: Full ARIA support with keyboard navigation
+
+## Examples
+
+### Basic Slider
+
+```html
+<snice-slider
+  label="Volume"
+  min="0"
+  max="100"
+  value="50"
+></snice-slider>
+```
+
+### With Value Display
+
+```html
+<snice-slider
+  label="Brightness"
+  min="0"
+  max="100"
+  value="75"
+  show-value
+></snice-slider>
+```
+
+### With Tick Marks
+
+```html
+<snice-slider
+  label="Rating"
+  min="0"
+  max="10"
+  step="1"
+  show-ticks
+  show-value
+></snice-slider>
+```
+
+### Different Variants
+
+```html
+<snice-slider variant="default" label="Default"></snice-slider>
+<snice-slider variant="primary" label="Primary"></snice-slider>
+<snice-slider variant="success" label="Success"></snice-slider>
+<snice-slider variant="warning" label="Warning"></snice-slider>
+<snice-slider variant="danger" label="Danger"></snice-slider>
+```
+
+### Different Sizes
+
+```html
+<snice-slider size="small" label="Small"></snice-slider>
+<snice-slider size="medium" label="Medium"></snice-slider>
+<snice-slider size="large" label="Large"></snice-slider>
+```
+
+### Custom Range and Step
+
+```html
+<!-- Temperature: 60-80°F in 0.5° increments -->
+<snice-slider
+  label="Temperature"
+  min="60"
+  max="80"
+  step="0.5"
+  value="72"
+  show-value
+></snice-slider>
+
+<!-- Percentage: 0-100 in 5% increments -->
+<snice-slider
+  label="Discount"
+  min="0"
+  max="100"
+  step="5"
+  value="20"
+  show-value
+  show-ticks
+></snice-slider>
+```
+
+### Vertical Slider
+
+```html
+<snice-slider
+  label="Volume"
+  min="0"
+  max="100"
+  value="60"
+  vertical
+  show-value
+></snice-slider>
+```
+
+### Error State
+
+```html
+<snice-slider
+  label="Age"
+  min="0"
+  max="120"
+  value="150"
+  invalid
+  error-text="Value must be between 0 and 120"
+></snice-slider>
+```
+
+### In a Form
+
+```html
+<form id="settings-form">
+  <snice-slider
+    name="volume"
+    label="Volume"
+    min="0"
+    max="100"
+    value="50"
+    required
+  ></snice-slider>
+
+  <snice-slider
+    name="brightness"
+    label="Brightness"
+    min="0"
+    max="100"
+    value="75"
+  ></snice-slider>
+
+  <button type="submit">Save Settings</button>
+</form>
+
+<script>
+document.getElementById('settings-form').addEventListener('submit', (e) => {
+  e.preventDefault();
+  const formData = new FormData(e.target);
+  console.log('Volume:', formData.get('volume'));
+  console.log('Brightness:', formData.get('brightness'));
+});
+</script>
+```
+
+### Real-time Value Display
+
+```html
+<snice-slider id="volume-slider" min="0" max="100" value="50"></snice-slider>
+<div id="volume-display">Volume: 50</div>
+
+<script>
+const slider = document.getElementById('volume-slider');
+const display = document.getElementById('volume-display');
+
+slider.addEventListener('@snice/slider-input', (e) => {
+  display.textContent = `Volume: ${e.detail.value}`;
+});
+</script>
+```

package/docs/components/sparkline.md

@@ -0,0 +1,293 @@
+# Sparkline Component
+
+A lightweight inline chart component for visualizing trends and patterns in compact spaces. Perfect for dashboards, tables, and data-dense interfaces.
+
+## Features
+
+- **Multiple Chart Types**: line, bar, area
+- **Semantic Colors**: primary, success, warning, danger, muted
+- **Custom Colors**: Use any color with the `custom-color` attribute
+- **Smooth Curves**: Optional smooth bezier curve interpolation
+- **Customizable Size**: Configurable width and height
+- **Optional Enhancements**: Dots, area fill, custom stroke width
+- **Flexible Data Range**: Optional min/max values for scaling
+
+## Basic Usage
+
+```html
+<snice-sparkline id="chart"></snice-sparkline>
+
+<script>
+  document.getElementById('chart').data = [10, 20, 15, 25, 30];
+</script>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `data` | `number[]` | `[]` | Array of numeric values to visualize |
+| `type` | `SparklineType` | `'line'` | Chart type ('line', 'bar', 'area') |
+| `color` | `SparklineColor` | `'primary'` | Color variant ('primary', 'success', 'warning', 'danger', 'muted') |
+| `custom-color` | `string` | `undefined` | Custom color (overrides `color`) - any valid CSS 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 instead of sharp lines |
+| `min` | `number` | `undefined` | Minimum value for scaling (auto if not set) |
+| `max` | `number` | `undefined` | Maximum value for scaling (auto if not set) |
+
+## Chart Types
+
+### Line Chart
+```html
+<snice-sparkline type="line"></snice-sparkline>
+```
+
+### Bar Chart
+```html
+<snice-sparkline type="bar"></snice-sparkline>
+```
+
+### Area Chart
+```html
+<snice-sparkline type="area"></snice-sparkline>
+```
+
+## Colors
+
+### Primary
+```html
+<snice-sparkline color="primary"></snice-sparkline>
+```
+
+### Success
+```html
+<snice-sparkline color="success"></snice-sparkline>
+```
+
+### Warning
+```html
+<snice-sparkline color="warning"></snice-sparkline>
+```
+
+### Danger
+```html
+<snice-sparkline color="danger"></snice-sparkline>
+```
+
+### Muted
+```html
+<snice-sparkline color="muted"></snice-sparkline>
+```
+
+## Customization
+
+### With Dots
+```html
+<snice-sparkline show-dots></snice-sparkline>
+```
+
+### With Area Fill
+```html
+<snice-sparkline show-area></snice-sparkline>
+```
+
+### Custom Size
+```html
+<snice-sparkline width="200" height="50"></snice-sparkline>
+```
+
+### Thick Stroke
+```html
+<snice-sparkline stroke-width="3"></snice-sparkline>
+```
+
+### Custom Scale
+```html
+<snice-sparkline min="0" max="100"></snice-sparkline>
+```
+
+### Smooth Curves
+```html
+<snice-sparkline smooth></snice-sparkline>
+```
+
+### Custom Colors
+```html
+<!-- Hex color -->
+<snice-sparkline custom-color="#9333ea"></snice-sparkline>
+
+<!-- RGB color -->
+<snice-sparkline custom-color="rgb(147, 51, 234)"></snice-sparkline>
+
+<!-- Any valid CSS color -->
+<snice-sparkline custom-color="hsl(270, 80%, 60%)"></snice-sparkline>
+```
+
+## CSS Parts
+
+Use `::part()` to style internal elements:
+
+```css
+snice-sparkline::part(container) {
+  padding: 4px;
+}
+
+snice-sparkline::part(svg) {
+  filter: drop-shadow(0 2px 4px rgba(0,0,0,0.1));
+}
+
+snice-sparkline::part(line) {
+  stroke-dasharray: 4;
+}
+
+snice-sparkline::part(bar) {
+  rx: 2;
+}
+
+snice-sparkline::part(area) {
+  opacity: 0.3;
+}
+
+snice-sparkline::part(dot) {
+  fill: white;
+}
+```
+
+## Theming
+
+The component uses these CSS custom properties:
+
+```css
+--snice-color-primary
+--snice-color-success
+--snice-color-warning
+--snice-color-danger
+--snice-color-text-secondary
+```
+
+## Examples
+
+### Website Traffic Trend
+```html
+<div>
+  <label>Daily Visitors</label>
+  <snice-sparkline
+    id="traffic"
+    color="primary"
+    width="150"
+    height="40"
+    show-area>
+  </snice-sparkline>
+</div>
+
+<script>
+  document.getElementById('traffic').data = [
+    1200, 1350, 1100, 1450, 1600, 1550, 1700,
+    1800, 1650, 1900, 2100, 2000, 2200, 2400
+  ];
+</script>
+```
+
+### Sales Performance
+```html
+<div>
+  <label>Weekly Sales</label>
+  <snice-sparkline
+    id="sales"
+    type="bar"
+    color="success"
+    width="150"
+    height="40">
+  </snice-sparkline>
+</div>
+
+<script>
+  document.getElementById('sales').data = [45, 52, 48, 61, 55, 70, 68];
+</script>
+```
+
+### Server Response Time
+```html
+<div>
+  <label>Response Time (ms)</label>
+  <snice-sparkline
+    id="response"
+    color="warning"
+    width="150"
+    height="40"
+    show-dots>
+  </snice-sparkline>
+</div>
+
+<script>
+  document.getElementById('response').data = [
+    120, 135, 115, 145, 160, 155, 140, 130, 125, 120
+  ];
+</script>
+```
+
+### Error Rate
+```html
+<div>
+  <label>Error Rate</label>
+  <snice-sparkline
+    id="errors"
+    type="area"
+    color="danger"
+    width="150"
+    height="40"
+    min="0">
+  </snice-sparkline>
+</div>
+
+<script>
+  document.getElementById('errors').data = [
+    5, 3, 7, 12, 8, 15, 25, 20, 18, 22, 15, 10, 5, 3, 1, 0
+  ];
+</script>
+```
+
+### In Table Cells
+```html
+<table>
+  <tr>
+    <td>Product A</td>
+    <td><snice-sparkline id="product-a" width="80" height="25"></snice-sparkline></td>
+  </tr>
+  <tr>
+    <td>Product B</td>
+    <td><snice-sparkline id="product-b" width="80" height="25"></snice-sparkline></td>
+  </tr>
+</table>
+
+<script>
+  document.getElementById('product-a').data = [10, 12, 15, 14, 18, 22, 25];
+  document.getElementById('product-b').data = [30, 28, 25, 27, 24, 22, 20];
+</script>
+```
+
+## Best Practices
+
+1. **Keep it Simple**: Sparklines are meant to show trends, not detailed analysis
+2. **Consistent Sizing**: Use the same dimensions for sparklines in a group
+3. **Appropriate Scale**: Set `min`/`max` when comparing multiple charts
+4. **Semantic Colors**: Use colors that match the data meaning (success=good, danger=bad)
+5. **Add Context**: Always label sparklines so users understand what they represent
+
+## Accessibility
+
+- Sparklines are decorative visualizations
+- Always provide text labels or tooltips for the data
+- Consider adding `aria-label` to describe the trend
+- Ensure sufficient color contrast for visibility
+
+## Performance
+
+- Lightweight SVG rendering
+- No external dependencies
+- Efficiently handles data updates
+- Suitable for rendering many sparklines simultaneously

package/docs/components/spinner.md

@@ -0,0 +1,63 @@
+# Spinner Component
+
+The `<snice-spinner>` component provides an animated loading indicator.
+
+## Basic Usage
+
+```html
+<snice-spinner></snice-spinner>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `size` | `'small' \| 'medium' \| 'large' \| 'xl'` | `'medium'` | Spinner size |
+| `color` | `'primary' \| 'success' \| 'warning' \| 'error' \| 'info'` | `'primary'` | Color variant |
+| `label` | `string` | `''` | Accessible label |
+| `thickness` | `number` | `4` | Stroke thickness |
+
+## Examples
+
+### Sizes
+
+```html
+<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
+
+```html
+<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
+
+```html
+<snice-spinner label="Loading data..."></snice-spinner>
+```
+
+### Loading State
+
+```html
+<div style="text-align: center; padding: 2rem;">
+  <snice-spinner size="large" color="primary"></snice-spinner>
+  <p>Loading content...</p>
+</div>
+```
+
+### Inline Spinner
+
+```html
+<button disabled>
+  <snice-spinner size="small"></snice-spinner>
+  Processing...
+</button>
+```