snice 4.9.0 → 4.10.0

package/docs/components/book.md

@@ -0,0 +1,184 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/book.md instead)
+
+# Book Component
+
+The book component displays content as a page-flipping book with realistic 3D page-turn animations. It supports spread (two-page) and single-page modes, a customizable cover page, keyboard and touch navigation, and programmatic page control.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [Slots](#slots)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS Custom Properties](#css-custom-properties)
+- [CSS Parts](#css-parts)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+
+## Basic Usage
+
+```html
+<snice-book>
+  <div>Page 1 content</div>
+  <div>Page 2 content</div>
+  <div>Page 3 content</div>
+</snice-book>
+```
+
+```typescript
+import 'snice/components/book/snice-book';
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `currentPage` (attr: `current-page`) | `number` | `0` | Current page number (0-indexed) |
+| `mode` | `'single' \| 'spread'` | `'spread'` | Display mode: single page or two-page spread |
+| `coverImage` (attr: `cover-image`) | `string` | `''` | URL for the cover page image |
+| `title` | `string` | `''` | Book title displayed on the cover |
+| `author` | `string` | `''` | Author name displayed on the cover |
+| `totalPages` | `number` | _(read-only)_ | Total number of pages (count of slotted child elements) |
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| (default) | Page elements. Each child element becomes one page in the book. |
+
+## Methods
+
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `goToPage()` | `page: number` | Navigate to a specific page. In spread mode, auto-aligns to the correct spread. |
+| `nextPage()` | -- | Advance forward by 1 page (single mode) or 2 pages (spread mode) |
+| `prevPage()` | -- | Go back by 1 page (single mode) or 2 pages (spread mode) |
+| `firstPage()` | -- | Jump to the first page (page 0) |
+| `lastPage()` | -- | Jump to the last page |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `page-turn` | `{ page: number, direction: 'forward' \| 'backward' }` | Fired when a page turn completes |
+| `page-flip-start` | `{ fromPage: number, toPage: number, direction: 'forward' \| 'backward' }` | Fired when a page flip animation starts |
+| `page-flip-end` | `{ page: number, direction: 'forward' \| 'backward' }` | Fired when a page flip animation finishes |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--book-bg` | Page background color |
+| `--book-text` | Primary text color |
+| `--book-text-secondary` | Secondary text color |
+| `--book-border` | Border color |
+| `--book-primary` | Primary accent color |
+| `--book-shadow` | Book shadow |
+| `--book-page-bg` | Individual page background |
+| `--book-page-line` | Ruled line color on pages |
+| `--book-spine-bg` | Spine color |
+| `--book-cover-bg` | Cover background color |
+| `--book-flip-duration` | Flip animation duration (default: `0.6s`) |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `spine` | The book spine element |
+| `pages` | The pages container |
+| `nav` | The navigation controls bar |
+
+## Examples
+
+### Basic Book with Cover
+
+Use the `title`, `author`, and `cover-image` attributes to create a book with a styled cover page.
+
+```html
+<snice-book title="The Great Gatsby" author="F. Scott Fitzgerald" cover-image="/covers/gatsby.jpg">
+  <div>In my younger and more vulnerable years my father gave me some advice...</div>
+  <div>Chapter 2 content here...</div>
+  <div>Chapter 3 content here...</div>
+  <div>Chapter 4 content here...</div>
+</snice-book>
+```
+
+### Single Page Mode
+
+Use `mode="single"` for narrow viewports or when you want one page visible at a time.
+
+```html
+<snice-book mode="single" title="User Guide">
+  <div>Welcome to the application...</div>
+  <div>Getting started with your first project...</div>
+  <div>Advanced features and configuration...</div>
+</snice-book>
+```
+
+### Spread Mode (Two-Page View)
+
+The default `mode="spread"` displays two pages side by side like an open book.
+
+```html
+<snice-book mode="spread" title="Photo Album" author="Jane Doe">
+  <div><img src="/photos/1.jpg" alt="Vacation day 1"></div>
+  <div><img src="/photos/2.jpg" alt="Vacation day 2"></div>
+  <div><img src="/photos/3.jpg" alt="Vacation day 3"></div>
+  <div><img src="/photos/4.jpg" alt="Vacation day 4"></div>
+</snice-book>
+```
+
+### Programmatic Navigation
+
+Use methods to control the book from JavaScript.
+
+```html
+<snice-book id="tutorial-book" title="Tutorial">
+  <div>Step 1: Install the package</div>
+  <div>Step 2: Import the component</div>
+  <div>Step 3: Add it to your HTML</div>
+  <div>Step 4: Customize with properties</div>
+</snice-book>
+
+<button onclick="document.getElementById('tutorial-book').prevPage()">Previous</button>
+<button onclick="document.getElementById('tutorial-book').nextPage()">Next</button>
+
+<script type="module">
+  import 'snice/components/book/snice-book';
+
+  const book = document.getElementById('tutorial-book');
+  book.addEventListener('page-turn', (e) => {
+    console.log(`Turned to page ${e.detail.page} (${e.detail.direction})`);
+  });
+</script>
+```
+
+### Rich HTML Content Pages
+
+Each page can contain arbitrary HTML including text, images, and interactive elements.
+
+```html
+<snice-book title="Product Catalog" mode="spread">
+  <div style="padding: 2rem;">
+    <h2>Introduction</h2>
+    <p>Browse our latest collection of premium products.</p>
+  </div>
+  <div style="padding: 2rem;">
+    <h3>Widget Pro</h3>
+    <img src="/products/widget-pro.jpg" alt="Widget Pro" style="width: 100%;">
+    <p>Our most popular product. Starting at $29.99.</p>
+  </div>
+  <div style="padding: 2rem;">
+    <h3>Gadget X</h3>
+    <img src="/products/gadget-x.jpg" alt="Gadget X" style="width: 100%;">
+    <p>Next-generation performance. Starting at $49.99.</p>
+  </div>
+</snice-book>
+```
+
+## Accessibility
+
+- **Keyboard support**: Arrow Right/Down to go to the next page, Arrow Left/Up for the previous page, Home for the first page, End for the last page
+- **Focus management**: The book is focusable and responds to keyboard input when focused
+- **Screen readers**: Page turn events and navigation controls provide feedback on the current position
+- **Touch support**: Swipe gestures on touch devices for natural page turning

package/docs/components/breadcrumbs.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/breadcrumbs.md instead)
+
 # Breadcrumbs Components
 
 The breadcrumbs components provide navigation trail indicators showing the user's current location within a hierarchy. Supports icons, custom separators, collapsing for long trails, and multiple sizes.

package/docs/components/button.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/button.md instead)
+
 # Button Component
 
 The button component provides an interactive element for user actions. It supports multiple variants, sizes, states (loading, disabled), styles (outline, pill, circle), icons, and can function as both a button and link.
@@ -25,6 +27,7 @@ import 'snice/components/button/snice-button';
 |----------|------|---------|-------------|
 | `variant` | `'default' \| 'primary' \| 'success' \| 'warning' \| 'danger' \| 'text'` | `'default'` | Visual style variant |
 | `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Button size |
+| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | Button type for form integration |
 | `disabled` | `boolean` | `false` | Disable the button |
 | `loading` | `boolean` | `false` | Show loading spinner |
 | `outline` | `boolean` | `false` | Use outline style |
@@ -77,6 +80,18 @@ The `icon` slot allows you to use external CSS-based icon fonts (like Material S
 
 > **Note**: When using the `icon` slot, the slotted content takes precedence over the `icon` property. The `iconPlacement` property still controls positioning.
 
+## Events
+
+#### `button-click`
+Fired when the button is clicked.
+
+**Event Detail:**
+```typescript
+{
+  originalEvent: MouseEvent;
+}
+```
+
 ## Methods
 
 #### `focus(options?: FocusOptions): void`

package/docs/components/calendar.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/calendar.md instead)
+
 # Calendar Component
 
 Display and select dates with event support.

package/docs/components/camera-annotate.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/camera-annotate.md instead)
+
 # Camera Annotate Component
 
 The camera annotate component combines camera capture with freehand drawing and labeled annotations. It provides a workflow for taking pictures, drawing shapes on them, and adding descriptive labels to each annotation.

package/docs/components/camera.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/camera.md instead)
+
 # Camera Component
 
 Live camera feed with built-in mobile-style controls and flexible positioning.

package/docs/components/candlestick.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/candlestick.md instead)
+
 # Candlestick Chart Component
 
 The candlestick chart component renders an SVG-based OHLC (Open-High-Low-Close) financial chart, commonly used for stock market and cryptocurrency price visualization. It supports volume bars, crosshair overlay, zoom/pan, tooltips, and responsive sizing.

package/docs/components/card.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/card.md instead)
+
 # Card Component
 
 The card component provides a container for grouped content with support for headers, footers, different visual styles, interactive states, and responsive sizing.

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.