snice 4.28.0 → 4.30.0

package/docs/ai/components/location.md

@@ -4,7 +4,7 @@ Display location information with addresses, coordinates, and maps.
 
 ## Properties
 
-```typescript
+```ts
 mode: 'full'|'compact'|'coordinates'|'address' = 'full';
 name: string = '';
 address: string = '';
@@ -22,22 +22,33 @@ mapUrl: string = '';             // attr: map-url
 clickable: boolean = false;
 ```
 
+## Methods
+
+- `getData()` → `LocationData`
+- `getCoordinates()` → `{ latitude, longitude } | null`
+- `getFullAddress()` → `string`
+- `openMap()` → Opens location in maps (new tab)
+
+## Events
+
+- `location-click` → `LocationData` (when clickable)
+
 ## Slots
 
 - `icon` - Custom icon content (overrides `icon`/`iconImage` properties)
 
-## Methods
+## CSS Parts
 
-- `getData()` - Returns LocationData object
-- `getCoordinates()` - Returns `{ latitude, longitude }` or null
-- `getFullAddress()` - Returns formatted address string
-- `openMap()` - Opens location in maps app (new tab)
+- `base` - Outer location container
+- `icon` - Icon container
+- `content` - Content area (name, address, coordinates)
+- `map` - Embedded map container
 
-## Events
-
-- `location-click` → `LocationData` - Clicked (when clickable)
+## Basic Usage
 
-## Usage
+```typescript
+import 'snice/components/location/snice-location';
+```
 
 ```html
 <snice-location
@@ -61,18 +72,3 @@ clickable: boolean = false;
   <span slot="icon" class="material-symbols-outlined">business</span>
 </snice-location>
 ```
-
-**CSS Parts:**
-- `base` - The outer location container
-- `icon` - The icon container
-- `content` - The content area with name, address, coordinates
-- `map` - The embedded map container
-
-## Features
-
-- 4 display modes (full/compact/coordinates/address)
-- Embedded Google Maps support
-- Custom icons (emoji, URL, image). Use slot for icon fonts.
-- Clickable to open in maps app
-- Custom map URL support
-- Complete address formatting

package/docs/ai/components/login.md

@@ -4,7 +4,7 @@ Login form with username/password using @request/@respond pattern.
 
 ## Properties
 
-```typescript
+```ts
 variant: 'default'|'card'|'minimal' = 'default';
 size: 'small'|'medium'|'large' = 'medium';
 title: string = 'Sign In';
@@ -17,11 +17,11 @@ actionText: string = 'Sign In';      // attr: action-text
 
 ## Methods
 
-- `login(credentials?)` - Trigger login via @request (async)
-- `setCredentials({username?, password?, remember?})` - Set form values
-- `reset()` - Clear form, alert, loading
-- `setError(message)` - Show error alert
-- `clearError()` - Clear alert
+- `login(credentials?)` → Trigger login via @request (async)
+- `setCredentials({username?, password?, remember?})` → Set form values
+- `reset()` → Clear form, alert, loading
+- `setError(message)` → Show error alert
+- `clearError()` → Clear alert
 
 ## Requests
 
@@ -29,7 +29,7 @@ actionText: string = 'Sign In';      // attr: action-text
 
 ## Types
 
-```typescript
+```ts
 interface LoginCredentials {
   username: string;
   password: string;
@@ -60,14 +60,19 @@ interface LoginResult {
 - `before-submit`, `after-submit` - Around button
 - `footer` - Footer content
 
-**CSS Parts:**
+## CSS Parts
+
 - `base` - Outer login container
 - `header` - Header section
 - `title` - H1 title element
 - `form` - The login form
 - `footer` - Footer section
 
-## Usage
+## Basic Usage
+
+```typescript
+import 'snice/components/login/snice-login';
+```
 
 ```html
 <!-- With controller -->

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