snice 4.9.0 → 4.10.0

package/docs/components/pagination.md

@@ -1,166 +1,75 @@
-# Pagination Component
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/pagination.md instead)
 
-The `<snice-pagination>` component provides a flexible pagination interface for navigating through large datasets or multi-page content.
+# Pagination
+`<snice-pagination>`
 
-## Table of Contents
-- [Basic Usage](#basic-usage)
-- [Properties](#properties)
-- [Methods](#methods)
-- [Events](#events)
-- [Variants](#variants)
-- [Examples](#examples)
+A pagination navigation component for navigating through multi-page content.
 
 ## Basic Usage
 
-```html
-<snice-pagination current="1" total="10"></snice-pagination>
-```
-
 ```typescript
 import 'snice/components/pagination/snice-pagination';
-
-const pagination = document.querySelector('snice-pagination');
-pagination.addEventListener('pagination-change', (e) => {
-  console.log('Page changed to:', e.detail.page);
-});
 ```
 
-## Properties
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `current` | `number` | `1` | The currently active page number |
-| `total` | `number` | `1` | Total number of pages |
-| `siblings` | `number` | `1` | Number of page buttons to show on each side of current page |
-| `showFirst` | `boolean` | `true` | Whether to show the "First" button |
-| `showLast` | `boolean` | `true` | Whether to show the "Last" button |
-| `showPrev` | `boolean` | `true` | Whether to show the "Previous" button |
-| `showNext` | `boolean` | `true` | Whether to show the "Next" button |
-| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Size variant of the pagination |
-| `variant` | `'default' \| 'rounded' \| 'text'` | `'default'` | Visual style variant |
-
-## Methods
-
-### `goToPage(page: number): void`
-Navigate to a specific page number.
-
-```typescript
-pagination.goToPage(5);
-```
-
-### `nextPage(): void`
-Navigate to the next page (if not on last page).
-
-```typescript
-pagination.nextPage();
-```
-
-### `previousPage(): void`
-Navigate to the previous page (if not on first page).
-
-```typescript
-pagination.previousPage();
-```
-
-### `firstPage(): void`
-Navigate to the first page.
-
-```typescript
-pagination.firstPage();
+```html
+<snice-pagination current="1" total="10"></snice-pagination>
 ```
 
-### `lastPage(): void`
-Navigate to the last page.
+## Importing
 
+**ESM (bundler)**
 ```typescript
-pagination.lastPage();
+import 'snice/components/pagination/snice-pagination';
 ```
 
-## Events
-
-### `pagination-change`
-Fired when the page changes.
-
-**Event Detail:**
-```typescript
-{
-  page: number;        // New page number
-  previousPage: number; // Previous page number
-}
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-pagination.min.js"></script>
 ```
 
-**Usage:**
-```typescript
-pagination.addEventListener('pagination-change', (e) => {
-  const { page, previousPage } = e.detail;
-  console.log(`Changed from page ${previousPage} to ${page}`);
-});
-```
+## Examples
 
-## Variants
+### Sizes
 
-### Size Variants
+Use the `size` attribute to change the pagination size.
 
 ```html
-<!-- Small -->
 <snice-pagination total="10" size="small"></snice-pagination>
-
-<!-- Medium (default) -->
 <snice-pagination total="10" size="medium"></snice-pagination>
-
-<!-- Large -->
 <snice-pagination total="10" size="large"></snice-pagination>
 ```
 
-### Style Variants
+### Variants
+
+Use the `variant` attribute to change the visual style.
 
 ```html
-<!-- Default (squared corners) -->
 <snice-pagination total="10" variant="default"></snice-pagination>
-
-<!-- Rounded (circular buttons) -->
 <snice-pagination total="10" variant="rounded"></snice-pagination>
-
-<!-- Text (minimal styling) -->
 <snice-pagination total="10" variant="text"></snice-pagination>
 ```
 
-## Examples
-
-### Basic Pagination
-
-```html
-<snice-pagination
-  current="1"
-  total="20">
-</snice-pagination>
-```
-
 ### Controlling Siblings
 
-The `siblings` property controls how many page buttons appear on each side of the current page.
+Use the `siblings` attribute to set how many page buttons appear on each side of the current page.
 
 ```html
-<!-- Show 1 page on each side (default) -->
-<!-- Current: 5 → Shows: [1] ... [4] [5] [6] ... [20] -->
+<!-- 1 page each side (default): [1] ... [4] [5] [6] ... [20] -->
 <snice-pagination current="5" total="20" siblings="1"></snice-pagination>
 
-<!-- Show 3 pages on each side -->
-<!-- Current: 10 → Shows: [1] ... [7] [8] [9] [10] [11] [12] [13] ... [20] -->
+<!-- 3 pages each side: [1] ... [7] [8] [9] [10] [11] [12] [13] ... [20] -->
 <snice-pagination current="10" total="20" siblings="3"></snice-pagination>
 ```
 
 ### Without Navigation Buttons
 
+Hide the first, last, previous, or next buttons as needed.
+
 ```html
-<!-- No first/last buttons -->
-<snice-pagination
-  total="10"
-  show-first="false"
-  show-last="false">
-</snice-pagination>
+<snice-pagination total="10" show-first="false" show-last="false"></snice-pagination>
 
-<!-- Only page numbers -->
+<!-- Page numbers only -->
 <snice-pagination
   total="10"
   show-first="false"
@@ -170,120 +79,68 @@ The `siblings` property controls how many page buttons appear on each side of th
 </snice-pagination>
 ```
 
-### Programmatic Navigation
+### Event Handling
 
-```typescript
-import type { SnicePaginationElement } from 'snice/components/pagination/snice-pagination.types';
-
-const pagination = document.querySelector<SnicePaginationElement>('snice-pagination');
-
-// Navigate to specific page
-pagination.goToPage(7);
+```html
+<snice-pagination id="pager" total="20"></snice-pagination>
 
-// Navigate step by step
-pagination.nextPage();
-pagination.previousPage();
+<script type="module">
+  import 'snice/components/pagination/snice-pagination';
 
-// Jump to extremes
-pagination.firstPage();
-pagination.lastPage();
+  document.getElementById('pager').addEventListener('pagination-change', (e) => {
+    console.log(`Page ${e.detail.previousPage} → ${e.detail.page}`);
+  });
+</script>
 ```
 
-### With Event Handling
+### Programmatic Control
 
 ```typescript
 const pagination = document.querySelector('snice-pagination');
 
-pagination.addEventListener('pagination-change', (e) => {
-  const { page } = e.detail;
-
-  // Fetch data for the new page
-  fetchPageData(page);
-});
-
-async function fetchPageData(page: number) {
-  const response = await fetch(`/api/data?page=${page}`);
-  const data = await response.json();
-  renderData(data);
-}
-```
-
-### Custom Styling with CSS Variables
-
-```html
-<style>
-  snice-pagination {
-    --pagination-gap: 8px;
-    --pagination-button-size: 40px;
-    --pagination-button-padding: 12px;
-    --pagination-font-size: 16px;
-    --pagination-border-radius: 8px;
-  }
-</style>
-
-<snice-pagination total="10"></snice-pagination>
+pagination.goToPage(5);
+pagination.nextPage();
+pagination.previousPage();
+pagination.firstPage();
+pagination.lastPage();
 ```
 
-### Complete Example
-
-```html
-<!DOCTYPE html>
-<html>
-<head>
-  <script type="module">
-    import 'snice/components/pagination/snice-pagination';
-
-    const pagination = document.querySelector('snice-pagination');
-    const dataContainer = document.querySelector('#data');
-    const itemsPerPage = 10;
-
-    // Sample data
-    const allData = Array.from({ length: 100 }, (_, i) => ({
-      id: i + 1,
-      name: `Item ${i + 1}`
-    }));
-
-    // Update total pages
-    pagination.total = Math.ceil(allData.length / itemsPerPage);
-
-    // Render data for current page
-    function renderPage(page) {
-      const start = (page - 1) * itemsPerPage;
-      const end = start + itemsPerPage;
-      const pageData = allData.slice(start, end);
-
-      dataContainer.innerHTML = pageData
-        .map(item => `<div>${item.id}. ${item.name}</div>`)
-        .join('');
-    }
-
-    // Listen for page changes
-    pagination.addEventListener('pagination-change', (e) => {
-      renderPage(e.detail.page);
-    });
-
-    // Render initial page
-    renderPage(1);
-  </script>
-</head>
-<body>
-  <div id="data"></div>
-  <snice-pagination current="1"></snice-pagination>
-</body>
-</html>
-```
+## Properties
 
-## Accessibility
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `current` | `number` | `1` | Active page number |
+| `total` | `number` | `1` | Total number of pages |
+| `siblings` | `number` | `1` | Page buttons on each side of current |
+| `showFirst` (attr: `show-first`) | `boolean` | `true` | Show "First" button |
+| `showLast` (attr: `show-last`) | `boolean` | `true` | Show "Last" button |
+| `showPrev` (attr: `show-prev`) | `boolean` | `true` | Show "Previous" button |
+| `showNext` (attr: `show-next`) | `boolean` | `true` | Show "Next" button |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Pagination size |
+| `variant` | `'default' \| 'rounded' \| 'text'` | `'default'` | Visual style |
 
-The pagination component includes proper ARIA attributes:
+## Events
 
-- `role="navigation"` on the container
-- `aria-label="Pagination"` on the nav element
-- `aria-label` on each button describing its action
-- `aria-current="page"` on the active page button
-- `disabled` state for unavailable navigation buttons
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `pagination-change` | `{ page: number, previousPage: number }` | Fired when the page changes |
 
-## Browser Support
+## Methods
 
-- Modern browsers (Chrome, Firefox, Safari, Edge)
-- Requires Custom Elements v1 and Shadow DOM support
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `goToPage()` | `page: number` | Navigate to a specific page |
+| `nextPage()` | -- | Go to the next page |
+| `previousPage()` | -- | Go to the previous page |
+| `firstPage()` | -- | Go to the first page |
+| `lastPage()` | -- | Go to the last page |
+
+## CSS Custom Properties
+
+| Property | Description | Default |
+|----------|-------------|---------|
+| `--pagination-gap` | Gap between buttons | `4px` |
+| `--pagination-button-size` | Button dimensions | `32px` |
+| `--pagination-button-padding` | Button padding | `8px` |
+| `--pagination-font-size` | Font size | `14px` |
+| `--pagination-border-radius` | Button border radius | `4px` |

package/docs/components/paint.md

@@ -1,129 +1,128 @@
-# Paint Component
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/paint.md instead)
 
-Self-contained drawing canvas with a built-in toolbar. Includes color swatches, brush size slider, eraser toggle, undo/redo, and clear — all rendered inside the component's shadow DOM.
+# Paint
+`<snice-paint>`
+
+A self-contained drawing canvas with a built-in toolbar for color selection, brush sizing, eraser, undo/redo, and export.
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/paint/snice-paint';
+```
+
 ```html
 <snice-paint></snice-paint>
 ```
 
-The component renders a vertical toolbar on the left and a drawing canvas filling the remaining space.
+## Importing
 
-## Properties
-
-| Property | Type | Default | Attribute | Description |
-|----------|------|---------|-----------|-------------|
-| `colors` | `string[]` | 8 default colors | `colors` | Color palette (JSON array) |
-| `color` | `string` | `'#3b82f6'` | `color` | Current brush color |
-| `strokeWidth` | `number` | `3` | `stroke-width` | Brush width |
-| `minStrokeWidth` | `number` | `1` | `min-stroke-width` | Min slider value |
-| `maxStrokeWidth` | `number` | `20` | `max-stroke-width` | Max slider value |
-| `controls` | `string` | `'colors,size,eraser,undo,redo,clear'` | `controls` | Visible toolbar controls |
-| `backgroundColor` | `string` | `'#ffffff'` | `background-color` | Canvas background |
-| `disabled` | `boolean` | `false` | `disabled` | Disable all interaction |
+**ESM (bundler)**
+```typescript
+import 'snice/components/paint/snice-paint';
+```
 
-## Controls
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-paint.min.js"></script>
+```
 
-The `controls` attribute accepts a comma-separated list of toolbar sections to show:
+## Examples
 
-- `colors` — Color swatch grid
-- `size` — Brush size slider
-- `eraser` — Eraser toggle button
-- `undo` — Undo button
-- `redo` — Redo button
-- `clear` — Clear canvas button
+### Custom Colors
 
-### Minimal Toolbar
+Use the `colors` attribute with a JSON array to set the palette.
 
 ```html
-<snice-paint controls="colors,undo"></snice-paint>
+<snice-paint colors='["#ff0000","#00ff00","#0000ff","#ffff00"]'></snice-paint>
 ```
 
-### No Toolbar
+### Custom Size Range
+
+Use `min-stroke-width` and `max-stroke-width` to control the brush slider range.
 
 ```html
-<snice-paint controls=""></snice-paint>
+<snice-paint min-stroke-width="2" max-stroke-width="50" stroke-width="10"></snice-paint>
 ```
 
-## Methods
-
-### `undo(): void`
-Undo the last stroke.
-
-### `redo(): void`
-Redo the last undone stroke.
-
-### `clear(): void`
-Clear the entire canvas.
-
-### `toDataURL(type?, quality?): string`
-Export as a data URL.
-
-### `toBlob(type?, quality?): Promise<Blob>`
-Export as a Blob.
+### Minimal Toolbar
 
-### `download(filename?): void`
-Download the painting as a PNG file.
+Use the `controls` attribute with a comma-separated list to show only specific controls.
 
-### `getStrokes(): PaintStroke[]`
-Get all strokes for serialization.
+```html
+<snice-paint controls="colors,undo"></snice-paint>
+```
 
-### `setStrokes(strokes): void`
-Restore strokes from a previous session.
+### No Toolbar
 
-## Events
+Pass an empty string to hide the toolbar entirely.
 
-- `paint-start` — Drawing started (`detail: { point }`)
-- `paint-end` — Stroke completed (`detail: { stroke }`)
-- `paint-clear` — Canvas cleared
-- `paint-undo` — Undo performed
-- `paint-redo` — Redo performed
+```html
+<snice-paint controls=""></snice-paint>
+```
 
-## Examples
+### Disabled
 
-### Custom Colors
+Set the `disabled` attribute to prevent all interaction.
 
 ```html
-<snice-paint colors='["#ff0000","#00ff00","#0000ff","#ffff00"]'></snice-paint>
+<snice-paint disabled></snice-paint>
 ```
 
-### Custom Size Range
+### Custom Background
+
+Use the `background-color` attribute to change the canvas background.
 
 ```html
-<snice-paint min-stroke-width="2" max-stroke-width="50" stroke-width="10"></snice-paint>
+<snice-paint background-color="#f0f0f0"></snice-paint>
 ```
 
 ### Programmatic Control
 
-```javascript
+```typescript
 const paint = document.querySelector('snice-paint');
 
-// Change color
+// Change settings
 paint.color = '#ff6600';
-
-// Change brush size
 paint.strokeWidth = 8;
 
+// Undo / redo / clear
+paint.undo();
+paint.redo();
+paint.clear();
+
 // Export
 paint.download('my-painting.png');
 const dataURL = paint.toDataURL('image/png');
 const blob = await paint.toBlob('image/jpeg', 0.9);
+```
+
+### Save and Restore Strokes
 
-// Save / load
+```typescript
+const paint = document.querySelector('snice-paint');
+
+// Save strokes
 const strokes = paint.getStrokes();
 localStorage.setItem('painting', JSON.stringify(strokes));
 
+// Restore strokes
 const saved = JSON.parse(localStorage.getItem('painting'));
 paint.setStrokes(saved);
 ```
 
 ### Event Handling
 
-```javascript
+```typescript
+const paint = document.querySelector('snice-paint');
+
 paint.addEventListener('paint-end', (e) => {
-  const stroke = e.detail.stroke;
-  console.log(`Stroke with ${stroke.points.length} points`);
+  console.log(`Stroke with ${e.detail.stroke.points.length} points`);
+});
+
+paint.addEventListener('paint-clear', () => {
+  console.log('Canvas cleared');
 });
 ```
 
@@ -131,11 +130,47 @@ paint.addEventListener('paint-end', (e) => {
 
 ```typescript
 interface PaintStroke {
-  id: string;           // Unique identifier
+  id: string;
   tool: 'pen' | 'eraser';
-  color: string;        // Hex color
-  width: number;        // Stroke width
-  points: Point[];      // Array of {x, y}
-  timestamp: number;    // Creation time (ms)
+  color: string;
+  width: number;
+  points: Point[];     // Array of { x, y }
+  timestamp: number;
 }
 ```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `colors` | `string[]` | 8 default colors | Color palette (set via JSON attribute) |
+| `color` | `string` | `'#3b82f6'` | Current brush color |
+| `strokeWidth` (attr: `stroke-width`) | `number` | `3` | Brush stroke width |
+| `minStrokeWidth` (attr: `min-stroke-width`) | `number` | `1` | Minimum slider value |
+| `maxStrokeWidth` (attr: `max-stroke-width`) | `number` | `20` | Maximum slider value |
+| `controls` | `string` | `'colors,size,eraser,undo,redo,clear'` | Visible toolbar sections |
+| `backgroundColor` (attr: `background-color`) | `string` | `'#ffffff'` | Canvas background color |
+| `disabled` | `boolean` | `false` | Disable all interaction |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `paint-start` | `{ point: Point }` | Drawing started |
+| `paint-end` | `{ stroke: PaintStroke }` | Stroke completed |
+| `paint-clear` | -- | Canvas cleared |
+| `paint-undo` | -- | Undo performed |
+| `paint-redo` | -- | Redo performed |
+
+## Methods
+
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `undo()` | -- | Undo the last stroke |
+| `redo()` | -- | Redo the last undone stroke |
+| `clear()` | -- | Clear the entire canvas |
+| `toDataURL()` | `type?: string, quality?: number` | Export as data URL |
+| `toBlob()` | `type?: string, quality?: number` | Export as Blob (async) |
+| `download()` | `filename?: string` | Download as PNG file |
+| `getStrokes()` | -- | Get all strokes for serialization |
+| `setStrokes()` | `strokes: PaintStroke[]` | Restore strokes from saved data |