snice 4.27.0 → 4.29.0

package/docs/ai/components/banner.md

@@ -9,16 +9,11 @@ variant: 'info'|'success'|'warning'|'error' = 'info';
 position: 'top'|'bottom' = 'top';
 message: string = '';
 dismissible: boolean = true;
-icon: string = '';
-actionText: string = '';
+icon: string = '';                    // emoji, URL, image file
+actionText: string = '';              // attr: action-text
 open: boolean = false;
 ```
 
-## Slots
-
-- `(default)` - Additional content after the message
-- `icon` - Custom icon content (overrides `icon` property and default variant icons)
-
 ## Methods
 
 - `show()` - Show banner
@@ -27,9 +22,14 @@ open: boolean = false;
 
 ## Events
 
-- `banner-open` → `{ banner }`
-- `banner-close` → `{ banner }`
-- `banner-action` → `{ banner }`
+- `banner-open` -> `{ banner }`
+- `banner-close` -> `{ banner }`
+- `banner-action` -> `{ banner }`
+
+## Slots
+
+- `(default)` - Additional content after the message
+- `icon` - Custom icon content (overrides `icon` property and default variant icons)
 
 ## CSS Parts
 
@@ -39,49 +39,32 @@ open: boolean = false;
 - `action` - Action button
 - `close` - Close/dismiss button
 
-## Usage
+## Basic Usage
 
 ```html
-<!-- Basic -->
 <snice-banner message="This is an info message" open></snice-banner>
 
 <!-- Variants -->
-<snice-banner variant="info" message="Info"></snice-banner>
-<snice-banner variant="success" message="Success"></snice-banner>
-<snice-banner variant="warning" message="Warning"></snice-banner>
-<snice-banner variant="error" message="Error"></snice-banner>
+<snice-banner variant="success" message="Success" open></snice-banner>
+<snice-banner variant="warning" message="Warning" open></snice-banner>
+<snice-banner variant="error" message="Error" open></snice-banner>
 
 <!-- Position -->
-<snice-banner position="top" message="Top banner" open></snice-banner>
 <snice-banner position="bottom" message="Bottom banner" open></snice-banner>
 
 <!-- With action -->
-<snice-banner
-  message="Update available"
-  action-text="Update Now"
-  open
-></snice-banner>
+<snice-banner message="Update available" action-text="Update Now" open></snice-banner>
 
 <!-- Not dismissible -->
-<snice-banner
-  message="Important notice"
-  dismissible="false"
-  open
-></snice-banner>
-
-<!-- ⚠️ icon="update" renders as PLAIN TEXT. Use the icon slot for icon fonts. -->
+<snice-banner message="Important" dismissible="false" open></snice-banner>
 
-<!-- Icon SLOT — for Material Symbols, Font Awesome, SVGs -->
+<!-- Icon SLOT for icon fonts -->
 <snice-banner message="Update available" open>
   <span slot="icon" class="material-symbols-outlined">update</span>
 </snice-banner>
 
-<!-- Icon PROPERTY — for emoji, URLs, image files only -->
+<!-- Icon PROPERTY for emoji/URLs -->
 <snice-banner icon="🎉" message="Celebration!" open></snice-banner>
-<snice-banner icon="/icons/update.svg" message="Update" open></snice-banner>
-
-<!-- API -->
-<snice-banner message="Hello"></snice-banner>
 ```
 
 ```typescript
@@ -90,12 +73,7 @@ banner.hide();
 banner.toggle();
 ```
 
-## Features
+## Accessibility
 
-- 4 variants (info, success, warning, error)
-- Top or bottom positioning
-- Dismissible with close button
-- Optional action button
-- Smooth slide animation
-- Fixed positioning
-- Accessible (role=alert)
+- `role="alert"` on banner container
+- `aria-label="Close"` on dismiss button

package/docs/ai/components/binpack.md

@@ -0,0 +1,89 @@
+# snice-binpack
+
+JS-driven bin-packing layout using the maximal rectangles algorithm. Absolute positioning with transform-based transitions.
+
+## Properties
+
+```typescript
+gap: string = '1rem';                           // spacing between items
+columnWidth: number = 0;                        // grid snap width (0 = no grid) -- attr: column-width
+rowHeight: number = 0;                          // grid snap height (0 = no grid) -- attr: row-height
+horizontal: boolean = false;                    // pack horizontally instead of vertically
+originLeft: boolean = true;                     // false = right-to-left -- attr: origin-left
+originTop: boolean = true;                      // false = bottom-to-top -- attr: origin-top
+transitionDuration: string = '0.4s';            // CSS transition duration -- attr: transition-duration
+stagger: number = 0;                            // ms delay between each item transition
+resize: boolean = true;                         // auto re-layout on container resize
+draggable: boolean = false;                     // enable drag-to-reorder
+dragThrottle: number = 120;                     // ms throttle for drag layout updates -- attr: drag-throttle
+```
+
+## Methods
+
+- `layout()` - Full re-layout
+- `fit(element, x?, y?)` - Position specific item at coordinates, reflow others
+- `reloadItems()` - Re-collect items from DOM
+- `stamp(elements)` - Layout around fixed elements
+- `unstamp(elements)` - Remove stamp constraint
+- `getItemElements()` - Get all layout items
+- `getLayout()` - Returns `BinpackLayout` with item positions/order
+- `setLayout(layout)` - Apply saved layout (reorder, hide/show)
+
+## Events
+
+- `binpack-layout-complete` -> `{ items: HTMLElement[] }`
+- `binpack-fit-complete` -> `{ item: HTMLElement, x: number, y: number }`
+- `binpack-drag-item-positioned` -> `{ item: HTMLElement, x: number, y: number }`
+
+## Slots
+
+- `(default)` - Items to pack (any elements with explicit width/height)
+
+## CSS Custom Properties
+
+- `--binpack-gap` - Gap between items (set via `gap` property)
+- `--binpack-transition-duration` - Transition duration (set via `transition-duration` property)
+
+## CSS Parts
+
+- `base` - The inner container element
+
+## Basic Usage
+
+```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>
+
+<!-- Horizontal mode -->
+<snice-binpack horizontal style="height:300px">
+  <div style="width:100px;height:100px">A</div>
+</snice-binpack>
+
+<!-- Grid-snapped -->
+<snice-binpack column-width="100" row-height="100">
+  <div style="width:80px;height:80px">A</div>
+</snice-binpack>
+
+<!-- Draggable dashboard -->
+<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>
+```
+
+## Drag CSS Classes
+
+- `.binpack-dragging` -- applied during drag (no transition, z-index: 100)
+- `.binpack-positioning` -- applied while animating to final position after drop
+
+## Notes
+
+- Items must have explicit width/height (not auto-sized)
+- Container uses `position: relative`, items get `position: absolute` + `transform`
+- Uses ResizeObserver on container and items for auto re-layout
+- FOUC prevented via `[ready]` attribute gating transitions
+- `contain: layout style` on `:host` (NOT paint -- items use absolute positioning)

package/docs/ai/components/book.md

@@ -2,19 +2,28 @@
 
 Page-flipping book component with cover page, keyboard navigation, and animated page turns.
 
+## Components
+
+- `<snice-book>` - Main book container
+- `<snice-book-page>` - Individual page element
+
 ## Properties
 
 ```ts
 currentPage: number = 0          // attr: current-page
-coverImage: string = ''          // attr: cover-image — URL for cover page image
+coverImage: string = ''          // attr: cover-image -- URL for cover page image
 title: string = ''               // Book title shown on cover
 author: string = ''              // Author name shown on cover
 readonly totalPages: number      // Getter, count of slotted page elements
 ```
 
-## Slots
+## Methods
 
-- `(default)` — Page elements; each child becomes one page
+- `goToPage(page: number): void` -- Navigate to specific page
+- `nextPage(): void` -- Advance by 1 page
+- `prevPage(): void` -- Go back by 1 page
+- `firstPage(): void` -- Jump to page 0
+- `lastPage(): void` -- Jump to last page
 
 ## Events
 
@@ -22,13 +31,9 @@ readonly totalPages: number      // Getter, count of slotted page elements
 - `page-flip-start` -> `{ fromPage: number, toPage: number, direction: 'forward' | 'backward' }`
 - `page-flip-end` -> `{ page: number, direction: 'forward' | 'backward' }`
 
-## Methods
+## Slots
 
-- `goToPage(page: number): void` — Navigate to specific page
-- `nextPage(): void` — Advance by 1 page
-- `prevPage(): void` — Go back by 1 page
-- `firstPage(): void` — Jump to page 0
-- `lastPage(): void` — Jump to last page
+- `(default)` -- `<snice-book-page>` elements; each child becomes one page
 
 ## CSS Custom Properties
 
@@ -36,10 +41,10 @@ readonly totalPages: number      // Getter, count of slotted page elements
 --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)) */
+--book-title         /* Book title font family */
+--title              /* Section title / body heading font */
+--body               /* Body text font */
+--base-size          /* Base font size, derived from baseline */
 ```
 
 ## CSS Parts
@@ -47,21 +52,18 @@ readonly totalPages: number      // Getter, count of slotted page elements
 - `base` - Outer cover container
 - `book` - Inner book element
 
-## Keyboard
+## Keyboard Navigation
 
-- ArrowRight/ArrowDown — Next page
-- ArrowLeft/ArrowUp — Previous page
-- Home — First page
-- End — Last page
+- ArrowRight -- Next page
+- ArrowLeft -- Previous page
 
-## Usage
+## Basic Usage
 
 ```html
 <snice-book title="My Book" author="Jane Doe" cover-image="/cover.jpg">
-  <div>Page 1 content</div>
-  <div>Page 2 content</div>
-  <div>Page 3 content</div>
-  <div>Page 4 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>
 ```
 

package/docs/ai/components/booking.md

@@ -5,15 +5,36 @@ Multi-step appointment booking widget: date picker, time slots, confirmation for
 ## Properties
 
 ```typescript
-availableDates: (Date | string)[] = [];   // attr: available-dates
-availableSlots: BookingSlot[] = [];       // attr: available-slots
+availableDates: (Date | string)[] = [];   // JS property only
+availableSlots: BookingSlot[] = [];       // JS property only
 duration: number = 30;                     // default appointment duration (minutes)
 minDate: Date | string = '';              // attr: min-date
 maxDate: Date | string = '';              // attr: max-date
-fields: BookingField[] = [];              // custom form fields for step 3
+fields: BookingField[] = [];              // JS property only
 variant: 'stepper'|'inline' = 'stepper';
 ```
 
+## Methods
+
+- `reset()` - Reset to step 1, clear selections
+- `getBooking()` - Returns `BookingData | null`
+
+## Events
+
+- `date-select` -> `{ date: string }`
+- `slot-select` -> `{ slot: BookingSlot }`
+- `booking-confirm` -> `{ booking: BookingData }`
+- `booking-cancel` -> `void`
+
+## CSS Parts
+
+- `base` - Main container
+- `stepper` - Step indicator header
+- `calendar` - Date picker section
+- `slots` - Time slots section
+- `form` - Confirmation form section
+- `confirmation` - Success message
+
 ## Interfaces
 
 ```typescript
@@ -38,19 +59,7 @@ interface BookingData {
 }
 ```
 
-## Methods
-
-- `reset()` - Reset to step 1, clear selections
-- `getBooking()` - Returns `BookingData | null`
-
-## Events
-
-- `date-select` -> `{ date: string }`
-- `slot-select` -> `{ slot: BookingSlot }`
-- `booking-confirm` -> `{ booking: BookingData }`
-- `booking-cancel` -> `void`
-
-## Usage
+## Basic Usage
 
 ```html
 <snice-booking></snice-booking>
@@ -71,26 +80,12 @@ booking.addEventListener('booking-confirm', e => {
   console.log(e.detail.booking);
 });
 
-<!-- Inline variant (all steps visible) -->
-<snice-booking variant="inline"></snice-booking>
+// Inline variant (all steps visible)
+// <snice-booking variant="inline"></snice-booking>
 ```
 
-**CSS Parts:**
-- `base` - Main container
-- `stepper` - Step indicator header
-- `calendar` - Date picker section
-- `slots` - Time slots section
-- `form` - Confirmation form section
-- `confirmation` - Success message
+## Accessibility
 
-## Features
-
-- 3-step wizard: Date -> Time -> Confirm
-- Stepper or inline layout
-- Available date highlighting
-- Time slot grid with duration display
-- Custom form fields (text, email, tel, textarea)
-- Booking summary before confirmation
-- Success confirmation view
-- Date restrictions (min/max)
-- Past date disabling
+- Keyboard navigation for date picker and slots
+- ARIA labels for steps and form fields
+- Focus management between steps

package/docs/ai/components/breadcrumbs.md

@@ -2,30 +2,47 @@
 
 Navigation breadcrumb trail.
 
+## Components
+
+- `<snice-breadcrumbs>` - Container (imperative `items` array or declarative `<snice-crumb>` children)
+- `<snice-crumb>` - Individual breadcrumb item (data element, no shadow DOM)
+
 ## Properties
 
+### snice-breadcrumbs
+
 ```typescript
-items: BreadcrumbItem[] = [];
-separator: '/'|'>'|'»'|'•'|'|' = '/';
+items: BreadcrumbItem[] = [];                              // JS property only
+separator: '/'|'>'|'>>'|'.'|'|' = '/';
 size: 'small'|'medium'|'large' = 'medium';
-maxItems: number = 0;  // 0 = show all, attr: max-items
+maxItems: number = 0;                                      // 0 = show all, attr: max-items
 ```
 
-## Slots
+### snice-crumb
 
-- `(default)` - `<snice-crumb>` elements (declarative API)
+```typescript
+label: string = '';
+href: string = '';
+icon: string = '';
+iconImage: string = '';           // attr: icon-image (deprecated)
+active: boolean = false;
+```
 
-### snice-crumb Slots
+## Methods
 
-- `icon` - Custom icon element (for CSS icon fonts)
+- `setItems(items: BreadcrumbItem[])` - Update breadcrumb items
 
 ## Events
 
-- `breadcrumb-click` → `{ item, index, href, label }`
+- `breadcrumb-click` -> `{ item: BreadcrumbItem, index: number, href: string, label: string }`
 
-## Methods
+## Slots
 
-- `setItems(items: BreadcrumbItem[])` - Update breadcrumb items
+### snice-breadcrumbs
+- `(default)` - `<snice-crumb>` elements (declarative API)
+
+### snice-crumb
+- `icon` - Custom icon element (for CSS icon fonts)
 
 ## CSS Parts
 
@@ -59,7 +76,7 @@ interface BreadcrumbItem {
 }
 ```
 
-## Usage
+## Basic Usage
 
 ```html
 <!-- Imperative -->
@@ -72,7 +89,9 @@ breadcrumbs.items = [
   { label: 'Products', href: '/products' },
   { label: 'Laptop', active: true }
 ];
+```
 
+```html
 <!-- Declarative -->
 <snice-breadcrumbs>
   <snice-crumb href="/" label="Home"></snice-crumb>
@@ -90,3 +109,9 @@ breadcrumbs.items = [
   </snice-crumb>
 </snice-breadcrumbs>
 ```
+
+## Accessibility
+
+- `<nav>` with `aria-label="Breadcrumb"`
+- `aria-current="page"` on active/last item
+- All links and ellipsis button are keyboard accessible

package/docs/ai/components/button.md

@@ -1,6 +1,6 @@
 # snice-button
 
-Interactive button with variants and states.
+Interactive button with variants, states, and form association.
 
 ## Properties
 
@@ -16,19 +16,10 @@ circle: boolean = false;
 href: string = '';
 target: string = '';
 download: string = '';
-icon: string = '';
-iconPlacement: 'start'|'end' = 'start';
+icon: string = '';                        // emoji, URL, image file
+iconPlacement: 'start'|'end' = 'start';  // attr: icon-placement
 ```
 
-## Slots
-
-- `(default)` - Button label content
-- `icon` - Custom icon content (overrides `icon` property)
-
-## Events
-
-- `button-click` → `{ originalEvent: MouseEvent }`
-
 ## Methods
 
 - `focus(options?)` - Focus button
@@ -38,10 +29,25 @@ iconPlacement: 'start'|'end' = 'start';
 - `setDisabled(disabled)` - Set disabled state
 - `setVariant(variant)` - Set variant
 
-## Usage
+## Events
+
+- `button-click` -> `{ originalEvent: MouseEvent }`
+
+## Slots
+
+- `(default)` - Button label content
+- `icon` - Custom icon content (overrides `icon` property)
+
+## CSS Parts
+
+- `base` - The button element
+- `spinner` - Loading spinner
+- `label` - Button label text
+- `icon` - Icon container
+
+## Basic Usage
 
 ```html
-<!-- Basic -->
 <snice-button>Click me</snice-button>
 
 <!-- Variants -->
@@ -53,7 +59,6 @@ iconPlacement: 'start'|'end' = 'start';
 
 <!-- Sizes -->
 <snice-button size="small">Small</snice-button>
-<snice-button size="medium">Medium</snice-button>
 <snice-button size="large">Large</snice-button>
 
 <!-- States -->
@@ -63,11 +68,9 @@ iconPlacement: 'start'|'end' = 'start';
 <!-- Styles -->
 <snice-button outline>Outline</snice-button>
 <snice-button pill>Pill</snice-button>
-<snice-button circle icon="×"></snice-button>
-
-<!-- ⚠️ icon="home" renders as PLAIN TEXT. Use the icon slot for icon fonts. -->
+<snice-button circle icon="x"></snice-button>
 
-<!-- Icon SLOT — for Material Symbols, Font Awesome, SVGs -->
+<!-- Icon SLOT -- for Material Symbols, Font Awesome, SVGs -->
 <snice-button>
   <span slot="icon" class="material-symbols-outlined">save</span>
   Save
@@ -76,38 +79,24 @@ iconPlacement: 'start'|'end' = 'start';
   <i slot="icon" class="fa-solid fa-trash"></i>
   Delete
 </snice-button>
-<snice-button>
-  <svg slot="icon" viewBox="0 0 24 24"><path d="..."/></svg>
-  Action
-</snice-button>
 
-<!-- Icon PROPERTY — for emoji, URLs, image files only -->
-<snice-button icon="→">Next</snice-button>
-<snice-button icon="🏠">Home</snice-button>
+<!-- Icon PROPERTY -- for emoji, URLs, image files only -->
+<!-- icon="home" renders as PLAIN TEXT, NOT a Material icon -->
+<snice-button icon="->">Next</snice-button>
 <snice-button icon="/icons/save.svg">Save</snice-button>
-<snice-button icon="icon.png">Image file</snice-button>
-<!-- Scheme overrides: img://, text:// -->
 <snice-button icon="img://filename">Force img</snice-button>
-<snice-button icon="text://content">Force text</snice-button>
 
 <!-- As link -->
 <snice-button href="/page">Link</snice-button>
 <snice-button href="/file.pdf" download>Download</snice-button>
-```
 
-## CSS Parts
-
-`base`, `spinner`, `label`, `icon`
+<!-- Form -->
+<snice-button type="submit" variant="primary">Submit</snice-button>
+<snice-button type="reset">Reset</snice-button>
+```
 
-## Features
+## Accessibility
 
-- 6 color variants
-- 3 sizes
-- Outline style
-- Pill (rounded) shape
-- Circle (icon only) shape
-- Loading state with spinner
-- Disabled state
-- Link mode (href)
-- Icon support with placement (URL, image files, emoji). Use slot for icon fonts.
-- Download attribute support
+- Keyboard accessible (Enter, Space)
+- Focus ring on `:focus-visible`
+- Form-associated (`formAssociated: true`)