snice 4.28.0 → 4.30.0

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`)

package/docs/ai/components/calendar.md

@@ -8,96 +8,63 @@ Calendar with date selection and event support.
 value: Date | string = new Date();
 view: 'month'|'week'|'day' = 'month';
 events: CalendarEvent[] = [];
-minDate: Date | string = '';
-maxDate: Date | string = '';
-disabledDates: (Date | string)[] = [];
-highlightToday: boolean = true;
-showWeekNumbers: boolean = false;
-firstDayOfWeek: number = 0; // 0=Sun, 1=Mon
+minDate: Date | string = '';           // attribute: min-date
+maxDate: Date | string = '';           // attribute: max-date
+disabledDates: (Date | string)[] = []; // attribute: disabled-dates
+highlightToday: boolean = true;        // attribute: highlight-today
+showWeekNumbers: boolean = false;      // attribute: show-week-numbers
+firstDayOfWeek: number = 0;            // attribute: first-day-of-week (0=Sun, 1=Mon)
 locale: string = 'en-US';
 ```
 
-## CalendarEvent
-
-```typescript
-interface CalendarEvent {
-  id: string | number;
-  title: string;
-  start: Date | string;
-  end?: Date | string;
-  color?: string;
-  data?: any;
-}
-```
-
 ## Methods
 
-```typescript
-goToToday(): void
-goToDate(date: Date | string): void
-previousMonth(): void
-nextMonth(): void
-previousWeek(): void
-nextWeek(): void
-previousDay(): void
-nextDay(): void
-getDisplayedMonth(): { month: number; year: number }
-getEventsForDate(date: Date | string): CalendarEvent[]
-```
+- `goToToday()` - Navigate to today
+- `goToDate(date: Date | string)` - Navigate to specific date
+- `previousMonth()` / `nextMonth()` - Navigate months
+- `previousWeek()` / `nextWeek()` - Navigate weeks
+- `previousDay()` / `nextDay()` - Navigate days
+- `getDisplayedMonth()` - Returns `{ month: number; year: number }`
+- `getEventsForDate(date: Date | string)` - Returns `CalendarEvent[]`
 
 ## Events
 
-- `calendar-change` - Date selected (detail: { value, calendar })
-- `calendar-event-click` - Event clicked (detail: { event, calendar })
+- `calendar-change` -> `{ value: Date, calendar: SniceCalendarElement }`
+- `calendar-event-click` -> `{ event: CalendarEvent, calendar: SniceCalendarElement }`
 
-## Usage
+## CSS Parts
 
-```html
-<snice-calendar></snice-calendar>
+- `base` - Main calendar container
+- `header` - Header with title and navigation buttons
+- `grid` - Day cells grid
 
-<!-- With events -->
+## Basic Usage
+
+```html
 <snice-calendar></snice-calendar>
 ```
 
 ```typescript
+import 'snice/components/calendar/snice-calendar';
+
 calendar.events = [
   { id: 1, title: 'Meeting', start: new Date(), color: '#2196f3' }
 ];
-```
 
-```html
-<!-- With restrictions -->
-<snice-calendar
-  min-date="2024-01-01"
-  max-date="2024-12-31"
-  first-day-of-week="1"
-  locale="fr-FR">
-</snice-calendar>
+calendar.addEventListener('calendar-change', (e) => {
+  console.log('Selected:', e.detail.value);
+});
 ```
 
-```typescript
-// Programmatic control
-calendar.goToToday();
-calendar.previousMonth();
-calendar.nextMonth();
-calendar.goToDate(new Date(2024, 5, 15));
-```
+## Keyboard Navigation
 
-**CSS Parts:**
-- `base` - Main calendar container
-- `header` - Header with title and navigation buttons
-- `grid` - Day cells grid
+- Arrow keys: navigate dates
+- Enter: select date
+- Tab: move between controls
+
+## Accessibility
 
-## Features
-
-- Month/week/day views
-- Event display with colors
-- Date restrictions (min/max/disabled)
-- Locale support
-- Week starting day configuration
-- Week numbers (optional)
-- Keyboard navigation
-- Event click handling
-- Programmatic navigation
-- Multi-event days
-- Today highlighting
+- Keyboard navigation with arrow keys
+- ARIA labels for dates and events
+- Screen reader friendly
+- Focus management

package/docs/ai/components/camera-annotate.md

@@ -1,88 +1,55 @@
 # snice-camera-annotate
 
-Image annotation component combining camera capture + freehand drawing + labeled annotations.
+Camera capture + freehand drawing + labeled annotations.
 
 ## Properties
 
 ```typescript
 mode: 'camera' | 'annotate' = 'camera';
-autoRotateColors: boolean = true;    // attribute: auto-rotate-colors
-showLabelsPanel: boolean = true;     // attribute: show-labels-panel
+autoRotateColors: boolean = true;     // attribute: auto-rotate-colors
+showLabelsPanel: boolean = true;      // attribute: show-labels-panel
 ```
 
 ## Methods
 
-```typescript
-capture(): Promise<void>;
-exportImage(options?: { includeLabels?: boolean }): string;
-exportAnnotations(): AnnotationData;
-importAnnotations(data: AnnotationData): void;
-clearAnnotations(): void;
-```
+- `capture(): Promise<void>` - Capture frame, switch to annotate mode
+- `exportImage(options?: { includeLabels?: boolean }): string` - Export as data URL
+- `exportAnnotations(): AnnotationData` - Export annotation data (JSON-serializable)
+- `importAnnotations(data: AnnotationData): void` - Load annotation data
+- `clearAnnotations(): void` - Remove all annotations
 
 ## Events
 
-```typescript
-'capture'           → { dataURL: string; width: number; height: number }
-'annotate'          → { annotation: Annotation }
-'annotation-change' → { annotations: Annotation[] }
-```
+- `capture` -> `{ dataURL: string, width: number, height: number }`
+- `annotate` -> `{ annotation: Annotation }`
+- `annotation-change` -> `{ annotations: Annotation[] }`
 
-## Types
+## CSS Parts
 
-```typescript
-interface Annotation {
-  id: string;
-  strokeId: string;
-  label: string;
-  color: string;
-  visible: boolean;
-  timestamp: number;
-}
-
-interface AnnotationData {
-  annotations: Annotation[];
-  strokes: AnnotationStroke[];
-  imageWidth: number;
-  imageHeight: number;
-}
-
-interface AnnotationStroke {
-  id: string;
-  color: string;
-  width: number;
-  points: { x: number; y: number }[];
-  timestamp: number;
-}
-```
+- `base` - Outer layout container
+- `canvas` - Canvas area (video + drawing surface)
+- `toolbar` - Toolbar (capture/retake, undo, clear, export)
+- `sidebar` - Sidebar (color palette + annotation labels)
 
-## Usage
+## Basic Usage
 
 ```html
-<!-- Default -->
 <snice-camera-annotate></snice-camera-annotate>
+```
 
-<!-- No sidebar -->
-<snice-camera-annotate show-labels-panel="false"></snice-camera-annotate>
+```typescript
+import 'snice/components/camera-annotate/snice-camera-annotate';
 
-<!-- Manual color selection -->
-<snice-camera-annotate auto-rotate-colors="false"></snice-camera-annotate>
+// Save/load annotations
+const data = annotator.exportAnnotations();
+annotator.importAnnotations(data);
+
+// Export image
+const url = annotator.exportImage({ includeLabels: true });
 ```
 
-**CSS Parts:**
-- `base` - Outer layout container div
-- `canvas` - Canvas area containing video and drawing surface
-- `toolbar` - Toolbar with capture/retake, undo, clear, export buttons
-- `sidebar` - Sidebar panel with color palette and annotation labels
-
-## Features
-
-- Camera capture → freehand draw → label workflow
-- 12-color preset palette with auto-rotation
-- Sidebar labels linked to drawn shapes
-- Hover label highlights shape, dims others (opacity 0.2 + grayscale)
-- Show/hide individual and bulk annotations
-- Export image with/without rendered labels
-- Save/load annotation data (JSON)
-- Undo last stroke
-- Adjustable stroke width
+## Accessibility
+
+- Color swatches have title attributes
+- Annotation toggles have descriptive titles
+- Sidebar scrolls independently