snice 4.8.0 → 4.10.0

package/docs/ai/components/login.md

@@ -10,134 +10,83 @@ size: 'small'|'medium'|'large' = 'medium';
 title: string = 'Sign In';
 disabled: boolean = false;
 loading: boolean = false;
-showRememberMe: boolean = true;
-showForgotPassword: boolean = true;
-actionText: string = 'Sign In';
+showRememberMe: boolean = true;      // attr: show-remember-me
+showForgotPassword: boolean = true;   // attr: show-forgot-password
+actionText: string = 'Sign In';      // attr: action-text
 ```
 
 ## Methods
 
-- `login(credentials?: LoginCredentials): Promise<LoginResult>` - Programmatic login via @request/@respond
-- `setCredentials({username?, password?, remember?})` - Set form field values
-- `reset()` - Clear form, alert, loading state
-- `setError(message)` - Display error 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
 
-## @Request/@Respond Pattern (Primary)
+## Requests
 
-Component uses `@request('login-user')` to communicate with controller.
+- `login-user` → sends `LoginCredentials`, expects `LoginResult`
+
+## Types
 
-**Element request:**
 ```typescript
 interface LoginCredentials {
   username: string;
   password: string;
   remember?: boolean;
 }
-```
 
-**Controller response:**
-```typescript
 interface LoginResult {
   success: boolean;
   error?: string;
-  data?: any;  // Can include user, token, etc.
+  data?: any;
 }
 ```
 
-**Controller setup:**
-```typescript
-import { controller, respond, IController } from 'snice';
+## Events
 
-@controller('auth-controller')
-class AuthController implements IController {
-  async attach(element: HTMLElement) {}
-  async detach(element: HTMLElement) {}
+- `login-attempt` → `{ username, timestamp }`
+- `login-success` → `{ timestamp }`
+- `login-error` → `{ error, timestamp }`
+- `login-forgot-password` → `{ timestamp }`
 
-  @respond('login-user')
-  async handleLogin(credentials: LoginCredentials): Promise<LoginResult> {
-    // Validate, authenticate, return result
-    return { success: true, data: { user, token } };
-  }
-}
-```
-
-**Usage:**
-```html
-<snice-login controller="auth-controller"></snice-login>
-```
-
-## Events (Fallback)
-
-Dispatched for non-Snice framework consumers.
+## Slots
 
-- `login-attempt` - {username, timestamp} - Form submitted
-- `login-success` - {timestamp} - Login succeeded
-- `login-error` - {error, timestamp} - Login failed
-- `login-forgot-password` - {timestamp} - Forgot password clicked
+- `before-header`, `after-header` - Around header
+- `subtitle` - Custom subtitle
+- `before-form`, `after-form` - Around form
+- `form-top` - Top of form
+- `between-fields` - Between username/password
+- `before-submit`, `after-submit` - Around button
+- `footer` - Footer content
 
 ## Usage
 
 ```html
-<!-- With controller (primary) -->
-<snice-login controller="auth-controller"></snice-login>
+<!-- With controller -->
+<snice-login controller="auth-controller" title="Welcome" show-remember-me></snice-login>
 
 <!-- Variants -->
 <snice-login variant="card"></snice-login>
-<snice-login variant="minimal"></snice-login>
-
-<!-- Sizes -->
-<snice-login size="small"></snice-login>
-<snice-login size="large"></snice-login>
-
-<!-- Options -->
-<snice-login
-  title="Welcome Back"
-  action-text="Sign In"
-  show-remember-me
-  show-forgot-password>
-</snice-login>
+<snice-login variant="minimal" size="small"></snice-login>
 
-<!-- Custom subtitle/footer -->
+<!-- Custom slots -->
 <snice-login>
-  <p slot="subtitle">Please sign in to continue</p>
-  <div slot="footer">
-    <a href="/signup">Create account</a>
-  </div>
+  <p slot="subtitle">Please sign in</p>
+  <div slot="footer"><a href="/signup">Create account</a></div>
 </snice-login>
-
-<!-- Event handling (fallback) -->
-<script>
-const login = document.querySelector('snice-login');
-
-login.addEventListener('login-success', (e) => {
-  window.location = '/dashboard';
-});
-
-login.addEventListener('login-error', (e) => {
-  console.error(e.detail.error);
-});
-</script>
 ```
 
-## Slots
-
-- `before-header`, `after-header` - Around header
-- `subtitle` - Custom subtitle
-- `before-form`, `after-form` - Around form
-- `form-top` - Top of form
-- `between-fields` - Between username/password
-- `before-submit`, `after-submit` - Around button
-- `footer` - Footer content
+```typescript
+// Controller
+@controller('auth-controller')
+class AuthController {
+  @respond('login-user')
+  async handleLogin(creds: LoginCredentials): Promise<LoginResult> {
+    return { success: true, data: { token } };
+  }
+}
 
-## Features
-
-- @request/@respond with controllers (primary)
-- Event dispatch fallback
-- 3 visual variants
-- 3 sizes
-- Optional remember me
-- Optional forgot password
-- Loading/disabled states
-- Error display via alert component
-- Keyboard accessible (Enter to submit)
+// Event fallback
+login.addEventListener('login-success', () => location.href = '/dashboard');
+```

package/docs/ai/components/map.md

@@ -0,0 +1,72 @@
+# snice-map
+
+Interactive slippy map using OpenStreetMap tiles with markers, popups, drag panning, scroll zoom, and programmatic control.
+
+## Properties
+
+```ts
+center: MapCenter = { lat: 51.505, lng: -0.09 }  // Map center (set via JS)
+zoom: number = 13                                  // attr: zoom — Zoom level
+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
+```
+
+## Types
+
+```ts
+interface MapCenter {
+  lat: number;
+  lng: number;
+}
+
+interface MapMarker {
+  id: string;
+  lat: number;
+  lng: number;
+  label?: string;
+  icon?: string;
+  popup?: string;   // Popup text shown on marker click
+}
+```
+
+## Events
+
+- `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
+
+## Methods
+
+- `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)
+
+## Behavior
+
+- 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
+
+## Usage
+
+```html
+<snice-map zoom="10" min-zoom="3" max-zoom="16"></snice-map>
+```
+
+```js
+const map = document.querySelector('snice-map');
+map.center = { lat: 40.7128, lng: -74.006 };
+map.markers = [
+  { id: 'nyc', lat: 40.7128, lng: -74.006, label: 'NYC', popup: 'New York City' },
+  { id: 'bos', lat: 42.3601, lng: -71.0589, popup: 'Boston' }
+];
+map.fitBounds();
+map.addEventListener('marker-click', e => console.log(e.detail.marker.label));
+```

package/docs/ai/components/markdown.md

@@ -0,0 +1,63 @@
+# snice-markdown
+
+Lightweight GFM-compatible markdown renderer with built-in sanitization.
+
+## Properties
+
+```ts
+content: string                          // Markdown source text
+sanitize: boolean                        // Sanitize HTML output (default: true)
+theme: 'default' | 'github'             // Visual theme
+```
+
+## Events
+
+- `markdown-render` -> `{ html: string }` -- Fired after markdown is rendered
+- `link-click` -> `{ href: string; text: string }` -- Fired when a link is clicked (default prevented)
+
+## CSS Custom Properties
+
+```css
+--snice-font-family
+--snice-color-text
+--snice-color-primary              /* Link color */
+--snice-color-border               /* Headings, tables, code, blockquote borders */
+--snice-color-text-secondary       /* Strikethrough, blockquote text */
+--snice-color-text-tertiary        /* h6 color */
+--snice-color-background-element   /* Code, blockquote, table row backgrounds */
+--snice-line-height-normal
+--snice-font-size-md
+--snice-spacing-*                  /* Various spacing tokens */
+--snice-border-radius-md
+--snice-border-radius-lg
+--snice-font-weight-semibold
+```
+
+## Supported Markdown
+
+- 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
+
+## Usage
+
+```html
+<snice-markdown
+  content="# Hello\n\nThis is **bold** and *italic*."
+  theme="github"
+></snice-markdown>
+```
+
+```js
+const md = document.querySelector('snice-markdown');
+md.content = '## Dynamic Content\n\n- Item 1\n- Item 2';
+
+md.addEventListener('link-click', (e) => {
+  console.log('Navigating to:', e.detail.href);
+});
+```

package/docs/ai/components/masonry.md

@@ -5,22 +5,26 @@ Pinterest-style masonry layout using CSS columns.
 ## Properties
 
 ```typescript
-columns: number = 3;           // Column count (0 = auto based on minColumnWidth)
-gap: string = '1rem';          // Gap between items
-minColumnWidth: string = '250px'; // Min column width when columns=0
+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
 ```
 
+## Slots
+
+- `(default)` - Items to arrange in masonry layout
+
 ## Usage
 
 ```html
-<!-- Basic 3-column masonry -->
+<!-- Fixed columns -->
 <snice-masonry columns="3" gap="1rem">
   <div>Card 1</div>
   <div>Card 2</div>
   <div>Card 3</div>
 </snice-masonry>
 
-<!-- Auto columns based on min width -->
+<!-- Auto-responsive columns -->
 <snice-masonry columns="0" min-column-width="300px">
   <div>Card 1</div>
   <div>Card 2</div>
@@ -37,7 +41,7 @@ minColumnWidth: string = '250px'; // Min column width when columns=0
 
 - CSS columns-based layout (no JS measurement)
 - Auto-responsive when columns=0
-- Configurable gap via CSS variable
+- Configurable gap
 - Items flow top-to-bottom, left-to-right
 - `break-inside: avoid` on slotted children
 - `role="list"` for accessibility

package/docs/ai/components/menu.md

@@ -8,7 +8,7 @@ Dropdown menu with items, dividers, and configurable trigger behavior.
 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;
+closeOnSelect: boolean = true;       // attr: close-on-select
 distance: number = 4;
 ```
 
@@ -16,99 +16,67 @@ distance: number = 4;
 
 - `openMenu()` - Open the menu
 - `closeMenu()` - Close the menu
-- `toggleMenu()` - Toggle menu open/closed state
+- `toggleMenu()` - Toggle open/closed
 
-## Slots
+## Slots (menu)
 
-- `trigger` - Element that triggers the menu (required)
-- Default slot - Menu items and dividers
+- `trigger` - Trigger element (required)
+- `image-left` - Image before trigger
+- `image-right` - Image after trigger
+- `(default)` - Menu items and dividers
 
 ## Events
 
-- `menu-open` - Fired when menu opens (detail: { menu: SniceMenuElement })
-- `menu-close` - Fired when menu closes (detail: { menu: SniceMenuElement })
+- `menu-open` → `{ menu }`
+- `menu-close` → `{ menu }`
+- `menu-item-select` → `{ item, value }`
+
+## snice-menu-item
+
+```typescript
+value: string = '';
+disabled: boolean = false;
+selected: boolean = false;
+```
+
+Slots: `icon`, `(default)`, `shortcut`
+
+## snice-menu-divider
+
+Visual separator between items.
 
 ## Usage
 
 ```html
-<!-- Basic menu -->
 <snice-menu>
-  <button slot="trigger">Open Menu</button>
-  <snice-menu-item value="new">New File</snice-menu-item>
-  <snice-menu-item value="open">Open</snice-menu-item>
-  <snice-menu-divider></snice-menu-divider>
-  <snice-menu-item value="save">Save</snice-menu-item>
-</snice-menu>
-
-<!-- With icons and shortcuts -->
-<snice-menu>
-  <button slot="trigger">Edit</button>
-  <snice-menu-item value="cut">
-    <span slot="icon">✂️</span>
-    Cut
-    <span slot="shortcut">⌘X</span>
-  </snice-menu-item>
-  <snice-menu-item value="copy">
-    <span slot="icon">📋</span>
-    Copy
-    <span slot="shortcut">⌘C</span>
-  </snice-menu-item>
-  <snice-menu-item value="paste">
-    <span slot="icon">📄</span>
-    Paste
-    <span slot="shortcut">⌘V</span>
+  <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>
 
-<!-- Different placements -->
-<snice-menu placement="top-start">...</snice-menu>
-<snice-menu placement="right-start">...</snice-menu>
-
 <!-- Hover trigger -->
 <snice-menu trigger="hover">...</snice-menu>
 
 <!-- Manual control -->
-<snice-menu trigger="manual" id="my-menu">...</snice-menu>
-<script>
-  document.getElementById('my-menu').openMenu();
-</script>
+<snice-menu trigger="manual" id="m">...</snice-menu>
+<script>document.getElementById('m').openMenu();</script>
 
-<!-- Keep open on select -->
+<!-- Keep open -->
 <snice-menu close-on-select="false">...</snice-menu>
 ```
 
-## snice-menu-item
-
-### Properties
-
-```typescript
-value: string = '';
-disabled: boolean = false;
-selected: boolean = false;
-```
-
-### Slots
-
-- `icon` - Icon before label
-- Default slot - Item label
-- `shortcut` - Keyboard shortcut text
-
-### Events
-
-- `menu-item-select` - Fired when item is clicked (detail: { item: SniceMenuItemElement, value: string })
-
-## snice-menu-divider
-
-Visual separator between menu items.
-
 ## Features
 
 - 8 placement options
-- Click, hover, or manual trigger modes
-- Auto-close on item selection (configurable)
+- Click, hover, or manual trigger
+- Auto-close on select (configurable)
 - Auto-close on outside click
-- Icon and shortcut support
-- Disabled state for items
-- Selected state for items
-- Keyboard accessible (aria roles)
-- Configurable distance from trigger
+- Icon and shortcut slots
+- Disabled/selected item states
+- ARIA roles (menu, menuitem)

package/docs/ai/components/modal.md

@@ -5,66 +5,49 @@ Dialog overlay with focus trap, backdrop dismiss, and accessibility.
 ## Properties
 
 ```typescript
-open: boolean = false;                        // Visibility state
+open: boolean = false;
 size: 'small'|'medium'|'large'|'fullscreen' = 'medium';
-noBackdropDismiss: boolean = false;           // Prevent backdrop click close
-noEscapeDismiss: boolean = false;             // Prevent Escape key close
-noFocusTrap: boolean = false;                 // Disable focus trapping
-noCloseButton: boolean = false;               // Hide close button
-label: string = '';                           // Accessible label
+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
+label: string = '';                  // Accessible label
 ```
 
-## Methods
+## Slots
 
-```typescript
-show()   // Open modal
-close()  // Close modal
-```
+- `(default)` - Modal body content
+- `header` - Header content (title)
+- `footer` - Footer content (action buttons)
 
 ## Events
 
-```typescript
-'modal-open'   // Emitted when modal opens. Detail: { modal }
-'modal-close'  // Emitted when modal closes. Detail: { modal }
-```
+- `modal-open` → `{ modal: SniceModalElement }`
+- `modal-close` → `{ modal: SniceModalElement }`
 
-## Slots
+## Methods
 
-```html
-<snice-modal>
-  <div slot="header">Title</div>
-  <div>Body content</div>
-  <div slot="footer">Actions</div>
-</snice-modal>
-```
+- `show()` - Open modal
+- `close()` - Close modal
 
 ## Usage
 
-**Template syntax:**
-```typescript
-html`
-  <snice-modal
-    ?open=${this.isOpen}
-    label="Confirm Action"
-    @modal-close=${() => this.handleClose()}>
-    <span slot="header">Title</span>
-    <p>Content</p>
-    <div slot="footer">
-      <snice-button @click=${() => this.close()}>Cancel</snice-button>
-    </div>
-  </snice-modal>
-`
+```html
+<snice-modal label="Confirm Action">
+  <div slot="header"><h2>Confirm</h2></div>
+  <p>Are you sure?</p>
+  <div slot="footer">
+    <button onclick="this.closest('snice-modal').close()">Cancel</button>
+    <button onclick="this.closest('snice-modal').close()">Confirm</button>
+  </div>
+</snice-modal>
 ```
 
-**Imperative:**
 ```typescript
 const modal = document.querySelector('snice-modal');
 modal.show();
 modal.close();
-
-modal.addEventListener('modal-close', (e) => {
-  console.log('Modal closed');
-});
+modal.addEventListener('modal-close', () => console.log('Closed'));
 ```
 
 ## Features