snice 3.1.0 → 3.2.0

package/docs/components/empty-state.md

@@ -0,0 +1,79 @@
+# Empty State Component
+
+The `<snice-empty-state>` component provides a consistent way to display empty or no-data states.
+
+## Basic Usage
+
+```html
+<snice-empty-state
+  icon="📭"
+  title="No data"
+  description="There's nothing here yet"
+></snice-empty-state>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Size variant |
+| `icon` | `string` | `'📭'` | Icon (emoji or text) |
+| `title` | `string` | `'No data'` | Title text |
+| `description` | `string` | `''` | Description text |
+| `actionText` | `string` | `''` | Action button text |
+| `actionHref` | `string` | `''` | Action link URL |
+
+## Events
+
+### `@snice/empty-state-action`
+Fired when action button/link is clicked.
+
+## Examples
+
+### No Search Results
+
+```html
+<snice-empty-state
+  icon="🔍"
+  title="No results found"
+  description="Try adjusting your search criteria"
+  action-text="Clear Search"
+></snice-empty-state>
+```
+
+### Empty List
+
+```html
+<snice-empty-state
+  icon="📦"
+  title="No items yet"
+  description="Get started by creating your first item"
+  action-text="Create Item"
+></snice-empty-state>
+```
+
+### 404 Page
+
+```html
+<snice-empty-state
+  icon="🤷"
+  title="Page not found"
+  description="The page you're looking for doesn't exist"
+  action-text="Go Home"
+  action-href="/"
+></snice-empty-state>
+```
+
+### With Custom Content
+
+```html
+<snice-empty-state
+  icon="🎨"
+  title="No projects"
+>
+  <div slot="">
+    <button>Create Project</button>
+    <button>Import Project</button>
+  </div>
+</snice-empty-state>
+```

package/docs/components/file-upload.md

@@ -0,0 +1,263 @@
+# File Upload Component
+
+The `<snice-file-upload>` component provides a file upload interface with drag-and-drop support, file previews, and validation.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [Features](#features)
+- [Examples](#examples)
+
+## Basic Usage
+
+```html
+<snice-file-upload
+  label="Upload Documents"
+  accept=".pdf,.doc,.docx"
+  max-size="5242880"
+></snice-file-upload>
+```
+
+```typescript
+import 'snice/components/file-upload/snice-file-upload';
+
+const upload = document.querySelector('snice-file-upload');
+upload.addEventListener('@snice/file-upload-change', (e) => {
+  console.log('Files:', e.detail.files);
+});
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Size variant |
+| `variant` | `'outlined' \| 'filled'` | `'outlined'` | Visual style variant |
+| `accept` | `string` | `''` | Allowed file types (same as input accept) |
+| `multiple` | `boolean` | `false` | Allow multiple file selection |
+| `label` | `string` | `''` | Label text |
+| `helperText` | `string` | `''` | Helper text below upload area |
+| `errorText` | `string` | `''` | Error message (shown when invalid) |
+| `disabled` | `boolean` | `false` | Whether upload is disabled |
+| `required` | `boolean` | `false` | Whether upload is required |
+| `invalid` | `boolean` | `false` | Whether to show invalid state |
+| `maxSize` | `number` | `-1` | Maximum file size in bytes (-1 = no limit) |
+| `maxFiles` | `number` | `-1` | Maximum number of files (-1 = no limit) |
+| `name` | `string` | `''` | Form field name |
+| `dragDrop` | `boolean` | `true` | Enable drag-and-drop |
+| `showPreview` | `boolean` | `true` | Show image previews |
+| `files` | `FileList \| null` | `null` | Selected files (read-only) |
+
+## Methods
+
+### `clear(): void`
+Remove all selected files.
+
+```typescript
+upload.clear();
+```
+
+### `removeFile(index: number): void`
+Remove a specific file by index.
+
+```typescript
+upload.removeFile(0); // Remove first file
+```
+
+## Events
+
+### `@snice/file-upload-change`
+Fired when files are added or removed.
+
+**Detail**: `{ files: File[], fileUpload: SniceFileUploadElement }`
+
+```typescript
+upload.addEventListener('@snice/file-upload-change', (e) => {
+  console.log('Selected files:', e.detail.files);
+  e.detail.files.forEach(file => {
+    console.log(`- ${file.name} (${file.size} bytes)`);
+  });
+});
+```
+
+### `@snice/file-upload-error`
+Fired when file validation fails.
+
+**Detail**: `{ message: string, fileUpload: SniceFileUploadElement }`
+
+```typescript
+upload.addEventListener('@snice/file-upload-error', (e) => {
+  console.error('Upload error:', e.detail.message);
+});
+```
+
+## Features
+
+- **Drag and Drop**: Native drag-and-drop support with visual feedback
+- **Image Preview**: Automatic thumbnail generation for image files
+- **File Validation**: Size and type validation with error messaging
+- **Multiple Files**: Support for single or multiple file selection
+- **File Management**: Add and remove files before upload
+- **Form Integration**: Form-associated custom element
+- **Accessibility**: Full keyboard support and ARIA attributes
+
+## Examples
+
+### Basic Upload
+
+```html
+<snice-file-upload
+  label="Upload File"
+  helper-text="Choose a file to upload"
+></snice-file-upload>
+```
+
+### Image Upload with Preview
+
+```html
+<snice-file-upload
+  label="Upload Image"
+  accept="image/*"
+  max-size="2097152"
+  helper-text="Maximum 2MB, images only"
+></snice-file-upload>
+```
+
+### Multiple Files
+
+```html
+<snice-file-upload
+  label="Upload Documents"
+  accept=".pdf,.doc,.docx"
+  multiple
+  max-files="5"
+  helper-text="Select up to 5 documents"
+></snice-file-upload>
+```
+
+### Without Drag-and-Drop
+
+```html
+<snice-file-upload
+  label="Upload File"
+  drag-drop="false"
+></snice-file-upload>
+```
+
+### Different Sizes
+
+```html
+<snice-file-upload size="small" label="Small"></snice-file-upload>
+<snice-file-upload size="medium" label="Medium"></snice-file-upload>
+<snice-file-upload size="large" label="Large"></snice-file-upload>
+```
+
+### Different Variants
+
+```html
+<snice-file-upload variant="outlined" label="Outlined"></snice-file-upload>
+<snice-file-upload variant="filled" label="Filled"></snice-file-upload>
+```
+
+### Error State
+
+```html
+<snice-file-upload
+  label="Resume"
+  invalid
+  error-text="Please upload your resume"
+  required
+></snice-file-upload>
+```
+
+### File Type Restrictions
+
+```html
+<!-- Images only -->
+<snice-file-upload accept="image/*" label="Images"></snice-file-upload>
+
+<!-- Specific formats -->
+<snice-file-upload accept=".pdf,.doc,.docx" label="Documents"></snice-file-upload>
+
+<!-- Multiple types -->
+<snice-file-upload accept="image/*,.pdf" label="Images and PDFs"></snice-file-upload>
+```
+
+### With Size Validation
+
+```html
+<snice-file-upload
+  label="Upload Photo"
+  accept="image/*"
+  max-size="5242880"
+  helper-text="Maximum 5MB"
+></snice-file-upload>
+
+<script>
+const upload = document.querySelector('snice-file-upload');
+upload.addEventListener('@snice/file-upload-error', (e) => {
+  alert(e.detail.message);
+});
+</script>
+```
+
+### Form Integration
+
+```html
+<form id="upload-form">
+  <snice-file-upload
+    name="documents"
+    label="Upload Documents"
+    accept=".pdf,.doc,.docx"
+    multiple
+    required
+  ></snice-file-upload>
+
+  <button type="submit">Submit</button>
+</form>
+
+<script>
+document.getElementById('upload-form').addEventListener('submit', async (e) => {
+  e.preventDefault();
+
+  const formData = new FormData(e.target);
+  const files = formData.getAll('documents');
+
+  console.log(`Uploading ${files.length} file(s)...`);
+
+  // Upload to server
+  const response = await fetch('/api/upload', {
+    method: 'POST',
+    body: formData
+  });
+
+  console.log('Upload complete!');
+});
+</script>
+```
+
+### Managing Files Programmatically
+
+```html
+<snice-file-upload id="file-upload" multiple></snice-file-upload>
+<button onclick="clearFiles()">Clear All</button>
+<button onclick="removeFirst()">Remove First</button>
+
+<script>
+const upload = document.getElementById('file-upload');
+
+function clearFiles() {
+  upload.clear();
+}
+
+function removeFirst() {
+  upload.removeFile(0);
+}
+
+upload.addEventListener('@snice/file-upload-change', (e) => {
+  console.log(`${e.detail.files.length} file(s) selected`);
+});
+</script>
+```

package/docs/components/image.md

@@ -0,0 +1,110 @@
+# Image Component
+
+The `<snice-image>` component provides a flexible image display with variants, sizes, lazy loading, and fallback support.
+
+## Basic Usage
+
+```html
+<snice-image
+  src="https://example.com/image.jpg"
+  alt="Description"
+></snice-image>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `src` | `string` | `''` | Image source URL |
+| `alt` | `string` | `''` | Alternative text |
+| `fallback` | `string` | `''` | Fallback image URL on error |
+| `variant` | `'rounded' \| 'square' \| 'circle'` | `'rounded'` | Shape variant |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Predefined size |
+| `lazy` | `boolean` | `true` | Enable lazy loading |
+| `fit` | `'cover' \| 'contain' \| 'fill' \| 'none' \| 'scale-down'` | `'cover'` | Object-fit behavior |
+| `width` | `string` | `''` | Custom width (CSS value) |
+| `height` | `string` | `''` | Custom height (CSS value) |
+
+## Examples
+
+### Sizes
+
+```html
+<snice-image src="image.jpg" size="small"></snice-image>
+<snice-image src="image.jpg" size="medium"></snice-image>
+<snice-image src="image.jpg" size="large"></snice-image>
+```
+
+### Shape Variants
+
+```html
+<snice-image src="image.jpg" variant="rounded"></snice-image>
+<snice-image src="image.jpg" variant="square"></snice-image>
+<snice-image src="image.jpg" variant="circle"></snice-image>
+```
+
+### Object Fit
+
+```html
+<snice-image src="image.jpg" fit="cover" width="200px" height="200px"></snice-image>
+<snice-image src="image.jpg" fit="contain" width="200px" height="200px"></snice-image>
+<snice-image src="image.jpg" fit="fill" width="200px" height="200px"></snice-image>
+```
+
+### Custom Dimensions
+
+```html
+<snice-image src="image.jpg" width="300px" height="200px"></snice-image>
+<snice-image src="image.jpg" width="100%" height="auto"></snice-image>
+```
+
+### Fallback Image
+
+```html
+<snice-image
+  src="image.jpg"
+  fallback="placeholder.jpg"
+  alt="Profile picture"
+></snice-image>
+```
+
+### Lazy Loading
+
+```html
+<!-- Lazy loaded (default) -->
+<snice-image src="image.jpg"></snice-image>
+
+<!-- Eager loaded -->
+<snice-image src="image.jpg" lazy="false"></snice-image>
+```
+
+### Placeholder
+
+```html
+<!-- Shows placeholder when no src -->
+<snice-image variant="circle" size="medium"></snice-image>
+```
+
+## Styling
+
+```css
+snice-image::part(container) {
+  /* Image container */
+}
+
+snice-image::part(image) {
+  /* The img element */
+}
+
+snice-image::part(placeholder) {
+  /* Placeholder element */
+}
+```
+
+## Notes
+
+- Images are lazy-loaded by default for better performance
+- Placeholder is shown when `src` is empty
+- Fallback image is used when main image fails to load
+- Size presets provide consistent image dimensions
+- Custom width/height override size presets

package/docs/components/kpi.md

@@ -0,0 +1,251 @@
+# KPI Component
+
+A key performance indicator display component for showing metrics with optional trend visualization and sentiment indicators. Perfect for dashboards and analytics interfaces.
+
+## Features
+
+- **Clear Value Display**: Large, prominent metric value
+- **Trend Indicators**: Optional trend value with sentiment icons
+- **Sparkline Integration**: Built-in sparkline chart support
+- **Sentiment Colors**: Visual feedback with up/down/neutral states
+- **Multiple Sizes**: Small, medium, and large variants
+- **Flexible Layout**: Responsive and adaptable to different layouts
+
+## Basic Usage
+
+```html
+<snice-kpi
+  label="Total Revenue"
+  value="$45,231">
+</snice-kpi>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `label` | `string` | `''` | Label text (metric name) |
+| `value` | `string \| number` | `''` | Main metric value to display |
+| `trend-value` | `string \| number` | `undefined` | Optional trend value (e.g., "+12.5%") |
+| `trend-data` | `number[]` | `undefined` | Data for sparkline chart |
+| `sentiment` | `KpiSentiment` | `undefined` | Trend sentiment ('up', 'down', 'neutral') |
+| `size` | `KpiSize` | `'medium'` | Component size ('small', 'medium', 'large') |
+| `show-sparkline` | `boolean` | `true` | Whether to show sparkline when data is provided |
+
+## With Trend Indicator
+
+```html
+<snice-kpi
+  label="Monthly Revenue"
+  value="$54,239"
+  trend-value="+12.5%"
+  sentiment="up">
+</snice-kpi>
+```
+
+## With Sparkline
+
+```html
+<snice-kpi
+  id="sales"
+  label="Weekly Sales"
+  value="$28,450"
+  trend-value="+15.3%"
+  sentiment="up">
+</snice-kpi>
+
+<script>
+  document.getElementById('sales').trendData = [
+    20, 25, 22, 30, 28, 35, 32, 38, 36, 42, 40, 45, 43, 48
+  ];
+</script>
+```
+
+## Sentiment Variants
+
+### Up (Positive)
+```html
+<snice-kpi
+  label="Profit Margin"
+  value="34.2%"
+  trend-value="+3.5%"
+  sentiment="up">
+</snice-kpi>
+```
+
+### Down (Attention Needed)
+```html
+<snice-kpi
+  label="Churn Rate"
+  value="2.3%"
+  trend-value="+0.8%"
+  sentiment="down">
+</snice-kpi>
+```
+
+### Neutral (Stable)
+```html
+<snice-kpi
+  label="Market Share"
+  value="28.5%"
+  trend-value="±0%"
+  sentiment="neutral">
+</snice-kpi>
+```
+
+## Sizes
+
+### Small
+```html
+<snice-kpi
+  label="Active Users"
+  value="1,234"
+  size="small">
+</snice-kpi>
+```
+
+### Medium (Default)
+```html
+<snice-kpi
+  label="Active Users"
+  value="1,234"
+  size="medium">
+</snice-kpi>
+```
+
+### Large
+```html
+<snice-kpi
+  label="Active Users"
+  value="1,234"
+  size="large">
+</snice-kpi>
+```
+
+## CSS Parts
+
+Use `::part()` to style internal elements:
+
+```css
+snice-kpi::part(container) {
+  border: 2px solid #e0e0e0;
+}
+
+snice-kpi::part(label) {
+  text-transform: uppercase;
+}
+
+snice-kpi::part(value) {
+  color: #2563eb;
+}
+
+snice-kpi::part(trend) {
+  font-weight: 700;
+}
+```
+
+## Theming
+
+The component uses these CSS custom properties:
+
+```css
+--snice-color-background
+--snice-color-border
+--snice-color-text
+--snice-color-text-secondary
+--snice-color-success
+--snice-color-danger
+--snice-spacing-*
+--snice-font-size-*
+--snice-font-weight-*
+--snice-border-radius-md
+```
+
+## Examples
+
+### Dashboard Metrics
+```html
+<div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 20px;">
+  <snice-kpi
+    id="revenue"
+    label="Monthly Revenue"
+    value="$127,450"
+    trend-value="+22.4%"
+    sentiment="up">
+  </snice-kpi>
+
+  <snice-kpi
+    id="users"
+    label="Active Users"
+    value="2,345"
+    trend-value="+8.7%"
+    sentiment="up">
+  </snice-kpi>
+
+  <snice-kpi
+    id="conversion"
+    label="Conversion Rate"
+    value="3.24%"
+    trend-value="-0.5%"
+    sentiment="down">
+  </snice-kpi>
+</div>
+
+<script>
+  document.getElementById('revenue').trendData = [20, 25, 30, 28, 35, 40, 45];
+  document.getElementById('users').trendData = [100, 120, 110, 150, 140, 170, 160];
+  document.getElementById('conversion').trendData = [3.5, 3.3, 3.4, 3.2, 3.3, 3.1, 3.24];
+</script>
+```
+
+### Without Sparkline
+```html
+<snice-kpi
+  label="Customer Satisfaction"
+  value="4.8/5"
+  trend-value="+0.2"
+  sentiment="up"
+  show-sparkline="false">
+</snice-kpi>
+```
+
+### Complex Metrics
+```html
+<snice-kpi
+  id="nps"
+  label="Net Promoter Score"
+  value="72"
+  trend-value="+4 pts"
+  sentiment="up">
+</snice-kpi>
+
+<snice-kpi
+  id="cac"
+  label="Customer Acquisition Cost"
+  value="$156"
+  trend-value="-5.2%"
+  sentiment="down">
+</snice-kpi>
+```
+
+## Best Practices
+
+1. **Use Clear Labels**: Make metric names concise and understandable
+2. **Format Values**: Present numbers in a readable format ($45K vs $45231.50)
+3. **Consistent Sentiment**: Use 'down' for bad news even if the number decreased (e.g., costs going down is good, but use 'down' for the direction)
+4. **Group Related KPIs**: Display related metrics together for context
+5. **Update Regularly**: Keep metrics fresh with real-time or frequent updates
+
+## Accessibility
+
+- Labels provide context for screen readers
+- Sentiment indicators have clear visual differentiation
+- Sufficient color contrast for all text elements
+- Keyboard navigation supported through standard focus
+
+## Performance
+
+- Lightweight component with minimal DOM
+- Efficient sparkline rendering via SVG
+- CSS containment for optimized rendering
+- No external dependencies beyond sparkline component