snice 4.8.0 → 4.10.0

package/docs/components/countdown.md

@@ -0,0 +1,121 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/countdown.md instead)
+
+# Countdown Component
+
+The countdown component displays a countdown timer to a target date with live-updating segments for days, hours, minutes, and seconds. It supports three visual variants (simple, flip, circular) and configurable display formats.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [Events](#events)
+- [CSS Custom Properties](#css-custom-properties)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+
+## Basic Usage
+
+```html
+<snice-countdown target="2026-12-31T00:00:00Z"></snice-countdown>
+```
+
+```typescript
+import 'snice/components/countdown/snice-countdown';
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `target` | `string` | `''` | ISO date string for the target date/time to count down to |
+| `format` | `'dhms' \| 'hms' \| 'ms'` | `'dhms'` | Display format: days+hours+minutes+seconds, hours+minutes+seconds, or minutes+seconds |
+| `variant` | `'simple' \| 'flip' \| 'circular'` | `'simple'` | Visual style of the countdown display |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `countdown-complete` | `void` | Fired when the countdown reaches zero |
+| `countdown-tick` | `{ days: number, hours: number, minutes: number, seconds: number, total: number }` | Fired every second with the current remaining time values |
+
+## CSS Custom Properties
+
+The countdown component uses standard Snice design tokens:
+
+| Property | Description |
+|----------|-------------|
+| `--snice-font-family` | Font family |
+| `--snice-font-size-2xl` | Digit size |
+| `--snice-font-size-xs` | Label size |
+| `--snice-color-text` | Digit color |
+| `--snice-color-text-secondary` | Label color |
+| `--snice-color-text-tertiary` | Separator color |
+| `--snice-color-background-element` | Flip variant card background |
+| `--snice-color-border` | Flip variant border |
+| `--snice-color-primary` | Circular variant ring color |
+| `--snice-color-success` | Completed state color |
+
+## Examples
+
+### Simple Countdown
+
+The default variant displays digits with labels underneath.
+
+```html
+<snice-countdown target="2026-12-31T00:00:00Z" format="dhms" variant="simple"></snice-countdown>
+```
+
+### Flip Variant
+
+Use `variant="flip"` for a card-flip animation style inspired by airport departure boards.
+
+```html
+<snice-countdown target="2027-01-01T00:00:00Z" variant="flip" format="dhms"></snice-countdown>
+```
+
+### Circular Variant
+
+Use `variant="circular"` to display each segment inside a circular progress ring.
+
+```html
+<snice-countdown target="2026-06-15T18:00:00Z" variant="circular" format="hms"></snice-countdown>
+```
+
+### Short Format (Minutes and Seconds)
+
+Use `format="ms"` for a short countdown that only shows minutes and seconds.
+
+```html
+<snice-countdown target="2026-02-22T12:30:00Z" format="ms" variant="simple"></snice-countdown>
+```
+
+### Event Handling
+
+Listen for completion and tick events to trigger actions.
+
+```html
+<snice-countdown id="sale-timer" target="2026-03-01T00:00:00Z" variant="flip"></snice-countdown>
+
+<script type="module">
+  import 'snice/components/countdown/snice-countdown';
+
+  const countdown = document.getElementById('sale-timer');
+
+  countdown.addEventListener('countdown-complete', () => {
+    alert('The sale has ended!');
+  });
+
+  countdown.addEventListener('countdown-tick', (e) => {
+    if (e.detail.total <= 60) {
+      // Last minute — add urgency styling
+      countdown.style.color = 'red';
+    }
+  });
+</script>
+```
+
+## Accessibility
+
+- **Live updates**: The countdown updates every second with current values
+- **Completion state**: A `.complete` CSS class is added to the host element when the countdown finishes, allowing for visual feedback
+- **Labels**: Each time segment (days, hours, minutes, seconds) has a descriptive label below the digits
+- **Screen readers**: Segment labels provide context for the displayed numbers

package/docs/components/cropper.md

@@ -0,0 +1,152 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/cropper.md instead)
+
+# Cropper Component
+
+The cropper component provides an image cropping tool with a draggable and resizable crop area, rotation, zoom controls, optional aspect ratio locking, and a rule-of-thirds grid overlay. It outputs cropped images as Blob objects in PNG, JPEG, or WebP format.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS Custom Properties](#css-custom-properties)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+
+## Basic Usage
+
+```html
+<snice-cropper src="/photo.jpg"></snice-cropper>
+```
+
+```typescript
+import 'snice/components/cropper/snice-cropper';
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `src` | `string` | `''` | URL of the image to crop |
+| `aspectRatio` (attr: `aspect-ratio`) | `number` | `0` | Lock the crop area to a specific aspect ratio. `0` means free-form. Use `1` for square, `1.777` for 16:9, etc. |
+| `minWidth` (attr: `min-width`) | `number` | `20` | Minimum crop area width in pixels |
+| `minHeight` (attr: `min-height`) | `number` | `20` | Minimum crop area height in pixels |
+| `outputType` (attr: `output-type`) | `'png' \| 'jpeg' \| 'webp'` | `'png'` | Output image format |
+
+## Methods
+
+| Method | Arguments | Returns | Description |
+|--------|-----------|---------|-------------|
+| `crop()` | -- | `Promise<Blob \| null>` | Produce a cropped image Blob from the current crop area |
+| `rotate()` | `degrees: number` | `void` | Rotate the image by the given degrees (cumulative) |
+| `zoom()` | `level: number` | `void` | Set the zoom level (range: 0.1 to 10) |
+| `reset()` | -- | `void` | Reset rotation, zoom, and crop area to their defaults |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `crop-change` | `{ rect: { x: number, y: number, width: number, height: number } }` | Fired when the crop area is moved or resized |
+| `crop-complete` | `{ blob: Blob \| null }` | Fired after `crop()` produces the output blob |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--snice-color-background-element` | Container background color |
+| `--snice-color-border` | Container border color |
+| `--snice-border-radius-lg` | Container border radius |
+
+## Examples
+
+### Basic Image Cropping
+
+Load an image and let the user crop it freely.
+
+```html
+<snice-cropper id="my-cropper" src="/photos/landscape.jpg"></snice-cropper>
+
+<button onclick="handleCrop()">Crop Image</button>
+
+<script type="module">
+  import 'snice/components/cropper/snice-cropper';
+
+  async function handleCrop() {
+    const cropper = document.getElementById('my-cropper');
+    const blob = await cropper.crop();
+    if (blob) {
+      const url = URL.createObjectURL(blob);
+      window.open(url); // Preview the cropped image
+    }
+  }
+  window.handleCrop = handleCrop;
+</script>
+```
+
+### Square Crop with Aspect Ratio Lock
+
+Use `aspect-ratio="1"` to enforce a square crop area, useful for profile photos.
+
+```html
+<snice-cropper
+  src="/photos/portrait.jpg"
+  aspect-ratio="1"
+  output-type="jpeg">
+</snice-cropper>
+```
+
+### 16:9 Crop for Video Thumbnails
+
+Lock to a widescreen aspect ratio for video thumbnails or banner images.
+
+```html
+<snice-cropper
+  src="/photos/wide-shot.jpg"
+  aspect-ratio="1.777"
+  output-type="webp"
+  min-width="160"
+  min-height="90">
+</snice-cropper>
+```
+
+### Rotation and Zoom Controls
+
+Use the `rotate()` and `zoom()` methods for image adjustment.
+
+```html
+<snice-cropper id="editor" src="/photos/vacation.jpg" aspect-ratio="0"></snice-cropper>
+
+<div style="display: flex; gap: 0.5rem; margin-top: 1rem;">
+  <button onclick="document.getElementById('editor').rotate(-90)">Rotate Left</button>
+  <button onclick="document.getElementById('editor').rotate(90)">Rotate Right</button>
+  <button onclick="document.getElementById('editor').zoom(1.5)">Zoom In</button>
+  <button onclick="document.getElementById('editor').zoom(0.8)">Zoom Out</button>
+  <button onclick="document.getElementById('editor').reset()">Reset</button>
+</div>
+```
+
+### Listening to Crop Changes
+
+Track the crop area position and dimensions in real time.
+
+```html
+<snice-cropper id="tracked-cropper" src="/photos/product.jpg"></snice-cropper>
+<p id="crop-info">Move the crop area...</p>
+
+<script type="module">
+  const cropper = document.getElementById('tracked-cropper');
+  const info = document.getElementById('crop-info');
+
+  cropper.addEventListener('crop-change', (e) => {
+    const { x, y, width, height } = e.detail.rect;
+    info.textContent = `Position: (${x}, ${y}) Size: ${width} x ${height}`;
+  });
+</script>
+```
+
+## Accessibility
+
+- **Drag interaction**: The crop area can be repositioned by dragging, and resized via 8 corner and edge handles
+- **Rule-of-thirds grid**: An overlay grid helps with composition alignment
+- **Visual feedback**: A dark mask outside the crop area clearly indicates the cropped region
+- **Aspect ratio enforcement**: When `aspectRatio` is set, resize handles maintain the locked ratio automatically

package/docs/components/date-picker.md

@@ -0,0 +1,201 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/date-picker.md instead)
+
+# Date Picker
+`<snice-date-picker>`
+
+Calendar-based date input with format options and validation.
+
+## Basic Usage
+
+```typescript
+import 'snice/components/date-picker/snice-date-picker';
+```
+
+```html
+<snice-date-picker label="Select date"></snice-date-picker>
+```
+
+## Importing
+
+**ESM (bundler)**
+```typescript
+import 'snice/components/date-picker/snice-date-picker';
+```
+
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-date-picker.min.js"></script>
+```
+
+## Examples
+
+### Variants
+
+Use the `variant` attribute to change the input style.
+
+```html
+<snice-date-picker variant="outlined" label="Outlined"></snice-date-picker>
+<snice-date-picker variant="filled" label="Filled"></snice-date-picker>
+<snice-date-picker variant="underlined" label="Underlined"></snice-date-picker>
+```
+
+### Sizes
+
+Use the `size` attribute to change the picker size.
+
+```html
+<snice-date-picker size="small" label="Small"></snice-date-picker>
+<snice-date-picker size="medium" label="Medium"></snice-date-picker>
+<snice-date-picker size="large" label="Large"></snice-date-picker>
+```
+
+### Date Formats
+
+Use the `format` attribute to control how dates are displayed and parsed.
+
+```html
+<snice-date-picker format="mm/dd/yyyy" label="US Format"></snice-date-picker>
+<snice-date-picker format="dd/mm/yyyy" label="EU Format"></snice-date-picker>
+<snice-date-picker format="yyyy-mm-dd" label="ISO Format"></snice-date-picker>
+<snice-date-picker format="mmmm dd, yyyy" label="Long Format"></snice-date-picker>
+```
+
+### Min and Max Dates
+
+Use the `min` and `max` attributes to restrict the selectable date range.
+
+```html
+<snice-date-picker min="2024-01-01" max="2024-12-31" label="Year 2024 only"></snice-date-picker>
+```
+
+### Clearable
+
+Set the `clearable` attribute to show a clear button when a date is selected.
+
+```html
+<snice-date-picker value="2024-03-15" clearable label="Clearable"></snice-date-picker>
+```
+
+### Helper and Error Text
+
+Use the `helper-text` and `error-text` attributes to provide guidance or validation messages.
+
+```html
+<snice-date-picker label="Start Date" helper-text="Choose a date in the future"></snice-date-picker>
+<snice-date-picker label="End Date" invalid error-text="End date must be after start date"></snice-date-picker>
+```
+
+### Loading
+
+Set the `loading` attribute to show a spinner and disable interaction.
+
+```html
+<snice-date-picker loading label="Loading dates"></snice-date-picker>
+```
+
+### Disabled and Readonly
+
+Use `disabled` or `readonly` to prevent user interaction.
+
+```html
+<snice-date-picker disabled value="2024-06-15" label="Disabled"></snice-date-picker>
+<snice-date-picker readonly value="2024-06-15" label="Readonly"></snice-date-picker>
+```
+
+### First Day of Week
+
+Use the `first-day-of-week` attribute to set which day starts the week (0 = Sunday, 1 = Monday).
+
+```html
+<snice-date-picker first-day-of-week="1" label="Week starts Monday"></snice-date-picker>
+```
+
+### Form Integration
+
+Use `name` and `required` for native form participation.
+
+```html
+<form>
+  <snice-date-picker name="birthdate" required label="Date of Birth"></snice-date-picker>
+</form>
+```
+
+### Event Handling
+
+Listen for date changes using the `datepicker-change` event.
+
+```html
+<snice-date-picker id="dp" label="Pick a date"></snice-date-picker>
+<script>
+document.querySelector('#dp').addEventListener('datepicker-change', (e) => {
+  console.log('Date:', e.detail.formatted);
+  console.log('ISO:', e.detail.iso);
+});
+</script>
+```
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+|----------|-----------|------|---------|-------------|
+| `value` | `value` | `string` | `''` | Current date value |
+| `format` | `format` | `'yyyy-mm-dd' \| 'mm/dd/yyyy' \| 'dd/mm/yyyy' \| 'yyyy/mm/dd' \| 'dd-mm-yyyy' \| 'mm-dd-yyyy' \| 'mmmm dd, yyyy'` | `'mm/dd/yyyy'` | Display and parse format |
+| `variant` | `variant` | `'outlined' \| 'filled' \| 'underlined'` | `'outlined'` | Input visual style |
+| `size` | `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Component size |
+| `placeholder` | `placeholder` | `string` | `''` | Input placeholder text |
+| `label` | `label` | `string` | `''` | Label text |
+| `helperText` | `helper-text` | `string` | `''` | Helper text below input |
+| `errorText` | `error-text` | `string` | `''` | Error text below input |
+| `disabled` | `disabled` | `boolean` | `false` | Disables the picker |
+| `readonly` | `readonly` | `boolean` | `false` | Makes the input read-only |
+| `loading` | `loading` | `boolean` | `false` | Shows loading spinner |
+| `required` | `required` | `boolean` | `false` | Marks as required |
+| `invalid` | `invalid` | `boolean` | `false` | Shows invalid styling |
+| `clearable` | `clearable` | `boolean` | `false` | Shows clear button |
+| `min` | `min` | `string` | `''` | Minimum selectable date |
+| `max` | `max` | `string` | `''` | Maximum selectable date |
+| `name` | `name` | `string` | `''` | Form field name |
+| `showCalendar` | `show-calendar` | `boolean` | `false` | Calendar visibility |
+| `firstDayOfWeek` | `first-day-of-week` | `number` | `0` | First day of week (0=Sun) |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `datepicker-input` | `{ value, datePicker }` | Fired on text input |
+| `datepicker-change` | `{ value, date, formatted, iso, datePicker }` | Fired when date changes |
+| `datepicker-focus` | `{ datePicker }` | Fired on input focus |
+| `datepicker-blur` | `{ datePicker }` | Fired on input blur |
+| `datepicker-open` | `{ datePicker }` | Fired when calendar opens |
+| `datepicker-close` | `{ datePicker }` | Fired when calendar closes |
+| `datepicker-clear` | `{ datePicker }` | Fired when value is cleared |
+| `datepicker-select` | `{ date, formatted, iso, datePicker }` | Fired when a date is selected |
+
+## Methods
+
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `focus()` | — | Focuses the input |
+| `blur()` | — | Removes focus |
+| `clear()` | — | Clears the selected date |
+| `open()` | — | Opens the calendar popup |
+| `close()` | — | Closes the calendar popup |
+| `selectDate()` | `date: Date` | Programmatically selects a date |
+| `goToMonth()` | `year: number, month: number` | Navigates calendar to a month |
+| `goToToday()` | — | Selects today's date |
+| `checkValidity()` | — | Returns input validity |
+| `reportValidity()` | — | Reports input validity |
+| `setCustomValidity()` | `message: string` | Sets custom validation message |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `input` | The text input element |
+| `calendar-toggle` | The calendar icon button |
+| `clear` | The clear button |
+| `spinner` | The loading spinner |
+| `calendar` | The calendar popup container |
+| `helper-text` | The helper text element |
+| `error-text` | The error text element |

package/docs/components/diff.md

@@ -0,0 +1,177 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/diff.md instead)
+
+# Diff Component
+
+The diff component displays a text diff between two strings with unified or side-by-side (split) views, line numbers, word-level highlighting, collapsible unchanged sections, and addition/deletion statistics.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [Events](#events)
+- [CSS Custom Properties](#css-custom-properties)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+
+## Basic Usage
+
+```html
+<snice-diff old-text="hello world" new-text="hello there"></snice-diff>
+```
+
+```typescript
+import 'snice/components/diff/snice-diff';
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `oldText` (attr: `old-text`) | `string` | `''` | The original text |
+| `newText` (attr: `new-text`) | `string` | `''` | The modified text |
+| `language` | `string` | `''` | Language hint for future syntax highlighting support |
+| `mode` | `'unified' \| 'split'` | `'unified'` | Display mode: unified inline view or side-by-side split view |
+| `lineNumbers` (attr: `line-numbers`) | `boolean` | `true` | Show line number gutters |
+| `contextLines` (attr: `context-lines`) | `number` | `3` | Number of unchanged lines shown around each change |
+| `markers` | `boolean` | `true` | Show the +/- markers column |
+
+### Types
+
+```typescript
+interface DiffLine {
+  type: 'added' | 'removed' | 'unchanged';
+  oldLine: number | null;
+  newLine: number | null;
+  content: string;
+}
+
+interface DiffHunk {
+  lines: DiffLine[];
+  collapsed: boolean;
+}
+```
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `diff-computed` | `{ hunks: DiffHunk[], additions: number, deletions: number }` | Fired after the diff is calculated, with hunk data and stats |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--snice-diff-added-bg` | Background color for added lines |
+| `--snice-diff-removed-bg` | Background color for removed lines |
+| `--snice-diff-added-word-bg` | Word-level highlight color for added text |
+| `--snice-diff-removed-word-bg` | Word-level highlight color for removed text |
+
+## Examples
+
+### Unified Diff View
+
+The default unified mode shows all changes inline with +/- markers.
+
+```html
+<snice-diff
+  old-text="function greet(name) {
+  return 'Hello, ' + name;
+}"
+  new-text="function greet(name) {
+  return `Hello, ${name}!`;
+}"
+  mode="unified"
+  context-lines="3">
+</snice-diff>
+```
+
+### Side-by-Side Split View
+
+Use `mode="split"` to display old and new text in separate columns.
+
+```html
+<snice-diff
+  id="split-diff"
+  mode="split"
+  line-numbers
+  context-lines="3">
+</snice-diff>
+
+<script type="module">
+  import 'snice/components/diff/snice-diff';
+
+  const diff = document.getElementById('split-diff');
+  diff.oldText = `const x = 1;
+const y = 2;
+const z = x + y;
+console.log(z);`;
+
+  diff.newText = `const x = 10;
+const y = 2;
+const sum = x + y;
+console.log(sum);
+console.log('done');`;
+</script>
+```
+
+### Without Line Numbers or Markers
+
+Set `line-numbers="false"` and `markers="false"` for a minimal view.
+
+```html
+<snice-diff
+  old-text="The quick brown fox"
+  new-text="The slow red fox"
+  line-numbers="false"
+  markers="false">
+</snice-diff>
+```
+
+### Listening to Diff Stats
+
+Use the `diff-computed` event to access addition and deletion counts.
+
+```html
+<snice-diff id="stats-diff" old-text="Line A" new-text="Line B"></snice-diff>
+<p id="diff-stats"></p>
+
+<script type="module">
+  const diff = document.getElementById('stats-diff');
+  diff.addEventListener('diff-computed', (e) => {
+    const { additions, deletions } = e.detail;
+    document.getElementById('diff-stats').textContent =
+      `+${additions} additions, -${deletions} deletions`;
+  });
+</script>
+```
+
+### Comparing Large Texts with Collapsed Sections
+
+When comparing large files, unchanged sections beyond the `context-lines` threshold are collapsed. Click the collapsed section indicator to expand it.
+
+```html
+<snice-diff
+  id="large-diff"
+  mode="unified"
+  context-lines="2">
+</snice-diff>
+
+<script type="module">
+  const diff = document.getElementById('large-diff');
+
+  diff.oldText = Array.from({ length: 50 }, (_, i) => `Line ${i + 1}: original content`).join('\n');
+  diff.newText = Array.from({ length: 50 }, (_, i) => {
+    if (i === 10) return `Line ${i + 1}: MODIFIED content`;
+    if (i === 40) return `Line ${i + 1}: ALSO changed`;
+    return `Line ${i + 1}: original content`;
+  }).join('\n');
+</script>
+```
+
+## Accessibility
+
+- **Dark mode support**: Automatically adapts colors for `[data-theme="dark"]` and `prefers-color-scheme: dark`
+- **Line numbers**: Provide clear reference points for discussing specific changes
+- **Color coding**: Added lines are highlighted with a green background, removed lines with red, providing clear visual distinction
+- **Word-level diffs**: Within changed lines, the specific words that differ are highlighted for precision
+- **Collapsible sections**: Large unchanged regions are collapsed to reduce noise and can be expanded on demand
+- **Stats header**: The +N/-N summary provides an immediate overview of the change scope