snice 4.27.0 → 4.29.0

package/docs/ai/components/map.md

@@ -1,25 +1,22 @@
 # snice-map
 
-Interactive slippy map using OpenStreetMap tiles with markers, popups, drag panning, scroll zoom, and programmatic control.
+Interactive slippy map using OpenStreetMap tiles with markers, popups, drag panning, scroll zoom.
 
 ## Properties
 
 ```ts
-center: MapCenter = { lat: 51.505, lng: -0.09 }  // Map center (set via JS)
-zoom: number = 13                                  // attr: zoom — Zoom level
+center: MapCenter = { lat: 51.505, lng: -0.09 }  // JS only
+zoom: number = 13
 minZoom: number = 1                                // attr: min-zoom
 maxZoom: number = 18                               // attr: max-zoom
-markers: MapMarker[] = []                          // Marker data (set via JS)
-tileUrl: string = 'https://tile.openstreetmap.org/{z}/{x}/{y}.png'  // attr: tile-url — Tile server template
+markers: MapMarker[] = []                          // JS only
+tileUrl: string = 'https://tile.openstreetmap.org/{z}/{x}/{y}.png'  // attr: tile-url
 ```
 
 ## Types
 
 ```ts
-interface MapCenter {
-  lat: number;
-  lng: number;
-}
+interface MapCenter { lat: number; lng: number; }
 
 interface MapMarker {
   id: string;
@@ -27,40 +24,37 @@ interface MapMarker {
   lng: number;
   label?: string;
   icon?: string;
-  popup?: string;   // Popup text shown on marker click
+  popup?: string;
 }
 ```
 
-## Events
+## Methods
 
-- `map-click` -> `{ lat: number, lng: number }` — Click on map (not a marker)
-- `marker-click` -> `{ marker: MapMarker }` — Marker clicked (also toggles popup)
-- `map-move` -> `{ center: MapCenter, zoom: number }` — After drag pan completes
-- `map-zoom` -> `{ zoom: number }` — Zoom level changed
+- `setCenter(lat, lng)` → Pan to coordinates
+- `setZoom(zoom)` → Set zoom (clamped to min/max)
+- `addMarker(marker)` → Add a marker
+- `removeMarker(id)` → Remove marker by ID
+- `fitBounds(markers?)` → Auto-zoom/center to fit markers (defaults to all)
 
-## Methods
+## Events
 
-- `setCenter(lat: number, lng: number): void` — Pan to coordinates
-- `setZoom(zoom: number): void` — Set zoom level (clamped to min/max)
-- `addMarker(marker: MapMarker): void` — Add a marker
-- `removeMarker(id: string): void` — Remove marker by ID
-- `fitBounds(markers?: MapMarker[]): void` — Auto-zoom/center to fit markers (defaults to all)
+- `map-click` → `{ lat, lng }` (click on map, not marker)
+- `marker-click` → `{ marker: MapMarker }` (also toggles popup)
+- `map-move` → `{ center: MapCenter, zoom }` (after drag pan)
+- `map-zoom` → `{ zoom }` (zoom level changed)
 
-**CSS Parts:**
-- `base` - The outer map container
-- `tiles` - The tile layer container
-- `markers` - The markers layer container
-- `controls` - The zoom controls container
+## CSS Parts
 
-## Behavior
+- `base` - Outer map container
+- `tiles` - Tile layer container
+- `markers` - Markers layer container
+- `controls` - Zoom controls container
 
-- Mouse drag to pan, scroll wheel to zoom
-- Zoom +/- buttons in top-right corner
-- Marker click toggles popup display
-- OpenStreetMap attribution included
-- Custom tile servers via `tile-url` with `{x}`, `{y}`, `{z}` placeholders
+## Basic Usage
 
-## Usage
+```typescript
+import 'snice/components/map/snice-map';
+```
 
 ```html
 <snice-map zoom="10" min-zoom="3" max-zoom="16"></snice-map>

package/docs/ai/components/markdown.md

@@ -5,26 +5,24 @@ Lightweight GFM-compatible markdown renderer with built-in sanitization.
 ## Properties
 
 ```ts
-sanitize: boolean                        // Sanitize HTML output (default: true)
-theme: 'default' | 'github'             // Visual theme
+sanitize: boolean = true;          // Sanitize HTML output
+theme: 'default'|'github' = 'default';
 ```
 
-## Methods
-
-- `setContent(markdown: string)` — Set markdown source programmatically
+> `content` is a plain class field, not `@property`. Use `setContent()` or slotted text.
 
-## Slots
+## Methods
 
-- (default) - Markdown source text
+- `setContent(markdown: string)` → Set markdown source and re-render
 
-## Input
+## Events
 
-Content via slotted text or `setContent()`. No `content` attribute/property.
+- `markdown-render` → `{ html: string }` (after render)
+- `link-click` → `{ href: string, text: string }` (default prevented)
 
-## Events
+## Slots
 
-- `markdown-render` → `{ html: string }` - Fired after markdown is rendered
-- `link-click` → `{ href: string; text: string }` - Fired when a link is clicked (default prevented)
+- `(default)` - Markdown source text
 
 ## CSS Custom Properties
 
@@ -44,21 +42,19 @@ Content via slotted text or `setContent()`. No `content` attribute/property.
 --snice-font-weight-semibold
 ```
 
-**CSS Parts:**
-- `base` - The rendered markdown body container
+## CSS Parts
+
+- `base` - Rendered markdown body container
+
+## Supported Syntax
 
-## Supported Markdown
+Headings (h1-h6), bold, italic, strikethrough, ordered/unordered/task lists, code blocks with language class, inline code, blockquotes, tables (GFM), images, links, autolinks, horizontal rules.
 
-- Headings (h1-h6)
-- Bold, italic, strikethrough
-- Ordered/unordered lists, task lists
-- Code blocks with language class, inline code
-- Blockquotes
-- Tables (GFM)
-- Images, links, autolinks
-- Horizontal rules
+## Basic Usage
 
-## Usage
+```typescript
+import 'snice/components/markdown/snice-markdown';
+```
 
 ```html
 <snice-markdown># Hello

package/docs/ai/components/masonry.md

@@ -4,7 +4,7 @@ Pinterest-style masonry layout using CSS columns.
 
 ## Properties
 
-```typescript
+```ts
 columns: number = 3;                  // Column count (0 = auto based on minColumnWidth)
 gap: string = '1rem';                 // Gap between items
 minColumnWidth: string = '250px';     // attr: min-column-width, min width when columns=0
@@ -14,7 +14,15 @@ minColumnWidth: string = '250px';     // attr: min-column-width, min width when
 
 - `(default)` - Items to arrange in masonry layout
 
-## Usage
+## CSS Parts
+
+- `base` - Masonry layout container
+
+## Basic Usage
+
+```typescript
+import 'snice/components/masonry/snice-masonry';
+```
 
 ```html
 <!-- Fixed columns -->
@@ -36,15 +44,3 @@ minColumnWidth: string = '250px';     // attr: min-column-width, min width when
   <div>Card 2</div>
 </snice-masonry>
 ```
-
-**CSS Parts:**
-- `base` - The masonry layout container
-
-## Features
-
-- CSS columns-based layout (no JS measurement)
-- Auto-responsive when columns=0
-- Configurable gap
-- Items flow top-to-bottom, left-to-right
-- `break-inside: avoid` on slotted children
-- `role="list"` for accessibility

package/docs/ai/components/mentions.md

@@ -4,13 +4,17 @@ Text input with inline @mention autocomplete. Mentions stored as `@[Name](id)` m
 
 ## Properties
 
-```typescript
+```ts
 value: string = '';              // Raw text with @[Name](id) markers
-users: MentionUser[] = [];       // Autocomplete candidates
+users: MentionUser[] = [];       // JS only — autocomplete candidates
 placeholder: string = 'Type @ to mention someone...';
 readonly: boolean = false;
 trigger: string = '@';           // Trigger character
+```
+
+## Types
 
+```ts
 interface MentionUser {
   id: string;
   name: string;
@@ -25,26 +29,30 @@ interface Mention {
 }
 ```
 
-## Events
+## Methods
 
-- `mention-add` -> `{ user: MentionUser, value: string }`
-- `mention-remove` -> `{ user: MentionUser, value: string }`
-- `value-change` -> `{ value: string, plainText: string, mentions: Mention[] }`
+- `getValue()` → `string` (raw value with markers)
+- `getPlainText()` → `string` (mentions replaced by names)
+- `getMentions()` → `Mention[]` (structured mention data)
 
-## Methods
+## Events
 
-- `getValue()` - Raw value with mention markers
-- `getPlainText()` - Text with mentions replaced by names only
-- `getMentions()` - Array of Mention objects with id, name, indices
+- `mention-add` → `{ user: MentionUser, value: string }`
+- `mention-remove` → `{ user: MentionUser, value: string }`
+- `value-change` → `{ value: string, plainText: string, mentions: Mention[] }`
 
 ## CSS Parts
 
-- `base` - Wrapper
+- `base` - Wrapper container
 - `editor` - Editor container
 - `textarea` - Text input
 - `dropdown` - Autocomplete dropdown
 
-## Usage
+## Basic Usage
+
+```typescript
+import 'snice/components/mentions/snice-mentions';
+```
 
 ```html
 <snice-mentions placeholder="Write something..."></snice-mentions>
@@ -59,3 +67,9 @@ editor.value = 'Hey @[Alice Johnson](u1), check this out!';
 editor.addEventListener('mention-add', e => console.log('Mentioned:', e.detail.user));
 editor.addEventListener('value-change', e => console.log('Mentions:', e.detail.mentions));
 ```
+
+## Keyboard Navigation
+
+- Arrow Down/Up navigate dropdown
+- Enter/Tab select
+- Escape closes

package/docs/ai/components/menu.md

@@ -2,97 +2,99 @@
 
 Dropdown menu with items, dividers, and configurable trigger behavior.
 
+## Components
+
+- `<snice-menu>` - Container with trigger and panel
+- `<snice-menu-item>` - Selectable item with icon/shortcut slots
+- `<snice-menu-divider>` - Visual separator
+
 ## Properties
 
-```typescript
+```ts
+// snice-menu
 open: boolean = false;
 placement: 'bottom-start'|'bottom-end'|'top-start'|'top-end'|'right-start'|'right-end'|'left-start'|'left-end' = 'bottom-start';
 trigger: 'click'|'hover'|'manual' = 'click';
 closeOnSelect: boolean = true;       // attr: close-on-select
 distance: number = 4;
-```
-
-## Methods
-
-- `openMenu()` - Open the menu
-- `closeMenu()` - Close the menu
-- `toggleMenu()` - Toggle open/closed
-
-## Slots (menu)
 
-- `trigger` - Trigger element (required)
-- `image-left` - Image before trigger
-- `image-right` - Image after trigger
-- `(default)` - Menu items and dividers
-
-## Events
-
-- `menu-open` → `{ menu }`
-- `menu-close` → `{ menu }`
-- `menu-item-select` → `{ item, value }`
-
-## snice-menu-item
-
-```typescript
+// snice-menu-item
 value: string = '';
 disabled: boolean = false;
 selected: boolean = false;
 ```
 
-Slots: `icon`, `(default)`, `shortcut`
+## Methods
 
-## snice-menu-divider
+- `openMenu()` → Open the menu
+- `closeMenu()` → Close the menu
+- `toggleMenu()` → Toggle open/closed
 
-Visual separator between items.
+## Events
 
-## Usage
+- `menu-open` → `{ menu }`
+- `menu-close` → `{ menu }`
+- `menu-item-select` → `{ item, value }` (bubbles from menu-item)
 
-```html
-<snice-menu>
-  <button slot="trigger">File</button>
-  <snice-menu-item value="new">New</snice-menu-item>
-  <snice-menu-item value="save">
-    <span slot="icon">💾</span>
-    Save
-    <span slot="shortcut">⌘S</span>
-  </snice-menu-item>
-  <snice-menu-divider></snice-menu-divider>
-  <snice-menu-item value="exit">Exit</snice-menu-item>
-</snice-menu>
+## Slots (snice-menu)
 
-<!-- Hover trigger -->
-<snice-menu trigger="hover">...</snice-menu>
+- `trigger` - Trigger element (required)
+- `image-left` - Image before trigger
+- `image-right` - Image after trigger
+- `(default)` - Menu items and dividers
 
-<!-- Manual control -->
-<snice-menu trigger="manual">...</snice-menu>
+## Slots (snice-menu-item)
 
-<!-- Keep open -->
-<snice-menu close-on-select="false">...</snice-menu>
-```
+- `icon` - Icon before label
+- `(default)` - Label content
+- `shortcut` - Keyboard shortcut hint
 
-## CSS Parts
+## CSS Parts (snice-menu)
 
-### snice-menu
 - `trigger` - Trigger wrapper
 - `image-left` - Left image container
 - `image-right` - Right image container
 - `panel` - Dropdown panel
 - `content` - Panel content wrapper
 
-### snice-menu-item
+## CSS Parts (snice-menu-item)
+
 - `item` - Item container
 - `icon` - Icon wrapper
 - `label` - Label wrapper
 - `shortcut` - Shortcut wrapper
 
+## CSS Parts (snice-menu-divider)
+
+- `divider` - Separator line
+
 ## CSS Custom Properties
 
 ```css
 --menu-bg: var(--snice-color-background, white);
 --menu-border: var(--snice-color-border, #e5e7eb);
---menu-shadow: var(--snice-shadow-lg, ...);
+--menu-shadow: var(--snice-shadow-lg);
 --menu-z-index: var(--snice-z-index-dropdown, 1000);
 --menu-border-radius: var(--snice-radius-md, 0.375rem);
 --menu-min-width: 10rem;
---menu-distance: 4px;  /* set via distance property */
+```
+
+## Basic Usage
+
+```typescript
+import 'snice/components/menu/snice-menu';
+```
+
+```html
+<snice-menu>
+  <button slot="trigger">File</button>
+  <snice-menu-item value="new">New</snice-menu-item>
+  <snice-menu-item value="save">
+    <span slot="icon">💾</span>
+    Save
+    <span slot="shortcut">⌘S</span>
+  </snice-menu-item>
+  <snice-menu-divider></snice-menu-divider>
+  <snice-menu-item value="exit">Exit</snice-menu-item>
+</snice-menu>
 ```

package/docs/ai/components/message-strip.md

@@ -1,36 +1,44 @@
 # snice-message-strip
 
-Inline contextual message bar within content flow. Differs from alert (dismissable card), banner (full-width top), toast (floating).
+Inline contextual message bar within content flow. Differs from alert (card), banner (full-width), toast (floating).
 
 ## Properties
 
-```typescript
+```ts
 variant: 'info'|'success'|'warning'|'danger' = 'info';
 dismissable: boolean = false;
 icon: string = '';  // Custom icon (set "none" to hide)
 ```
 
-## Slots
+## Methods
 
-- `(default)` - Message content
-- `icon` - Custom icon element
+- `show()` → Show the message strip
+- `hide()` → Hide with slide-out animation
 
 ## Events
 
 - `dismiss` → `{ variant: string }`
 
-## Methods
+## Slots
 
-- `show()` - Show the message strip
-- `hide()` - Hide with animation
+- `(default)` - Message content
+- `icon` - Custom icon element
 
-## Usage
+## CSS Parts
 
-```html
-<!-- Basic -->
-<snice-message-strip variant="info">Informational message.</snice-message-strip>
+- `icon` - Icon container
+- `content` - Message content area
+- `dismiss` - Dismiss button
+
+## Basic Usage
+
+```typescript
+import 'snice/components/message-strip/snice-message-strip';
+```
 
+```html
 <!-- Variants -->
+<snice-message-strip variant="info">Informational message.</snice-message-strip>
 <snice-message-strip variant="success">Operation completed.</snice-message-strip>
 <snice-message-strip variant="warning">Review your changes.</snice-message-strip>
 <snice-message-strip variant="danger">An error occurred.</snice-message-strip>
@@ -43,17 +51,9 @@ icon: string = '';  // Custom icon (set "none" to hide)
 
 <!-- No icon -->
 <snice-message-strip variant="info" icon="none">No icon shown.</snice-message-strip>
-
-<!-- Programmatic -->
-<snice-message-strip>Message</snice-message-strip>
 ```
 
 ```typescript
 messageStrip.hide();
 messageStrip.show();
 ```
-
-**CSS Parts:**
-- `icon` - The icon container
-- `content` - The message content area
-- `dismiss` - The dismiss button

package/docs/ai/components/metric-table.md

@@ -4,29 +4,29 @@ Compact metrics table with sparklines, color-coded values, and built-in sorting.
 
 ## Properties
 
-```typescript
-columns: MetricColumn[] = [];
-data: Record<string, any>[] = [];
-sortBy: string = '';           // attr: sort-by
-sortDirection: 'asc'|'desc' = 'desc';  // attr: sort-direction
+```ts
+columns: MetricColumn[] = [];                    // JS only
+data: Record<string, any>[] = [];                // JS only
+sortBy: string = '';
+sortDirection: 'asc'|'desc' = 'desc';
 ```
 
 ## Types
 
-```typescript
+```ts
 interface MetricColumn {
   key: string;
   label: string;
   type?: 'text'|'number'|'percent'|'currency';
-  format?: string;       // Currency code for 'currency' type (default: 'USD')
+  format?: string;       // Currency code (default: 'USD')
   sparkline?: boolean;   // Render array values as sparkline
 }
 ```
 
 ## Events
 
-- `sort-change` -> `{ sortBy: string, sortDirection: 'asc'|'desc' }`
-- `row-click` -> `{ row: Record<string, any>, index: number }`
+- `sort-change` → `{ sortBy: string, sortDirection: 'asc'|'desc' }`
+- `row-click` → `{ row: Record<string, any>, index: number }`
 
 ## CSS Parts
 
@@ -34,7 +34,11 @@ interface MetricColumn {
 - `table` - Table element
 - `row` - Table row
 
-## Usage
+## Basic Usage
+
+```typescript
+import 'snice/components/metric-table/snice-metric-table';
+```
 
 ```html
 <snice-metric-table sort-by="value"></snice-metric-table>
@@ -53,14 +57,3 @@ el.data = [
   { name: 'Bounce Rate', value: 34.2, change: -2.5, revenue: null, trend: [40, 38, 35, 33] }
 ];
 ```
-
-## Features
-
-- Column types: text, number, percent, currency
-- Inline SVG sparklines from array data
-- Positive values green, negative values red
-- Click column headers to sort (toggles asc/desc)
-- Compact row density
-- Currency formatting with locale
-- Null/undefined shown as em-dash
-- Keyboard accessible rows

package/docs/ai/components/modal.md

@@ -4,35 +4,48 @@ Dialog overlay with focus trap, backdrop dismiss, and accessibility.
 
 ## Properties
 
-```typescript
+```ts
 open: boolean = false;
 size: 'small'|'medium'|'large'|'fullscreen' = 'medium';
 noBackdropDismiss: boolean = false;  // attr: no-backdrop-dismiss
 noEscapeDismiss: boolean = false;    // attr: no-escape-dismiss
 noFocusTrap: boolean = false;        // attr: no-focus-trap
 noCloseButton: boolean = false;      // attr: no-close-button
-noHeader: boolean = false;           // attr: no-header — hides header entirely
-noFooter: boolean = false;           // attr: no-footer — hides footer entirely
+noHeader: boolean = false;           // attr: no-header
+noFooter: boolean = false;           // attr: no-footer
 label: string = '';                  // Accessible label
 ```
 
-## Slots
+## Methods
 
-- `(default)` - Modal body content
-- `header` - Header content (title)
-- `footer` - Footer content (action buttons)
+- `show()` → Open modal
+- `close()` → Close modal
 
 ## Events
 
 - `modal-open` → `{ modal: SniceModalElement }`
 - `modal-close` → `{ modal: SniceModalElement }`
 
-## Methods
+## Slots
+
+- `(default)` - Modal body content
+- `header` - Header content (title)
+- `footer` - Footer content (action buttons)
+
+## CSS Parts
 
-- `show()` - Open modal
-- `close()` - Close modal
+- `backdrop` - Backdrop overlay
+- `panel` - Modal panel container
+- `header` - Header section
+- `close` - Close button
+- `body` - Body content section
+- `footer` - Footer section
 
-## Usage
+## Basic Usage
+
+```typescript
+import 'snice/components/modal/snice-modal';
+```
 
 ```html
 <snice-modal label="Confirm Action">
@@ -51,11 +64,7 @@ modal.close();
 modal.addEventListener('modal-close', () => console.log('Closed'));
 ```
 
-## CSS Parts
+## Keyboard Navigation
 
-- `backdrop` - The backdrop overlay
-- `panel` - The modal panel container
-- `header` - Header section
-- `close` - Close button
-- `body` - Body content section
-- `footer` - Footer section
+- Escape closes (unless `no-escape-dismiss`)
+- Tab/Shift+Tab cycle focus within modal