snice 2.5.4 → 3.2.0

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>
+```

package/docs/components/timeline.md

@@ -0,0 +1,192 @@
+# Timeline Component
+
+The `<snice-timeline>` component displays events in chronological order with markers, timestamps, and descriptions.
+
+## Basic Usage
+
+```html
+<snice-timeline id="timeline"></snice-timeline>
+
+<script>
+  const timeline = document.getElementById('timeline');
+  timeline.items = [
+    {
+      timestamp: '2024-01-15',
+      title: 'Event Title',
+      description: 'Event description'
+    }
+  ];
+</script>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Timeline orientation |
+| `position` | `'left' \| 'right' \| 'alternate'` | `'left'` | Item position (vertical only) |
+| `items` | `TimelineItem[]` | `[]` | Timeline items |
+| `reverse` | `boolean` | `false` | Reverse item order |
+
+## TimelineItem Interface
+
+```typescript
+interface TimelineItem {
+  timestamp?: string;
+  title: string;
+  description?: string;
+  icon?: string;
+  variant?: 'default' | 'success' | 'warning' | 'error' | 'info';
+}
+```
+
+## Examples
+
+### Vertical Timeline
+
+```html
+<snice-timeline id="timeline"></snice-timeline>
+
+<script>
+  document.getElementById('timeline').items = [
+    {
+      timestamp: '2024-01-15 09:00',
+      title: 'Project Started',
+      description: 'Initial planning phase'
+    },
+    {
+      timestamp: '2024-01-20 14:30',
+      title: 'Design Complete',
+      description: 'Mockups approved'
+    }
+  ];
+</script>
+```
+
+### Horizontal Timeline
+
+```html
+<snice-timeline orientation="horizontal" id="horizontal-timeline"></snice-timeline>
+
+<script>
+  document.getElementById('horizontal-timeline').items = [
+    { title: 'Step 1', description: 'First step' },
+    { title: 'Step 2', description: 'Second step' },
+    { title: 'Step 3', description: 'Third step' }
+  ];
+</script>
+```
+
+### Alternate Position
+
+```html
+<snice-timeline position="alternate" id="alt-timeline"></snice-timeline>
+
+<script>
+  document.getElementById('alt-timeline').items = [
+    { title: 'Event 1', timestamp: 'Jan 2024' },
+    { title: 'Event 2', timestamp: 'Feb 2024' },
+    { title: 'Event 3', timestamp: 'Mar 2024' }
+  ];
+</script>
+```
+
+### With Variants
+
+```html
+<snice-timeline id="variant-timeline"></snice-timeline>
+
+<script>
+  document.getElementById('variant-timeline').items = [
+    {
+      title: 'Completed',
+      variant: 'success',
+      description: 'Task finished successfully'
+    },
+    {
+      title: 'Warning',
+      variant: 'warning',
+      description: 'Attention needed'
+    },
+    {
+      title: 'Error',
+      variant: 'error',
+      description: 'Action failed'
+    }
+  ];
+</script>
+```
+
+### Custom Icons
+
+```html
+<snice-timeline id="icon-timeline"></snice-timeline>
+
+<script>
+  document.getElementById('icon-timeline').items = [
+    { title: 'Planning', icon: '📋' },
+    { title: 'Development', icon: '💻' },
+    { title: 'Launch', icon: '🚀' }
+  ];
+</script>
+```
+
+### Reversed Order
+
+```html
+<snice-timeline reverse id="reversed-timeline"></snice-timeline>
+
+<script>
+  document.getElementById('reversed-timeline').items = [
+    { title: 'Latest Event', timestamp: '2024-03-01' },
+    { title: 'Earlier Event', timestamp: '2024-02-01' },
+    { title: 'First Event', timestamp: '2024-01-01' }
+  ];
+</script>
+```
+
+## Styling
+
+The component exposes several CSS parts for styling:
+
+```css
+snice-timeline::part(container) {
+  /* Timeline container */
+}
+
+snice-timeline::part(item) {
+  /* Timeline item */
+}
+
+snice-timeline::part(marker) {
+  /* Item marker/circle */
+}
+
+snice-timeline::part(icon) {
+  /* Marker icon */
+}
+
+snice-timeline::part(content) {
+  /* Item content area */
+}
+
+snice-timeline::part(timestamp) {
+  /* Timestamp text */
+}
+
+snice-timeline::part(title) {
+  /* Title text */
+}
+
+snice-timeline::part(description) {
+  /* Description text */
+}
+```
+
+## Notes
+
+- Items without timestamps will still render but won't display a timestamp
+- Items without descriptions will only show the title
+- Default icons are provided for each variant
+- Horizontal timelines work best with 3-5 items
+- Alternate positioning creates a zigzag layout