snice 4.28.0 → 4.30.0

package/docs/components/grid.md

@@ -0,0 +1,249 @@
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/grid.md -->
+
+# Grid Component
+`<snice-grid>`
+
+A grid-coordinate layout component. Items are placed at explicit grid positions using `grid-col` and `grid-row` attributes, and can span multiple cells with `grid-colspan` and `grid-rowspan`. Collision resolution uses swap-first with push-right-then-down fallback. Supports animated transitions and drag-and-drop with snap-to-grid.
+
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [Slots](#slots)
+- [CSS Custom Properties](#css-custom-properties)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+|----------|-----------|------|---------|-------------|
+| `gap` | `gap` | `string` | `'1rem'` | Spacing between cells |
+| `columnWidth` | `column-width` | `number` | `80` | Width of each grid column in pixels |
+| `rowHeight` | `row-height` | `number` | `80` | Height of each grid row in pixels |
+| `columns` | `columns` | `number` | `0` | Fixed number of columns (0 = auto from content) |
+| `rows` | `rows` | `number` | `0` | Fixed number of rows (0 = auto from content) |
+| `originLeft` | `origin-left` | `boolean` | `true` | `false` = right-to-left |
+| `originTop` | `origin-top` | `boolean` | `true` | `false` = bottom-to-top |
+| `transitionDuration` | `transition-duration` | `string` | `'0.4s'` | CSS transition duration for item movement |
+| `stagger` | `stagger` | `number` | `0` | Delay in ms between each item's transition |
+| `resize` | `resize` | `boolean` | `true` | Auto re-layout on container resize |
+| `draggable` | `draggable` | `boolean` | `false` | Enable drag-to-reorder with snap-to-grid |
+| `dragThrottle` | `drag-throttle` | `number` | `120` | Throttle interval (ms) for drag layout updates |
+
+## Methods
+
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `layout()` | -- | Perform a full re-layout |
+| `fit()` | `element: HTMLElement, col?: number, row?: number` | Position specific item at grid coordinates, reflow others |
+| `reloadItems()` | -- | Re-collect items from DOM |
+| `getItemElements()` | -- | Returns array of all layout items |
+| `getLayout()` | -- | Returns `GridLayout` object with item positions, spans, and order |
+| `setLayout()` | `layout: GridLayout` | Apply a saved layout (reorder, reposition, hide/show items) |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `grid-layout-complete` | `{ items: HTMLElement[] }` | Fired after layout completes |
+| `grid-drag-item-positioned` | `{ item: HTMLElement, col: number, row: number }` | Fired after a dragged item settles into its new grid position |
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| (default) | Items to place on the grid. Use `grid-col`, `grid-row`, `grid-colspan`, `grid-rowspan` attributes on each item to control placement. |
+
+### Item Attributes
+
+These attributes are set on child elements (not on `<snice-grid>` itself):
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `grid-col` | `number` | `0` | Column position (0-based) |
+| `grid-row` | `number` | `0` | Row position (0-based) |
+| `grid-colspan` | `number` | `1` | Number of columns to span |
+| `grid-rowspan` | `number` | `1` | Number of rows to span |
+| `name` | `string` | -- | Identifier used by `getLayout()`/`setLayout()` for persistence |
+| `hidden` | `boolean` | -- | Hides the item from layout |
+
+## CSS Custom Properties
+
+| Property | Description | Default |
+|----------|-------------|---------|
+| `--grid-gap` | Gap between cells (set via `gap` property) | `1rem` |
+| `--grid-transition-duration` | Transition duration for item movement (set via `transition-duration` property) | `0.4s` |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `base` | The inner container element |
+
+## Basic Usage
+
+```typescript
+import 'snice/components/grid/snice-grid';
+```
+
+```html
+<snice-grid column-width="100" row-height="100" gap="8px">
+  <div grid-col="0" grid-row="0">A</div>
+  <div grid-col="1" grid-row="0">B</div>
+  <div grid-col="0" grid-row="1">C</div>
+</snice-grid>
+```
+
+Items are sized automatically based on `columnWidth`, `rowHeight`, and their `grid-colspan`/`grid-rowspan` values.
+
+## Examples
+
+### Spanning Multiple Cells
+
+Use `grid-colspan` and `grid-rowspan` to make items span multiple columns or rows.
+
+```html
+<snice-grid column-width="80" row-height="80" gap="8px">
+  <div grid-col="0" grid-row="0" grid-colspan="2" grid-rowspan="2">Large</div>
+  <div grid-col="2" grid-row="0">Small A</div>
+  <div grid-col="2" grid-row="1">Small B</div>
+  <div grid-col="0" grid-row="2" grid-colspan="3">Wide</div>
+</snice-grid>
+```
+
+### Collision Resolution
+
+When two items request the same grid position, the component resolves collisions automatically:
+
+1. **Swap** -- If the target cell has a single occupant, the two items swap positions.
+2. **Push-right-then-down** -- If swap fails (multiple occupants or the swapped item doesn't fit), the incoming item is pushed to the next free cell scanning right, then down.
+
+```html
+<snice-grid column-width="80" row-height="80" gap="8px">
+  <!-- Both request (0,0): the second item will be pushed to (1,0) -->
+  <div grid-col="0" grid-row="0">First</div>
+  <div grid-col="0" grid-row="0">Second</div>
+</snice-grid>
+```
+
+### Fixed Grid Size
+
+Set `columns` and/or `rows` to constrain the grid. Items that exceed the column limit are wrapped to the next row.
+
+```html
+<snice-grid column-width="100" row-height="100" gap="8px" columns="4" rows="3">
+  <div grid-col="0" grid-row="0">A</div>
+  <div grid-col="3" grid-row="0" grid-colspan="2">B (clamped to fit)</div>
+</snice-grid>
+```
+
+When an item's `col + colspan` exceeds the column count, its column position is clamped to `columns - colspan`.
+
+### Draggable with Snap-to-Grid
+
+Enable `draggable` to let users drag items. Items snap to the nearest grid cell during and after drag.
+
+```html
+<snice-grid draggable column-width="80" row-height="80" gap="8px" columns="4">
+  <div grid-col="0" grid-row="0" name="widget-a">Widget A</div>
+  <div grid-col="1" grid-row="0" name="widget-b">Widget B</div>
+  <div grid-col="0" grid-row="1" name="widget-c" grid-colspan="2">Widget C</div>
+</snice-grid>
+```
+
+A dashed drop-placeholder shows the target cell during drag. CSS classes applied during drag:
+
+- `.grid-dragging` -- applied during drag (no transition, z-index: 100, opacity: 0.9, cursor: grabbing)
+- `.grid-positioning` -- applied while animating to final position after drop (z-index: 99)
+
+```javascript
+const grid = document.querySelector('snice-grid');
+grid.addEventListener('grid-drag-item-positioned', (e) => {
+  const { item, col, row } = e.detail;
+  console.log(`${item.getAttribute('name')} dropped at col=${col} row=${row}`);
+});
+```
+
+### Staggered Transitions
+
+Use `stagger` to add incremental delay between each item's transition.
+
+```html
+<snice-grid column-width="80" row-height="80" transition-duration="0.6s" stagger="40">
+  <div grid-col="0" grid-row="0">A</div>
+  <div grid-col="1" grid-row="0">B</div>
+  <div grid-col="2" grid-row="0">C</div>
+</snice-grid>
+```
+
+### Right-to-Left / Bottom-to-Top
+
+Set `origin-left="false"` or `origin-top="false"` to change the coordinate origin.
+
+```html
+<snice-grid column-width="80" row-height="80" origin-left="false">
+  <div grid-col="0" grid-row="0">Aligned right</div>
+</snice-grid>
+```
+
+### Save and Restore Layout
+
+Use `getLayout()` and `setLayout()` to persist item arrangement. Items must have a `name` attribute.
+
+```javascript
+const grid = document.querySelector('snice-grid');
+
+// Save
+const layout = grid.getLayout();
+localStorage.setItem('dashboard', JSON.stringify(layout));
+
+// Restore
+const saved = JSON.parse(localStorage.getItem('dashboard'));
+grid.setLayout(saved);
+```
+
+The `GridLayout` object is a `Record<string, GridLayoutEntry>` keyed by item name:
+
+```typescript
+interface GridLayoutEntry {
+  col: number;
+  row: number;
+  colspan?: number;
+  rowspan?: number;
+  order: number;
+  hidden?: boolean;
+}
+```
+
+### Dynamic Items
+
+Items can be added or removed dynamically. The layout automatically updates via slot change detection.
+
+```javascript
+const grid = document.querySelector('snice-grid');
+
+// Add an item
+const item = document.createElement('div');
+item.setAttribute('grid-col', '2');
+item.setAttribute('grid-row', '0');
+grid.appendChild(item);
+
+// Remove an item
+grid.lastElementChild.remove();
+```
+
+## Accessibility
+
+- The inner container has `role="list"` for screen reader navigation.
+- When `draggable` is enabled, items show `cursor: grab` (and `cursor: grabbing` during drag).
+
+### Notes
+
+- Items are absolutely positioned using `transform` for smooth transitions.
+- Item width/height is computed automatically from `columnWidth`, `rowHeight`, `colspan`, and `rowspan`.
+- Uses `ResizeObserver` on the container for automatic re-layout when `resize` is `true`.
+- FOUC is prevented by gating transitions behind the `[ready]` attribute.
+- Uses `contain: layout style` on `:host`.

package/docs/components/heatmap.md

@@ -1,4 +1,4 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/heatmap.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/heatmap.md -->
 
 # Heatmap Component
 
@@ -10,21 +10,18 @@ The heatmap component displays a GitHub-style contribution calendar heatmap. It
 - [CSS Parts](#css-parts)
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
-- [Intensity Levels](#intensity-levels)
-- [Color Schemes](#color-schemes)
 - [Accessibility](#accessibility)
-- [Browser Support](#browser-support)
 
 ## Properties
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
 | `data` | `HeatmapDataPoint[]` | `[]` | Array of data points with date and value |
-| `color-scheme` | `'green' \| 'blue' \| 'purple' \| 'orange' \| 'red'` | `'green'` | Color scheme for intensity levels |
-| `show-labels` | `boolean` | `true` | Show day and month labels |
-| `cell-size` | `number` | `12` | Cell size in pixels |
-| `cell-gap` | `number` | `3` | Gap between cells in pixels |
-| `show-tooltip` | `boolean` | `true` | Show tooltip on cell hover |
+| `colorScheme` (attr: `color-scheme`) | `'green' \| 'blue' \| 'purple' \| 'orange' \| 'red'` | `'green'` | Color scheme for intensity levels |
+| `showLabels` (attr: `show-labels`) | `boolean` | `true` | Show day and month labels |
+| `cellSize` (attr: `cell-size`) | `number` | `12` | Cell size in pixels |
+| `cellGap` (attr: `cell-gap`) | `number` | `3` | Gap between cells in pixels |
+| `showTooltip` (attr: `show-tooltip`) | `boolean` | `true` | Show tooltip on cell hover |
 | `weeks` | `number` | `52` | Number of weeks to display |
 
 ### HeatmapDataPoint
@@ -38,21 +35,9 @@ interface HeatmapDataPoint {
 
 ## Events
 
-### `cell-click`
-
-Fired when a cell is clicked.
-
-```typescript
-heatmap.addEventListener('cell-click', (e: CustomEvent) => {
-  console.log(e.detail.date);  // '2026-01-15'
-  console.log(e.detail.value); // 5
-});
-```
-
-| Detail Property | Type | Description |
-|-----------------|------|-------------|
-| `date` | `string` | ISO date of the clicked cell |
-| `value` | `number` | Value of the clicked cell |
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `cell-click` | `{ date: string, value: number }` | Fired when a cell is clicked |
 
 ## CSS Parts
 
@@ -77,6 +62,10 @@ snice-heatmap::part(tooltip) {
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/heatmap/snice-heatmap';
+```
+
 ```html
 <snice-heatmap id="my-heatmap"></snice-heatmap>
 
@@ -90,10 +79,6 @@ snice-heatmap::part(tooltip) {
 </script>
 ```
 
-```typescript
-import 'snice/components/heatmap/snice-heatmap';
-```
-
 ## Examples
 
 ### Default Green Heatmap
@@ -167,36 +152,9 @@ import 'snice/components/heatmap/snice-heatmap';
 </script>
 ```
 
-## Intensity Levels
-
-Cell colors are calculated based on quartiles of the maximum value in the dataset:
-
-| Level | Range | Description |
-|-------|-------|-------------|
-| 0 | No data | Empty (gray) |
-| 1 | 1-25% of max | Low activity |
-| 2 | 26-50% of max | Medium activity |
-| 3 | 51-75% of max | High activity |
-| 4 | 76-100% of max | Very high activity |
-
-## Color Schemes
-
-| Scheme | Level 1 | Level 2 | Level 3 | Level 4 |
-|--------|---------|---------|---------|---------|
-| `green` | #9be9a8 | #40c463 | #30a14e | #216e39 |
-| `blue` | #9ecae1 | #4292c6 | #2171b5 | #084594 |
-| `purple` | #c9b1e0 | #9b72cf | #7b4fbf | #5a2d91 |
-| `orange` | #fdcc8a | #fc8d59 | #e34a33 | #b30000 |
-| `red` | #fcae91 | #fb6a4a | #de2d26 | #a50f15 |
-
 ## Accessibility
 
 - **ARIA labels**: Each cell has an `aria-label` describing the date and contribution count
 - **Keyboard navigation**: Cells are focusable buttons
 - **Tooltips**: Visual hover feedback with date and value details
 - **Color contrast**: Intensity levels are distinguishable at all levels
-
-## Browser Support
-
-- Modern browsers (Chrome, Firefox, Safari, Edge)
-- Requires Custom Elements v1 and Shadow DOM support

package/docs/components/image.md

@@ -1,4 +1,4 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/image.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/image.md -->
 
 # Image Component
 
@@ -6,9 +6,9 @@ The `<snice-image>` component provides a flexible image display with variants, s
 
 ## Table of Contents
 - [Properties](#properties)
+- [CSS Parts](#css-parts)
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
-- [CSS Parts](#css-parts)
 
 ## Properties
 
@@ -27,8 +27,34 @@ The `<snice-image>` component provides a flexible image display with variants, s
 | `width` | `string` | `''` | Custom width (CSS value) |
 | `height` | `string` | `''` | Custom height (CSS value) |
 
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `container` | Image container div |
+| `image` | The img element |
+| `placeholder` | Placeholder element (shown when loading or no src) |
+
+```css
+snice-image::part(container) {
+  /* Image container */
+}
+
+snice-image::part(image) {
+  /* The img element */
+}
+
+snice-image::part(placeholder) {
+  /* Placeholder element */
+}
+```
+
 ## Basic Usage
 
+```typescript
+import 'snice/components/image/snice-image';
+```
+
 ```html
 <snice-image
   src="https://example.com/image.jpg"
@@ -95,33 +121,3 @@ The `<snice-image>` component provides a flexible image display with variants, s
 <!-- Shows placeholder when no src -->
 <snice-image variant="circle" size="medium"></snice-image>
 ```
-
-## CSS Parts
-
-| Part | Description |
-|------|-------------|
-| `container` | Image container div |
-| `image` | The img element |
-| `placeholder` | Placeholder element (shown when loading or no src) |
-
-```css
-snice-image::part(container) {
-  /* Image container */
-}
-
-snice-image::part(image) {
-  /* The img element */
-}
-
-snice-image::part(placeholder) {
-  /* Placeholder element */
-}
-```
-
-## Notes
-
-- Images are lazy-loaded by default for better performance
-- Placeholder is shown when `src` is empty
-- Fallback image is used when main image fails to load
-- Size presets provide consistent image dimensions
-- Custom width/height override size presets

package/docs/components/input.md

@@ -1,22 +1,19 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/input.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/input.md -->
 
 # Input
 `<snice-input>`
 
 Text input field with validation, icons, and form association.
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/input/snice-input';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-input.min.js"></script>
-```
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [Slots](#slots)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Keyboard Navigation](#keyboard-navigation)
 
 ## Properties
 
@@ -153,7 +150,7 @@ Set the `password` attribute along with `type="password"` to show a visibility t
 
 For icon fonts (Material Symbols, Font Awesome, etc.), use the `prefix-icon` and `suffix-icon` **slots**. The `prefix-icon` and `suffix-icon` **attributes** are for emoji, URLs, and image files only.
 
-> **⚠️ `prefix-icon="search"` renders as plain text, not a Material icon.** Use the slot for icon fonts.
+> **`prefix-icon="search"` renders as plain text, not a Material icon.** Use the slot for icon fonts.
 
 #### Icon Slots (for icon fonts and SVGs)
 
@@ -278,3 +275,17 @@ Listen for input events using `input-input` and `input-change`.
 inp.addEventListener('input-input', (e) => console.log('Input:', e.detail.value));
 inp.addEventListener('input-change', (e) => console.log('Change:', e.detail.value));
 ```
+
+## Keyboard Navigation
+
+- **Tab**: Focus/unfocus the input
+- **Escape**: Clear input when `clearable` is set (via clear button)
+- Standard native input keyboard behavior applies
+
+## Accessibility
+
+- Form-associated custom element with `ElementInternals`
+- Label element linked to input
+- `aria-invalid` set when `invalid` is true
+- Required indicator (`*`) shown when `required` is set
+- Clear button and password toggle have `aria-label`

package/docs/components/invoice.md

@@ -1,21 +1,18 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/invoice.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/invoice.md -->
 
 # Invoice Component
 
 A professional invoice component with line items, automatic tax and discount calculations, status tracking, and QR code support. Supports multiple visual variants and customizable layouts.
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/invoice/snice-invoice';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-invoice.min.js"></script>
-```
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [Slots](#slots)
+- [CSS Parts](#css-parts)
+- [CSS Custom Properties](#css-custom-properties)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
 
 ## Properties
 
@@ -82,23 +79,6 @@ interface InvoiceItem {
 | `qr` | QR code content. Use for payment QR codes or links. |
 | (default) | Additional content rendered in the footer area |
 
-## CSS Custom Properties
-
-| Property | Default | Description |
-|----------|---------|-------------|
-| `--invoice-max-width` | `50rem` | Maximum width of invoice |
-| `--invoice-padding` | `2rem` | Internal padding |
-| `--invoice-bg` | `white` | Background color |
-| `--invoice-text` | `rgb(23 23 23)` | Text color |
-| `--invoice-text-secondary` | `rgb(82 82 82)` | Secondary text |
-| `--invoice-accent` | `rgb(37 99 235)` | Accent color |
-| `--invoice-border` | `rgb(226 226 226)` | Border color |
-| `--invoice-border-radius` | `0.5rem` | Border radius |
-| `--invoice-shadow` | `none` | Box shadow |
-| `--invoice-table-header-bg` | `transparent` | Table header background |
-| `--invoice-summary-width` | `16rem` | Summary column width |
-| `--invoice-qr-size` | `6rem` | QR code size |
-
 ## CSS Parts
 
 | Part | Description |
@@ -132,8 +112,29 @@ interface InvoiceItem {
 | `qr` | QR code element |
 | `footer` | Footer area |
 
+## CSS Custom Properties
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `--invoice-max-width` | `50rem` | Maximum width of invoice |
+| `--invoice-padding` | `2rem` | Internal padding |
+| `--invoice-bg` | `white` | Background color |
+| `--invoice-text` | `rgb(23 23 23)` | Text color |
+| `--invoice-text-secondary` | `rgb(82 82 82)` | Secondary text |
+| `--invoice-accent` | `rgb(37 99 235)` | Accent color |
+| `--invoice-border` | `rgb(226 226 226)` | Border color |
+| `--invoice-border-radius` | `0.5rem` | Border radius |
+| `--invoice-shadow` | `none` | Box shadow |
+| `--invoice-table-header-bg` | `transparent` | Table header background |
+| `--invoice-summary-width` | `16rem` | Summary column width |
+| `--invoice-qr-size` | `6rem` | QR code size |
+
 ## Basic Usage
 
+```typescript
+import 'snice/components/invoice/snice-invoice';
+```
+
 ```html
 <snice-invoice
   invoice-number="INV-2026-001"
@@ -249,18 +250,18 @@ interface InvoiceItem {
   invoice.from = { name: 'My Company' };
   invoice.to = { name: 'Customer' };
   invoice.items = [];
-  
+
   function addItem() {
     invoice.items = [
       ...invoice.items,
       { description: 'New Service', quantity: 1, unitPrice: 99 }
     ];
   }
-  
+
   function markPaid() {
     invoice.status = 'paid';
   }
-  
+
   invoice.addEventListener('invoice-status-change', (e) => {
     console.log('Status changed:', e.detail.oldStatus, '→', e.detail.newStatus);
   });