snice 4.9.0 → 4.10.0

package/docs/ai/components/link.md

@@ -1,77 +1,57 @@
 # snice-link
 
-Link component with variants and external link handling.
+Hyperlink component with variants, external link handling, and hash routing.
 
 ## Properties
 
 ```typescript
-href: string = ''                      // Link URL
-target: LinkTarget = '_self'           // '_self' | '_blank' | '_parent' | '_top'
-variant: LinkVariant = 'default'       // 'default' | 'primary' | 'secondary' | 'muted'
-disabled: boolean = false              // Disable link
-external: boolean = false              // Auto _blank + noopener
-underline: boolean = false             // Show underline
-hash: boolean = false                  // Auto prepend # to href (for hash routing)
+href: string = '';
+target: '_self'|'_blank'|'_parent'|'_top' = '_self';
+variant: 'default'|'primary'|'secondary'|'muted' = 'default';
+disabled: boolean = false;
+external: boolean = false;   // auto _blank + noopener noreferrer + arrow icon
+underline: boolean = false;
+hash: boolean = false;        // auto-prepend # to href
 ```
 
+## Slots
+
+- `(default)` - Link text content
+
 ## Events
 
-```typescript
-@dispatch('click')     // Emitted on click (prevented if disabled)
-@dispatch('navigate')  // Emitted on hash link click (for router integration)
-                       // detail: { href: string }
-                       // cancelable: true
-```
+- `click` → `MouseEvent` (prevented when disabled)
+- `navigate` → `{ href: string }` (hash links only, cancelable)
+
+## CSS Parts
+
+- `link` - Anchor element
+- `external-icon` - External arrow icon
 
 ## Usage
 
 ```html
 <!-- Basic -->
-<snice-link href="/page">Link text</snice-link>
-
-<!-- External -->
-<snice-link href="https://example.com" external>External</snice-link>
+<snice-link href="/about">About</snice-link>
 
 <!-- Variants -->
 <snice-link href="/page" variant="primary">Primary</snice-link>
 <snice-link href="/page" variant="secondary">Secondary</snice-link>
 <snice-link href="/page" variant="muted">Muted</snice-link>
 
+<!-- External (auto _blank + noopener + arrow icon) -->
+<snice-link href="https://example.com" external>External</snice-link>
+
 <!-- Underlined -->
-<snice-link href="/page" underline>Underlined link</snice-link>
+<snice-link href="/docs" underline>Docs</snice-link>
 
 <!-- Disabled -->
 <snice-link href="/page" disabled>Disabled</snice-link>
 
-<!-- Hash links (for routing) -->
+<!-- Hash routing -->
 <snice-link href="home" hash>Home</snice-link>
-<snice-link href="about" hash>About</snice-link>
-<!-- Renders as: <a href="#home">Home</a> -->
+<!-- Renders: <a href="#home">Home</a> -->
 
 <!-- Router integration -->
-<snice-link href="profile" hash @navigate="${handleNavigate}">Profile</snice-link>
-<script>
-  function handleNavigate(e) {
-    console.log('Navigate to:', e.detail.href);
-    // e.preventDefault() in the handler will cancel navigation
-  }
-</script>
-```
-
-## CSS Parts
-
-```css
-::part(link)          /* Anchor element */
-::part(external-icon) /* External icon */
-```
-
-## Styling
-
-```css
---snice-color-primary
---snice-color-primary-dark
---snice-color-text-secondary
---snice-color-text
---snice-color-text-muted
---snice-color-text-disabled
+<snice-link href="profile" hash @navigate="${e => router.go(e.detail.href)}">Profile</snice-link>
 ```

package/docs/ai/components/list.md

@@ -1,50 +1,70 @@
 # snice-list
 
-List of items with optional selection, icons, descriptions.
+List container with search, infinite scroll, and composable list items.
 
 ## Properties
 
 ```typescript
-items: ListItem[] = [];
-selectionMode: 'single'|'multiple'|'none' = 'none';
-selectedItems: string[] = [];
-hoverable: boolean = true;
+// snice-list
 dividers: boolean = false;
-dense: boolean = false;
+searchable: boolean = false;
+search: string = '';
+infinite: boolean = false;
+loading: boolean = false;
+noResults: boolean = false;    // attr: no-results
+threshold: number = 0.5;
+skeletonCount: number = 5;     // attr: skeleton-count
+
+// snice-list-item
+heading: string = '';
+description: string = '';
+selected: boolean = false;
+disabled: boolean = false;
 ```
 
-## ListItem
+## Slots (snice-list)
 
-```typescript
-interface ListItem {
-  id: string;
-  label: string;
-  description?: string;
-  icon?: string;
-  iconImage?: string;
-  disabled?: boolean;
-  selected?: boolean;
-  data?: any;
-}
-```
+- `(default)` - List items
+- `before` - Content before items
+- `after` - Content after items
+- `no-results` - Custom empty state
+- `loading` - Custom loading content
 
-## Methods
+## Slots (snice-list-item)
 
-- `selectItem(id)`, `deselectItem(id)`, `toggleSelection(id)`
-- `getSelectedItems(): ListItem[]`
+- `(default)` - Custom content
+- `before` - Icon/avatar area
+- `after` - Badge/metadata area
 
-## Events
+## Requests
 
-- `@snice/list-item-select` (detail: { item, selected, list })
+- `@snice/list/search` → `{ query, list }` - Handle search
+- `@snice/list/load-more` → `{ page, list }` - Infinite scroll
 
 ## Usage
 
 ```html
-<snice-list id="list" selection-mode="single" dividers></snice-list>
-<script>
-  list.items = [
-    { id: '1', label: 'Item 1', description: 'First', icon: '📄' },
-    { id: '2', label: 'Item 2', description: 'Second', icon: '📄' }
-  ];
-</script>
+<!-- Basic with dividers -->
+<snice-list dividers>
+  <snice-list-item heading="Inbox" description="3 unread"></snice-list-item>
+  <snice-list-item heading="Sent" description="Last 2h ago"></snice-list-item>
+</snice-list>
+
+<!-- With icons -->
+<snice-list-item heading="Downloads">
+  <span slot="before">📥</span>
+  <span slot="after">12</span>
+</snice-list-item>
+
+<!-- Searchable -->
+<snice-list searchable dividers></snice-list>
+
+<!-- Infinite scroll (needs scrollable parent) -->
+<div style="height:300px;overflow-y:auto">
+  <snice-list infinite></snice-list>
+</div>
+
+<!-- Loading / empty -->
+<snice-list loading skeleton-count="3"></snice-list>
+<snice-list no-results></snice-list>
 ```

package/docs/ai/components/location.md

@@ -11,14 +11,14 @@ address: string = '';
 city: string = '';
 state: string = '';
 country: string = '';
-zipCode: string = '';
+zipCode: string = '';           // attr: zip-code
 latitude: number | string = '';
 longitude: number | string = '';
-showMap: boolean = false;
-showIcon: boolean = true;
+showMap: boolean = false;        // attr: show-map
+showIcon: boolean = true;        // attr: show-icon
 icon: string = '📍';
-iconImage: string = '';
-mapUrl: string = '';
+iconImage: string = '';          // attr: icon-image
+mapUrl: string = '';             // attr: map-url
 clickable: boolean = false;
 ```
 
@@ -28,16 +28,14 @@ clickable: boolean = false;
 
 ## Methods
 
-```typescript
-getData(): LocationData
-getCoordinates(): { latitude: number; longitude: number } | null
-getFullAddress(): string
-openMap(): void
-```
+- `getData()` - Returns LocationData object
+- `getCoordinates()` - Returns `{ latitude, longitude }` or null
+- `getFullAddress()` - Returns formatted address string
+- `openMap()` - Opens location in maps app (new tab)
 
 ## Events
 
-- `location-click` - Dispatched when clicked (detail: LocationData)
+- `location-click` → `LocationData` - Clicked (when clickable)
 
 ## Usage
 
@@ -53,21 +51,12 @@ openMap(): void
 </snice-location>
 
 <!-- With embedded map -->
-<snice-location
-  name="Times Square"
-  latitude="40.7580"
-  longitude="-73.9855"
-  show-map>
-</snice-location>
+<snice-location name="Times Square" latitude="40.7580" longitude="-73.9855" show-map></snice-location>
 
 <!-- Coordinates only -->
-<snice-location
-  latitude="40.7580"
-  longitude="-73.9855"
-  mode="coordinates">
-</snice-location>
+<snice-location latitude="40.7580" longitude="-73.9855" mode="coordinates"></snice-location>
 
-<!-- Icon slot (for external CSS icon fonts like Material Symbols) -->
+<!-- Icon slot -->
 <snice-location name="Office" address="123 Main St">
   <span slot="icon" class="material-symbols-outlined">business</span>
 </snice-location>
@@ -75,10 +64,9 @@ openMap(): void
 
 ## Features
 
-- Multiple display modes (full/compact/coordinates/address)
+- 4 display modes (full/compact/coordinates/address)
 - Embedded Google Maps support
-- Custom icons (URL, image files, emoji, font ligatures)
+- Custom icons (emoji, URL, image, font ligatures, slot)
 - Clickable to open in maps app
 - Custom map URL support
 - Complete address formatting
-- Coordinate validation

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