snice 4.8.0 → 4.10.0

package/docs/ai/components/layout.md

@@ -1,22 +1,18 @@
 # snice-layout
 
-Collection of pre-built page layouts for common application patterns.
+Application layout with header navigation, main content area, and footer.
 
-## snice-layout
-
-Base layout with header navigation, main content area, and footer.
-
-### Slots
+## Slots
 
 - `brand` - Logo/brand in header
 - `page` - Main page content
 - `footer` - Footer content
 
-### Methods
+## Methods
 
-- `update(appContext, placards, currentRoute, routeParams)` - Update layout navigation
+- `update(appContext, placards, currentRoute, routeParams)` - Update layout navigation from router state
 
-### Usage
+## Usage
 
 ```html
 <snice-layout>
@@ -27,235 +23,14 @@ Base layout with header navigation, main content area, and footer.
     <!-- Page content -->
   </div>
   <div slot="footer">
-    <p>© 2025 My Company</p>
+    <p>&copy; 2025 My Company</p>
   </div>
 </snice-layout>
 ```
 
-## snice-layout-centered
-
-Centered single-column layout with configurable width.
-
-### Properties
-
-```typescript
-width: 'sm'|'md'|'lg'|'xl' = 'md';
-```
-
-### Slots
-
-- `page` - Main content (centered)
-
-### Usage
-
-```html
-<snice-layout-centered width="lg">
-  <div slot="page">
-    <!-- Centered content -->
-  </div>
-</snice-layout-centered>
-```
-
-## snice-layout-split
-
-Two-column split layout.
-
-### Slots
-
-- `left` - Left column content
-- `right` - Right column content
-
-### Usage
-
-```html
-<snice-layout-split>
-  <div slot="left">
-    <!-- Left sidebar -->
-  </div>
-  <div slot="right">
-    <!-- Main content -->
-  </div>
-</snice-layout-split>
-```
-
-## snice-layout-sidebar
-
-Layout with collapsible sidebar and main content area.
-
-### Slots
-
-- `brand` - Logo/brand in sidebar header
-- `sidebar` - Sidebar navigation content
-- `page` - Main page content
-- `footer` - Footer content
-
-### Usage
-
-```html
-<snice-layout-sidebar>
-  <div slot="brand">
-    <h1>My App</h1>
-  </div>
-  <nav slot="sidebar">
-    <!-- Sidebar navigation -->
-  </nav>
-  <div slot="page">
-    <!-- Main content -->
-  </div>
-</snice-layout-sidebar>
-```
-
-## snice-layout-dashboard
-
-Dashboard layout with header, sidebar, and content grid.
-
-### Slots
-
-- `brand` - Logo/brand
-- `header` - Top header content
-- `sidebar` - Left sidebar navigation
-- `page` - Main dashboard content
-
-### Usage
-
-```html
-<snice-layout-dashboard>
-  <div slot="brand">
-    <h1>Dashboard</h1>
-  </div>
-  <div slot="header">
-    <!-- User menu, notifications -->
-  </div>
-  <nav slot="sidebar">
-    <!-- Nav items -->
-  </nav>
-  <div slot="page">
-    <!-- Dashboard widgets -->
-  </div>
-</snice-layout-dashboard>
-```
-
-## snice-layout-landing
-
-Landing page layout with hero section.
-
-### Slots
-
-- `header` - Top navigation
-- `hero` - Hero section
-- `page` - Main content
-- `footer` - Footer
-
-### Usage
-
-```html
-<snice-layout-landing>
-  <nav slot="header">
-    <!-- Top nav -->
-  </nav>
-  <div slot="hero">
-    <h1>Welcome</h1>
-  </div>
-  <div slot="page">
-    <!-- Features, content -->
-  </div>
-  <footer slot="footer">
-    <!-- Links, copyright -->
-  </footer>
-</snice-layout-landing>
-```
-
-## snice-layout-blog
-
-Blog-style layout with header, content, and sidebar.
-
-### Slots
-
-- `header` - Header navigation
-- `page` - Main blog content
-- `sidebar` - Blog sidebar (recent posts, categories)
-- `footer` - Footer
-
-### Usage
-
-```html
-<snice-layout-blog>
-  <nav slot="header">
-    <!-- Blog nav -->
-  </nav>
-  <article slot="page">
-    <!-- Blog post -->
-  </article>
-  <aside slot="sidebar">
-    <!-- Recent posts, categories -->
-  </aside>
-</snice-layout-blog>
-```
-
-## snice-layout-fullscreen
-
-Full viewport layout with no margins.
-
-### Slots
-
-- `page` - Fullscreen content
-
-### Usage
-
-```html
-<snice-layout-fullscreen>
-  <div slot="page">
-    <!-- Fullscreen app -->
-  </div>
-</snice-layout-fullscreen>
-```
-
-## snice-layout-minimal
-
-Minimal layout with just header and content.
-
-### Slots
-
-- `header` - Minimal header
-- `page` - Main content
-
-### Usage
-
-```html
-<snice-layout-minimal>
-  <div slot="header">
-    <h1>Simple App</h1>
-  </div>
-  <div slot="page">
-    <!-- Content -->
-  </div>
-</snice-layout-minimal>
-```
-
-## snice-layout-card
-
-Card-based centered layout for login/signup pages.
-
-### Slots
-
-- `page` - Card content
-
-### Usage
-
-```html
-<snice-layout-card>
-  <div slot="page">
-    <h2>Sign In</h2>
-    <!-- Login form -->
-  </div>
-</snice-layout-card>
-```
-
 ## Features
 
-- 10 pre-built layout patterns
-- Responsive design
-- Slotted content areas
-- Navigation integration (where applicable)
-- Router integration support
-- Common UI patterns (dashboard, blog, landing, etc.)
+- Grid layout: header, main, footer
+- Integrated `snice-nav` in header
+- Router integration via `update()` method
+- Slotted brand, page, and footer areas

package/docs/ai/components/link-preview.md

@@ -1,6 +1,6 @@
 # snice-link-preview
 
-Social media-style link preview card. Purely visual -- all data passed via properties.
+Rich URL preview card with image, title, description, and site info.
 
 ## Properties
 
@@ -8,51 +8,42 @@ Social media-style link preview card. Purely visual -- all data passed via prope
 url: string = '';
 title: string = '';
 description: string = '';
-image: string = '';                              // image URL
-siteName: string = '';                           // attribute: site-name
-favicon: string = '';                            // small icon URL
-variant: 'horizontal' | 'vertical' = 'vertical';
-size: 'small' | 'medium' | 'large' = 'medium';
+image: string = '';
+siteName: string = '';  // attr: site-name
+favicon: string = '';
+variant: 'vertical'|'horizontal' = 'vertical';
+size: 'small'|'medium'|'large' = 'medium';
 ```
 
 ## Events
 
-```typescript
-'@snice/link-click': CustomEvent<{ url: string }>  // emitted on click
-```
+- `@snice/link-click` → `{ url: string }`
 
 ## Usage
 
 ```html
 <!-- Vertical (default) -->
 <snice-link-preview
+  url="https://example.com"
   title="Article Title"
-  description="A brief summary of the article content."
-  image="https://example.com/og-image.jpg"
+  description="Brief summary."
+  image="/images/og.jpg"
   site-name="example.com"
-  favicon="https://example.com/favicon.ico"
-  url="https://example.com/article"
-></snice-link-preview>
+  favicon="/icons/favicon.ico">
+</snice-link-preview>
 
 <!-- Horizontal, small -->
-<snice-link-preview
-  variant="horizontal"
-  size="small"
-  title="Quick Link"
-  description="Short description"
-  site-name="example.com"
-  url="https://example.com"
-></snice-link-preview>
+<snice-link-preview variant="horizontal" size="small"
+  url="https://example.com" title="Quick Link" description="Short.">
+</snice-link-preview>
 ```
 
 ## Features
 
 - Vertical (image top) and horizontal (image left) layouts
 - 3 sizes: small, medium, large
-- Image with fallback placeholder
-- Title truncation (2 lines), description truncation (3 lines)
-- Domain extraction from URL
-- Favicon + site name footer
-- Hover shadow effect
-- Click opens URL in new tab
-- Accessible: role="article", keyboard navigable
+- Placeholder icon when no image
+- Title clamped to 2 lines, description to 3
+- Domain extracted from URL
+- Click opens URL in new tab (noopener, noreferrer)
+- Keyboard accessible (Enter/Space)

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