snice 4.27.0 → 4.29.0

package/docs/components/banner.md

@@ -1,8 +1,9 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/banner.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/banner.md -->
 
 # Banner Component
+`<snice-banner>`
 
-The `<snice-banner>` component displays fixed-position notification banners at the top or bottom of the viewport.
+The banner component displays fixed-position notification banners at the top or bottom of the viewport. Supports multiple variants, dismissible close button, and optional action button.
 
 ## Table of Contents
 - [Properties](#properties)
@@ -12,6 +13,7 @@ The `<snice-banner>` component displays fixed-position notification banners at t
 - [CSS Parts](#css-parts)
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
+- [Accessibility](#accessibility)
 
 ## Properties
 
@@ -21,32 +23,17 @@ The `<snice-banner>` component displays fixed-position notification banners at t
 | `position` | `'top' \| 'bottom'` | `'top'` | Position on screen |
 | `message` | `string` | `''` | Banner message |
 | `dismissible` | `boolean` | `true` | Show close button |
-| `icon` | `string` | `''` | Custom icon (default icons per variant) |
-| `actionText` | `string` | `''` | Action button text |
+| `icon` | `string` | `''` | Custom icon (emoji, URL, image file). Default icons per variant. |
+| `actionText` (attr: `action-text`) | `string` | `''` | Action button text |
 | `open` | `boolean` | `false` | Banner visibility |
 
 ## Methods
 
-#### `show(): void`
-Show the banner.
-
-```typescript
-banner.show();
-```
-
-#### `hide(): void`
-Hide the banner.
-
-```typescript
-banner.hide();
-```
-
-#### `toggle(): void`
-Toggle banner visibility.
-
-```typescript
-banner.toggle();
-```
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `show()` | -- | Show the banner |
+| `hide()` | -- | Hide the banner |
+| `toggle()` | -- | Toggle banner visibility |
 
 ## Events
 
@@ -58,9 +45,9 @@ banner.toggle();
 
 ## Slots
 
-| Slot Name | Description |
-|-----------|-------------|
-| `icon` | Custom icon content. Overrides the `icon` property and default variant icons. |
+| Name | Description |
+|------|-------------|
+| `icon` | Custom icon content. Overrides the `icon` property and default variant icons. Use for icon fonts. |
 | (default) | Additional content after the message |
 
 ### Icon Slot Usage
@@ -79,8 +66,6 @@ Use the `icon` slot for external CSS-based icon fonts:
 
 ## CSS Parts
 
-Style internal elements from outside the shadow DOM using `::part()`.
-
 | Part | Element | Description |
 |------|---------|-------------|
 | `banner` | `<div>` | The main banner container |
@@ -89,8 +74,22 @@ Style internal elements from outside the shadow DOM using `::part()`.
 | `action` | `<button>` | The action button (when `actionText` is set) |
 | `close` | `<button>` | The close/dismiss button |
 
+```css
+snice-banner::part(banner) {
+  font-size: 1rem;
+}
+
+snice-banner::part(action) {
+  font-weight: 600;
+}
+```
+
 ## Basic Usage
 
+```typescript
+import 'snice/components/banner/snice-banner';
+```
+
 ```html
 <snice-banner
   variant="info"
@@ -103,6 +102,8 @@ Style internal elements from outside the shadow DOM using `::part()`.
 
 ### Variants
 
+Use the `variant` attribute to set the banner style.
+
 ```html
 <snice-banner variant="info" message="Info message" open></snice-banner>
 <snice-banner variant="success" message="Success!" open></snice-banner>
@@ -112,13 +113,14 @@ Style internal elements from outside the shadow DOM using `::part()`.
 
 ### With Action Button
 
+Use `action-text` to show an action button. Listen for `banner-action` to handle clicks.
+
 ```html
 <snice-banner
   message="A new version is available"
   action-text="Update Now"
   open
 ></snice-banner>
-
 ```
 
 ```typescript
@@ -129,6 +131,8 @@ banner.addEventListener('banner-action', () => {
 
 ### Bottom Position
 
+Use `position="bottom"` to anchor the banner to the bottom of the viewport.
+
 ```html
 <snice-banner
   position="bottom"
@@ -140,6 +144,8 @@ banner.addEventListener('banner-action', () => {
 
 ### Not Dismissible
 
+Set `dismissible="false"` to hide the close button.
+
 ```html
 <snice-banner
   message="Maintenance mode active"
@@ -151,6 +157,8 @@ banner.addEventListener('banner-action', () => {
 
 ### Programmatic Control
 
+Use `show()`, `hide()`, and `toggle()` methods.
+
 ```html
 <snice-banner id="myBanner" message="Hello"></snice-banner>
 
@@ -158,3 +166,9 @@ banner.addEventListener('banner-action', () => {
 <button onclick="myBanner.hide()">Hide</button>
 <button onclick="myBanner.toggle()">Toggle</button>
 ```
+
+## Accessibility
+
+- **ARIA role**: Banner has `role="alert"` for screen reader announcements
+- **Close button**: Has `aria-label="Close"` for screen readers
+- **Keyboard accessible**: Close and action buttons are keyboard focusable

package/docs/components/binpack.md

@@ -0,0 +1,208 @@
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/binpack.md -->
+
+# Binpack Component
+`<snice-binpack>`
+
+A JavaScript-driven bin-packing layout component. Uses the maximal rectangles algorithm to efficiently pack items of varying sizes into a container with absolute positioning and smooth transitions.
+
+## 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)
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+|----------|-----------|------|---------|-------------|
+| `gap` | `gap` | `string` | `'1rem'` | Spacing between items |
+| `columnWidth` | `column-width` | `number` | `0` | Grid snap width (0 = no grid) |
+| `rowHeight` | `row-height` | `number` | `0` | Grid snap height (0 = no grid) |
+| `horizontal` | `horizontal` | `boolean` | `false` | Pack horizontally instead of vertically |
+| `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 |
+| `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, x?: number, y?: number` | Position specific item at coordinates, reflow others |
+| `reloadItems()` | -- | Re-collect items from DOM |
+| `stamp()` | `elements: HTMLElement \| HTMLElement[]` | Layout around fixed elements |
+| `unstamp()` | `elements: HTMLElement \| HTMLElement[]` | Remove stamp constraint |
+| `getItemElements()` | -- | Returns array of all layout items |
+| `getLayout()` | -- | Returns `BinpackLayout` object with item positions |
+| `setLayout()` | `layout: BinpackLayout` | Apply a saved layout (reorder, hide/show items) |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `binpack-layout-complete` | `{ items: HTMLElement[] }` | Fired after layout completes |
+| `binpack-fit-complete` | `{ item: HTMLElement, x: number, y: number }` | Fired after `fit()` completes |
+| `binpack-drag-item-positioned` | `{ item: HTMLElement, x: number, y: number }` | Fired after a dragged item settles into its new position |
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| (default) | Items to pack. Each item should have explicit width and height. |
+
+## CSS Custom Properties
+
+| Property | Description | Default |
+|----------|-------------|---------|
+| `--binpack-gap` | Gap between items (set via `gap` property) | `1rem` |
+| `--binpack-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/binpack/snice-binpack';
+```
+
+```html
+<snice-binpack gap="0.5rem">
+  <div style="width: 100px; height: 100px;">A</div>
+  <div style="width: 150px; height: 80px;">B</div>
+  <div style="width: 80px; height: 120px;">C</div>
+</snice-binpack>
+```
+
+## Examples
+
+### Horizontal Packing
+
+Use the `horizontal` attribute to pack items left-to-right instead of top-to-bottom. Set a fixed height on the container.
+
+```html
+<snice-binpack horizontal gap="0.5rem" style="height: 300px;">
+  <div style="width: 100px; height: 100px;">A</div>
+  <div style="width: 80px; height: 150px;">B</div>
+  <div style="width: 120px; height: 80px;">C</div>
+</snice-binpack>
+```
+
+### Grid-Snapped Layout
+
+Use `column-width` and `row-height` to snap items to a grid.
+
+```html
+<snice-binpack column-width="100" row-height="100" gap="0.5rem">
+  <div style="width: 80px; height: 80px;">A</div>
+  <div style="width: 180px; height: 80px;">B</div>
+  <div style="width: 80px; height: 160px;">C</div>
+</snice-binpack>
+```
+
+### Staggered Transitions
+
+Use `stagger` to add incremental delay between each item's transition.
+
+```html
+<snice-binpack transition-duration="0.6s" stagger="40">
+  <div style="width: 100px; height: 100px;">A</div>
+  <div style="width: 100px; height: 100px;">B</div>
+  <div style="width: 100px; height: 100px;">C</div>
+</snice-binpack>
+```
+
+### Right-to-Left
+
+Set `origin-left="false"` to pack items from the right side.
+
+```html
+<snice-binpack origin-left="false" gap="0.5rem">
+  <div style="width: 100px; height: 100px;">A</div>
+  <div style="width: 150px; height: 80px;">B</div>
+</snice-binpack>
+```
+
+### Draggable Dashboard
+
+Enable `draggable` to let users drag items to rearrange them.
+
+```html
+<snice-binpack draggable gap="8px" column-width="80" row-height="80">
+  <div style="width: 160px; height: 160px;">Revenue</div>
+  <div style="width: 80px; height: 80px;">CPU</div>
+  <div style="width: 160px; height: 80px;">Orders</div>
+</snice-binpack>
+```
+
+CSS classes applied during drag:
+- `.binpack-dragging` -- applied during drag (no transition, z-index: 100)
+- `.binpack-positioning` -- applied while animating to final position after drop
+
+```javascript
+pack.addEventListener('binpack-drag-item-positioned', (e) => {
+  const { item, x, y } = e.detail;
+  console.log('Item dropped at', x, y);
+});
+```
+
+### Dynamic Items
+
+Items can be added or removed dynamically. The layout automatically updates via slot change detection.
+
+```javascript
+const pack = document.querySelector('snice-binpack');
+
+// Add an item
+const item = document.createElement('div');
+item.style.width = '120px';
+item.style.height = '80px';
+pack.appendChild(item);
+
+// Remove an item
+pack.lastElementChild.remove();
+```
+
+### Stamp (Fixed Elements)
+
+Use `stamp()` to mark elements as fixed -- other items layout around them.
+
+```javascript
+const pack = document.getElementById('stamp-demo');
+const fixed = document.getElementById('fixed');
+pack.stamp(fixed);    // Items layout around it
+pack.unstamp(fixed);  // Resume normal layout
+```
+
+### Save and Restore Layout
+
+Use `getLayout()` and `setLayout()` to persist item arrangement. Items must have a `name` attribute.
+
+```javascript
+// Save
+const layout = pack.getLayout();
+localStorage.setItem('dashboard', JSON.stringify(layout));
+
+// Restore
+const saved = JSON.parse(localStorage.getItem('dashboard'));
+pack.setLayout(saved);
+```
+
+### Notes
+
+- Items must have explicit `width` and `height` (the component does not auto-size items)
+- The container uses `position: relative` and items are absolutely positioned with `transform` for smooth transitions
+- Uses `ResizeObserver` on both the container and individual items for automatic re-layout
+- FOUC is prevented by gating transitions behind the `[ready]` attribute
+- Uses `contain: layout style` on `:host` (not `paint`, as items use absolute positioning that may overflow)

package/docs/components/book.md

@@ -1,10 +1,12 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/book.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/book.md -->
 
 # Book Component
+`<snice-book>`
 
-The book component displays content as a page-flipping book with realistic 3D page-turn animations. It supports a customizable cover page, keyboard and touch navigation, and programmatic page control.
+The book component displays content as a page-flipping book with realistic 3D page-turn animations. It supports a customizable cover page, keyboard navigation, and programmatic page control.
 
 ## Table of Contents
+- [Components](#components)
 - [Properties](#properties)
 - [Methods](#methods)
 - [Events](#events)
@@ -13,17 +15,26 @@ The book component displays content as a page-flipping book with realistic 3D pa
 - [CSS Parts](#css-parts)
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
+- [Keyboard Navigation](#keyboard-navigation)
 - [Accessibility](#accessibility)
 
+## Components
+
+### `<snice-book>`
+Main book container with page-flip animation.
+
+### `<snice-book-page>`
+Individual page element. Each child becomes one page in the book. Supports `front` and `back` named slots for double-sided pages.
+
 ## Properties
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `currentPage` (attr: `current-page`) | `number` | `0` | Current page number (0-indexed) |
+| `currentPage` (attr: `current-page`) | `number` | `0` | Current page number (0 = cover closed) |
 | `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) |
+| `totalPages` | `number` | _(read-only)_ | Total number of pages (count of slotted `<snice-book-page>` elements) |
 
 ## Methods
 
@@ -47,24 +58,22 @@ The book component displays content as a page-flipping book with realistic 3D pa
 
 | Name | Description |
 |------|-------------|
-| (default) | Page elements. Each child element becomes one page in the book. |
+| (default) | `<snice-book-page>` elements. Each child element becomes one page in the book. |
 
 ## CSS Custom Properties
 
-| Property | Description |
-|----------|-------------|
-| `--page-bg` | Page background color (default: `#F5F5F5`) |
-| `--dark-text` | Primary text color (default: `#2A2935`) |
-| `--baseline` | Base spacing unit (default: `12px`) |
-| `--book-title` | Book title font family (default: `'Tulpen One', sans-serif`) |
-| `--title` | Section title / body heading font (default: `'Cormorant Garamond', serif`) |
-| `--body` | Body text font (default: `'Cormorant Garamond', serif`) |
-| `--base-size` | Base font size, derived from baseline (default: `calc(var(--baseline) * 1.2)`) |
+| Property | Description | Default |
+|----------|-------------|---------|
+| `--page-bg` | Page background color | `#F5F5F5` |
+| `--dark-text` | Primary text color | `#2A2935` |
+| `--baseline` | Base spacing unit | `12px` |
+| `--book-title` | Book title font family | `'Tulpen One', sans-serif` |
+| `--title` | Section title / body heading font | `'Cormorant Garamond', serif` |
+| `--body` | Body text font | `'Cormorant Garamond', serif` |
+| `--base-size` | Base font size, derived from baseline | `calc(var(--baseline) * 1.2)` |
 
 ## CSS Parts
 
-Style internal elements from outside the shadow DOM using `::part()`.
-
 | Part | Element | Description |
 |------|---------|-------------|
 | `base` | `<div>` | The outer cover container |
@@ -83,18 +92,24 @@ snice-book::part(book) {
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/book/snice-book';
+```
+
 ```html
 <snice-book>
-  <div>Page 1 content</div>
-  <div>Page 2 content</div>
-  <div>Page 3 content</div>
+  <snice-book-page>
+    <div>Page 1 content</div>
+  </snice-book-page>
+  <snice-book-page>
+    <div>Page 2 content</div>
+  </snice-book-page>
+  <snice-book-page>
+    <div>Page 3 content</div>
+  </snice-book-page>
 </snice-book>
 ```
 
-```typescript
-import 'snice/components/book/snice-book';
-```
-
 ## Examples
 
 ### Basic Book with Cover
@@ -103,10 +118,12 @@ Use the `title`, `author`, and `cover-image` attributes to create a book with a
 
 ```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-page>
+    <div>In my younger and more vulnerable years...</div>
+  </snice-book-page>
+  <snice-book-page>
+    <div>Chapter 2 content here...</div>
+  </snice-book-page>
 </snice-book>
 ```
 
@@ -116,23 +133,20 @@ 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-page><div>Step 1: Install</div></snice-book-page>
+  <snice-book-page><div>Step 2: Import</div></snice-book-page>
+  <snice-book-page><div>Step 3: Use</div></snice-book-page>
 </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>
+```typescript
+const book = document.getElementById('tutorial-book');
+book.addEventListener('page-turn', (e) => {
+  console.log(`Turned to page ${e.detail.page} (${e.detail.direction})`);
+});
 ```
 
 ### Rich HTML Content Pages
@@ -141,26 +155,33 @@ Each page can contain arbitrary HTML including text, images, and interactive ele
 
 ```html
 <snice-book title="Product Catalog">
-  <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-page>
+    <div style="padding: 2rem;">
+      <h2>Introduction</h2>
+      <p>Browse our latest collection.</p>
+    </div>
+  </snice-book-page>
+  <snice-book-page>
+    <div style="padding: 2rem;">
+      <h3>Widget Pro</h3>
+      <img src="/products/widget-pro.jpg" alt="Widget Pro" style="width: 100%;">
+      <p>Starting at $29.99.</p>
+    </div>
+  </snice-book-page>
 </snice-book>
 ```
 
+## Keyboard Navigation
+
+| Key | Action |
+|-----|--------|
+| Arrow Right | Next page |
+| Arrow Left | Previous page |
+
+The book must be focused (it sets `tabindex="0"` on ready).
+
 ## 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
+- **Keyboard support**: Arrow keys for page navigation when focused
+- **Focus management**: The book is focusable and responds to keyboard input
+- **Screen readers**: Page turn events provide feedback on current position