snice 4.8.0 → 4.10.0

package/docs/components/carousel.md

@@ -1,63 +1,232 @@
-# Carousel Component
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/carousel.md instead)
 
-Image/content carousel with autoplay, loop, and navigation controls.
+# Carousel
+`<snice-carousel>`
+
+Content carousel with autoplay, looping, navigation controls, and multi-slide views.
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/carousel/snice-carousel';
+```
+
 ```html
 <snice-carousel>
-  <div class="slide">Slide 1</div>
-  <div class="slide">Slide 2</div>
-  <div class="slide">Slide 3</div>
+  <div>Slide 1</div>
+  <div>Slide 2</div>
+  <div>Slide 3</div>
 </snice-carousel>
 ```
 
-## Properties
+## Importing
 
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `activeIndex` | `number` | `0` | Current slide index |
-| `autoplay` | `boolean` | `false` | Enable autoplay |
-| `autoplayInterval` | `number` | `3000` | Autoplay interval (ms) |
-| `autoplayDirection` | `'forward' \| 'backward'` | `'forward'` | Autoplay direction |
-| `loop` | `boolean` | `true` | Loop slides |
-| `showControls` | `boolean` | `true` | Show prev/next buttons |
-| `showIndicators` | `boolean` | `true` | Show slide indicators |
-| `slidesPerView` | `number` | `1` | Number of slides visible |
-| `spaceBetween` | `number` | `0` | Space between slides (px) |
-
-## Methods
+**ESM (bundler)**
+```typescript
+import 'snice/components/carousel/snice-carousel';
+```
 
-- `next()` - Go to next slide
-- `prev()` - Go to previous slide
-- `goToSlide(index: number)` - Go to specific slide
-- `play()` - Start autoplay
-- `pause()` - Pause autoplay
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-carousel.min.js"></script>
+```
 
-## Events
+## Examples
 
-- `carousel-slide-change` - Slide changed (detail: { activeIndex, previousIndex, carousel })
+### Autoplay
 
-## Examples
+Set the `autoplay` attribute to automatically advance slides. Use `autoplay-interval` to control the timing in milliseconds.
 
 ```html
-<!-- Autoplay -->
 <snice-carousel autoplay autoplay-interval="2000">
-  <div>Slide 1</div>
-  <div>Slide 2</div>
+  <img src="/photos/hero-1.jpg" alt="Product showcase">
+  <img src="/photos/hero-2.jpg" alt="Feature highlight">
+  <img src="/photos/hero-3.jpg" alt="Customer testimonial">
 </snice-carousel>
+```
+
+### Autoplay Direction
+
+Use `autoplay-direction` to reverse the autoplay direction.
 
-<!-- Multiple slides -->
+```html
+<snice-carousel autoplay autoplay-direction="backward">
+  <div>First</div>
+  <div>Second</div>
+  <div>Third</div>
+</snice-carousel>
+```
+
+### Multiple Slides Per View
+
+Use `slides-per-view` to show multiple slides at once, and `space-between` for spacing.
+
+```html
 <snice-carousel slides-per-view="3" space-between="20">
-  <div>1</div>
-  <div>2</div>
-  <div>3</div>
-  <div>4</div>
+  <div>Card 1</div>
+  <div>Card 2</div>
+  <div>Card 3</div>
+  <div>Card 4</div>
+  <div>Card 5</div>
 </snice-carousel>
+```
+
+### Without Loop
+
+Set `loop` to `false` to disable infinite scrolling. Navigation buttons will be disabled at the start and end.
 
-<!-- No loop -->
+```html
 <snice-carousel loop="false">
+  <div>Step 1: Introduction</div>
+  <div>Step 2: Configuration</div>
+  <div>Step 3: Deployment</div>
+</snice-carousel>
+```
+
+### Hide Controls
+
+Use `show-controls` and `show-indicators` to toggle navigation elements.
+
+```html
+<!-- No arrow buttons -->
+<snice-carousel show-controls="false">
+  <div>Slide 1</div>
+  <div>Slide 2</div>
+</snice-carousel>
+
+<!-- No indicator dots -->
+<snice-carousel show-indicators="false">
   <div>Slide 1</div>
   <div>Slide 2</div>
 </snice-carousel>
 ```
+
+### Programmatic Control
+
+Use methods to control the carousel from JavaScript.
+
+```html
+<snice-carousel id="myCarousel">
+  <img src="/photos/1.jpg" alt="Photo 1">
+  <img src="/photos/2.jpg" alt="Photo 2">
+  <img src="/photos/3.jpg" alt="Photo 3">
+</snice-carousel>
+
+<button onclick="document.getElementById('myCarousel').prev()">Previous</button>
+<button onclick="document.getElementById('myCarousel').next()">Next</button>
+<button onclick="document.getElementById('myCarousel').goToSlide(0)">First</button>
+```
+
+### Event Handling
+
+Listen for slide changes to synchronize other UI elements.
+
+```typescript
+const carousel = document.querySelector<SniceCarouselElement>('snice-carousel');
+
+carousel.addEventListener('carousel-slide-change', (e: CustomEvent) => {
+  console.log('Active slide:', e.detail.activeIndex);
+  console.log('Previous slide:', e.detail.previousIndex);
+});
+```
+
+### Image Gallery
+
+A common pattern using the carousel for an image gallery.
+
+```html
+<snice-carousel id="gallery" loop>
+  <img src="/gallery/sunset.jpg" alt="Sunset over mountains">
+  <img src="/gallery/ocean.jpg" alt="Ocean waves">
+  <img src="/gallery/forest.jpg" alt="Forest trail">
+  <img src="/gallery/city.jpg" alt="City skyline">
+</snice-carousel>
+
+<style>
+  snice-carousel img {
+    width: 100%;
+    height: 400px;
+    object-fit: cover;
+    border-radius: 8px;
+  }
+</style>
+```
+
+### Product Card Carousel
+
+Display product cards in a scrollable carousel.
+
+```html
+<snice-carousel slides-per-view="3" space-between="16" loop>
+  <div class="product-card">
+    <img src="/products/headphones.jpg" alt="Headphones">
+    <h3>Wireless Headphones</h3>
+    <p>$79.99</p>
+  </div>
+  <div class="product-card">
+    <img src="/products/keyboard.jpg" alt="Keyboard">
+    <h3>Mechanical Keyboard</h3>
+    <p>$129.99</p>
+  </div>
+  <div class="product-card">
+    <img src="/products/mouse.jpg" alt="Mouse">
+    <h3>Ergonomic Mouse</h3>
+    <p>$49.99</p>
+  </div>
+  <div class="product-card">
+    <img src="/products/monitor.jpg" alt="Monitor">
+    <h3>4K Monitor</h3>
+    <p>$399.99</p>
+  </div>
+</snice-carousel>
+```
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| (default) | Slide content. Each direct child element becomes one slide. |
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `activeIndex` (attr: `active-index`) | `number` | `0` | Current slide index |
+| `autoplay` | `boolean` | `false` | Enable automatic slide advancement |
+| `autoplayInterval` (attr: `autoplay-interval`) | `number` | `3000` | Autoplay interval in milliseconds |
+| `autoplayDirection` (attr: `autoplay-direction`) | `'forward' \| 'backward'` | `'forward'` | Autoplay direction |
+| `loop` | `boolean` | `true` | Enable infinite looping |
+| `showControls` (attr: `show-controls`) | `boolean` | `true` | Show previous/next arrow buttons |
+| `showIndicators` (attr: `show-indicators`) | `boolean` | `true` | Show slide indicator dots |
+| `slidesPerView` (attr: `slides-per-view`) | `number` | `1` | Number of slides visible at once |
+| `spaceBetween` (attr: `space-between`) | `number` | `0` | Space between slides in pixels |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `carousel-slide-change` | `{ activeIndex: number, previousIndex: number, carousel: SniceCarouselElement }` | Fired when the active slide changes |
+
+## Methods
+
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `next()` | — | Advance to the next slide |
+| `prev()` | — | Go to the previous slide |
+| `goToSlide()` | `index: number` | Navigate to a specific slide by index |
+| `play()` | — | Start autoplay |
+| `pause()` | — | Pause autoplay |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `container` | The outermost carousel wrapper |
+| `viewport` | The visible slide area |
+| `slides-container` | The flex container holding all slides |
+| `controls` | The prev/next button container |
+| `button-prev` | The previous slide button |
+| `button-next` | The next slide button |
+| `indicators` | The slide indicator dot container |
+| `indicator` | Individual slide indicator dot |

package/docs/components/chart.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/chart.md instead)
+
 # Chart Component
 
 General-purpose charting component supporting multiple chart types with animations and interactivity.

package/docs/components/chat.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/chat.md instead)
+
 # snice-chat
 
 A Slack-style chat interface component with messages, typing indicators, reactions, and file attachments.

package/docs/components/checkbox.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/checkbox.md instead)
+
 # Checkbox Component
 
 The checkbox component provides a form-associated checkbox input with support for checked, indeterminate, and invalid states, multiple sizes, and full keyboard accessibility.

package/docs/components/chip.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/chip.md instead)
+
 # Chip Component
 
 The chip component provides compact elements for tags, filters, selections, or categorizations. It supports icons, avatars, removable states, and multiple visual variants.

package/docs/components/code-block.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/code-block.md instead)
+
 # Code Block Component
 
 Display code with syntax highlighting, line numbers, and copy functionality. Uses a JSON-driven tokenizer engine with Monarch-inspired state machine for syntax highlighting.

package/docs/components/color-display.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/color-display.md instead)
+
 # Color Display Component
 
 The `<snice-color-display>` component displays colors with a swatch and formatted label.

package/docs/components/color-picker.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/color-picker.md instead)
+
 # Color Picker Component
 
 The `<snice-color-picker>` component provides a color selection interface with format conversion and preset colors.
@@ -20,14 +22,14 @@ The `<snice-color-picker>` component provides a color selection interface with f
 | `format` | `'hex' \| 'rgb' \| 'hsl'` | `'hex'` | Display format |
 | `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Size variant |
 | `label` | `string` | `''` | Label text |
-| `helperText` | `string` | `''` | Helper text |
-| `errorText` | `string` | `''` | Error message |
+| `helperText` (attr: `helper-text`) | `string` | `''` | Helper text |
+| `errorText` (attr: `error-text`) | `string` | `''` | Error message |
 | `disabled` | `boolean` | `false` | Disabled state |
 | `required` | `boolean` | `false` | Required state |
 | `invalid` | `boolean` | `false` | Invalid state |
 | `name` | `string` | `''` | Form field name |
-| `showInput` | `boolean` | `true` | Show text input |
-| `showPresets` | `boolean` | `false` | Show preset colors |
+| `showInput` (attr: `show-input`) | `boolean` | `true` | Show text input |
+| `showPresets` (attr: `show-presets`) | `boolean` | `false` | Show preset colors |
 | `presets` | `string[]` | `[...]` | Preset color values |
 
 ## Methods

package/docs/components/command-palette.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/command-palette.md instead)
+
 # Command Palette Component
 
 A searchable command palette overlay (⌘K) for quick access to application commands and actions.

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