snice 4.9.0 → 4.10.0

package/docs/components/comments.md

@@ -0,0 +1,235 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/comments.md instead)
+
+# Comments Component
+
+The comments component provides a threaded comment system with nested replies, like/unlike functionality, user avatars, relative timestamps, and current-user awareness for delete permissions.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS Custom Properties](#css-custom-properties)
+- [CSS Parts](#css-parts)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+
+## Basic Usage
+
+```html
+<snice-comments current-user="Alice"></snice-comments>
+```
+
+```typescript
+import 'snice/components/comments/snice-comments';
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `comments` | `Comment[]` | `[]` | Array of comment objects (set via JavaScript) |
+| `currentUser` (attr: `current-user`) | `string` | `''` | Name of the logged-in user. Enables delete on own comments. |
+| `allowReplies` (attr: `allow-replies`) | `boolean` | `true` | Enable nested reply threads |
+| `allowLikes` (attr: `allow-likes`) | `boolean` | `true` | Enable like/unlike functionality per comment |
+| `maxDepth` (attr: `max-depth`) | `number` | `3` | Maximum nesting depth for replies |
+
+### Comment Type
+
+```typescript
+interface Comment {
+  id: string;
+  author: string;
+  avatar?: string;       // URL for avatar image
+  text: string;
+  timestamp: string;     // ISO date string
+  replies?: Comment[];
+  likes?: number;
+  liked?: boolean;
+}
+```
+
+## Methods
+
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `addComment()` | `text: string, parentId?: string` | Add a top-level comment or a reply (when `parentId` is provided) |
+| `deleteComment()` | `id: string` | Remove a comment by its ID |
+| `likeComment()` | `id: string` | Toggle the like state on a comment |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `comment-add` | `{ id: string, text: string, author: string }` | Fired when a new top-level comment is submitted |
+| `comment-reply` | `{ id: string, text: string, author: string, parentId: string }` | Fired when a reply is submitted to an existing comment |
+| `comment-delete` | `{ id: string }` | Fired when a comment is deleted |
+| `comment-like` | `{ id: string, likes: number, liked: boolean }` | Fired when a comment is liked or unliked |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--comments-bg` | Background color |
+| `--comments-border` | Border color |
+| `--comments-text` | Primary text color |
+| `--comments-text-secondary` | Author name and secondary text color |
+| `--comments-text-tertiary` | Timestamps and placeholder text color |
+| `--comments-primary` | Submit button and active like color |
+| `--comments-danger` | Delete action hover color |
+| `--comments-bg-element` | Avatar background and hover state color |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `base` | Root container element |
+| `input-area` | The new comment input area |
+| `list` | The comments list container |
+
+## Examples
+
+### Basic Comment Thread
+
+Set comments via JavaScript to display a comment thread with the current user set.
+
+```html
+<snice-comments id="my-comments" current-user="Alice" allow-replies allow-likes></snice-comments>
+
+<script type="module">
+  import 'snice/components/comments/snice-comments';
+
+  const el = document.getElementById('my-comments');
+  el.comments = [
+    {
+      id: '1',
+      author: 'Bob',
+      avatar: '/avatars/bob.jpg',
+      text: 'Great article! Really enjoyed the section on performance.',
+      timestamp: '2026-02-20T10:00:00Z',
+      likes: 5
+    },
+    {
+      id: '2',
+      author: 'Alice',
+      text: 'Thanks Bob! I spent a lot of time on that section.',
+      timestamp: '2026-02-20T11:30:00Z',
+      likes: 2
+    }
+  ];
+</script>
+```
+
+### Nested Replies
+
+Use the `replies` array within a comment to create threaded conversations. Control the nesting depth with `max-depth`.
+
+```html
+<snice-comments id="nested-comments" current-user="Charlie" max-depth="3"></snice-comments>
+
+<script type="module">
+  const el = document.getElementById('nested-comments');
+  el.comments = [
+    {
+      id: '1',
+      author: 'Alice',
+      text: 'Has anyone tried the new API?',
+      timestamp: '2026-02-19T09:00:00Z',
+      likes: 3,
+      replies: [
+        {
+          id: '2',
+          author: 'Bob',
+          text: 'Yes! The response times are much better.',
+          timestamp: '2026-02-19T10:15:00Z',
+          likes: 1,
+          replies: [
+            {
+              id: '3',
+              author: 'Charlie',
+              text: 'Agreed, the caching layer makes a big difference.',
+              timestamp: '2026-02-19T11:00:00Z'
+            }
+          ]
+        }
+      ]
+    }
+  ];
+</script>
+```
+
+### Read-Only Comments (No Replies or Likes)
+
+Disable replies and likes for a read-only display of past comments.
+
+```html
+<snice-comments
+  id="readonly-comments"
+  current-user=""
+  allow-replies="false"
+  allow-likes="false">
+</snice-comments>
+
+<script type="module">
+  const el = document.getElementById('readonly-comments');
+  el.comments = [
+    { id: '1', author: 'Admin', text: 'Version 2.0 has been released.', timestamp: '2026-01-15T08:00:00Z', likes: 12 },
+    { id: '2', author: 'Support', text: 'Please update to the latest version.', timestamp: '2026-01-16T14:00:00Z', likes: 4 }
+  ];
+</script>
+```
+
+### Listening to Events
+
+Listen for comment actions to sync with a backend.
+
+```html
+<snice-comments id="event-comments" current-user="Alice"></snice-comments>
+
+<script type="module">
+  const el = document.getElementById('event-comments');
+  el.comments = [];
+
+  el.addEventListener('comment-add', (e) => {
+    console.log('New comment:', e.detail.text, 'by', e.detail.author);
+    // POST to your API
+  });
+
+  el.addEventListener('comment-reply', (e) => {
+    console.log('Reply to', e.detail.parentId, ':', e.detail.text);
+  });
+
+  el.addEventListener('comment-like', (e) => {
+    console.log('Comment', e.detail.id, 'now has', e.detail.likes, 'likes');
+  });
+
+  el.addEventListener('comment-delete', (e) => {
+    console.log('Deleted comment:', e.detail.id);
+  });
+</script>
+```
+
+### Declarative Usage with Child Elements
+
+Comments can also be defined declaratively using `<snice-comment>` child elements.
+
+```html
+<snice-comments current-user="John" allow-replies allow-likes>
+  <snice-comment author="Alice" avatar="alice.jpg" timestamp="2026-01-15T10:30:00Z" likes="3">
+    This is a great article!
+    <snice-comment author="Bob" timestamp="2026-01-15T11:00:00Z">
+      Thanks Alice!
+    </snice-comment>
+  </snice-comment>
+  <snice-comment author="Charlie" timestamp="2026-01-15T12:00:00Z">
+    Very informative.
+  </snice-comment>
+</snice-comments>
+```
+
+## Accessibility
+
+- **Keyboard support**: Tab through comments, reply buttons, and like buttons. Enter or Space to activate controls.
+- **Timestamps**: Displayed as relative times (e.g., "2 hours ago") for quick scanning
+- **Current user**: Delete controls only appear on the current user's own comments to prevent confusion
+- **Screen readers**: Comment structure and author information are conveyed through semantic markup

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