snice 4.9.0 → 4.10.0

package/docs/ai/decorators.md

@@ -4,7 +4,7 @@
 - `@element('tag-name')` - Custom element
 - `@page({ tag, routes, guards?, placard? })` - Routable page
 - `@controller('name')` - Swappable behavior
-- `@layout('name')` - Page wrapper
+- `@layout('tag-name')` - Page wrapper for routing system
 
 ## Rendering
 - `@render()` - Template method, returns `html\`...\``
@@ -12,12 +12,14 @@
 - `@styles()` - Scoped CSS, returns `css\`...\``
 
 ## Properties
-- `@property({ type?, attribute?, reflect? })` - Reactive, syncs attrs
-- `@watch('propName')` - React to changes: `(old, new) => void`
+- `@property({ type?, attribute?, converter?, hasChanged? })` - Reactive, syncs attrs
+- `@watch('propName')` - React to changes: `(oldVal, newVal, propertyName) => void`
 
 ## Lifecycle
 - `@ready()` - After first render
 - `@dispose()` - Cleanup on disconnect
+- `@moved(options?: { throttle?, debounce? })` - On adoptedCallback (element moved between documents)
+- `@adopted(options?: { throttle?, debounce? })` - On adoptedCallback (alias for moved)
 
 ## DOM
 - `@query('selector')` - Single element
@@ -27,6 +29,26 @@
 - `@on('event', 'selector?')` - Delegation, auto-bound
 - `@dispatch('event-name')` - Emit CustomEvent, detail = return value
 
+## Communication
+- `@request(channel, options?)` - Async generator request pattern
+- `@respond(channel, options?)` - Handle requests from `@request`
+- `@context(options?)` - Receive router navigation context updates
+
+## Observers
+- `@observe(target, selector?, options?)` - Watch intersection, resize, media query, mutation
+  - `'intersection'` - Viewport visibility (IntersectionObserver)
+  - `'resize'` - Element size changes (ResizeObserver)
+  - `'media:(query)'` - Media query changes (e.g., `'media:(min-width: 768px)'`)
+  - `'mutation:childList'` - DOM child changes (MutationObserver)
+  - `'mutation:attributes'` - Attribute changes
+  - `'mutation:attributes:name'` - Watch specific attribute
+
+## Utility Method Decorators
+- `@debounce(wait?, { leading?, trailing?, maxWait? })` - Delay execution until calls stop
+- `@throttle(wait?, { leading?, trailing? })` - Limit calls to once per interval
+- `@once(perInstance?)` - Execute method only once
+- `@memoize({ keyGenerator?, maxSize?, ttl? })` - Cache return values
+
 ## Template Bindings
 ```
 attr="${val}"     - String attribute

package/docs/ai/patterns.md

@@ -41,7 +41,23 @@ class DataLoader implements IController {
   handleClick(e: Event) {}
 }
 
-// Usage: <my-list controller="data-loader"></my-list>
+// Usage on custom elements:
+// <my-list controller="data-loader"></my-list>
+
+// Usage on native HTML elements (requires opt-in):
+// <div controller="data-loader"></div>
+// <form controller="form-handler"></form>
+// <table controller="table-loader"></table>
+```
+
+**Native element controllers** — attach controllers to any HTML element (div, form, table, etc.):
+```typescript
+import { useNativeElementControllers } from 'snice';
+useNativeElementControllers(); // Call once at app start
+
+// Sets up MutationObserver watching for controller= on non-custom elements
+// Handles add/change/remove of controller attribute dynamically
+// Adds ready promise automatically for non-custom elements
 ```
 
 ## Page + Router

package/docs/components/accordion.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/accordion.md instead)
+
 # Accordion Components
 
 The accordion components provide collapsible sections of content. An `<snice-accordion>` container manages multiple `<snice-accordion-item>` elements, supporting single or multiple open items with keyboard navigation.
@@ -128,7 +130,7 @@ item.collapse(false); // Without animation
 
 ### Container Events
 
-#### `@snice/accordion-open`
+#### `accordion-open`
 Fired when an item is opened.
 
 **Event Detail:**
@@ -141,12 +143,12 @@ Fired when an item is opened.
 
 **Usage:**
 ```typescript
-accordion.addEventListener('@snice/accordion-open', (e) => {
+accordion.addEventListener('accordion-open', (e) => {
   console.log('Item opened:', e.detail.itemId);
 });
 ```
 
-#### `@snice/accordion-close`
+#### `accordion-close`
 Fired when an item is closed.
 
 **Event Detail:**
@@ -331,12 +333,12 @@ import type { SniceAccordionElement } from 'snice/components/accordion/snice-acc
 
 const accordion = document.querySelector<SniceAccordionElement>('snice-accordion');
 
-accordion.addEventListener('@snice/accordion-open', (e) => {
+accordion.addEventListener('accordion-open', (e) => {
   console.log('Opened item:', e.detail.itemId);
   // Track analytics, load content, etc.
 });
 
-accordion.addEventListener('@snice/accordion-close', (e) => {
+accordion.addEventListener('accordion-close', (e) => {
   console.log('Closed item:', e.detail.itemId);
 });
 
@@ -367,7 +369,7 @@ accordion.toggleItem('item-3');
 
   const accordion = document.querySelector('#lazyAccordion');
 
-  accordion.addEventListener('@snice/accordion-open', async (e) => {
+  accordion.addEventListener('accordion-open', async (e) => {
     const contentId = `content-${e.detail.itemId.split('-')[1]}`;
     const contentEl = document.querySelector(`#${contentId}`);
 

package/docs/components/alert.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/alert.md instead)
+
 # Alert Component
 
 The alert component displays notification messages to provide user feedback for informational, success, warning, or error states. It supports customizable variants, sizes, titles, icons, and optional dismissal.

package/docs/components/app-tiles.md

@@ -0,0 +1,162 @@
+# App Tiles
+`<snice-app-tiles>`
+
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/app-tiles.md instead)
+
+## App Tiles Component
+
+An app launcher grid like Google's app drawer or a phone home screen. Supports material icons, image URLs, emoji, and letter fallbacks with optional badges.
+
+## Table of Contents
+
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [Slots](#slots)
+- [Events](#events)
+- [Examples](#examples)
+
+## Basic Usage
+
+```html
+<snice-app-tiles columns="3">
+  <snice-app-tile name="Mail" icon="mail" color="rgb(220 38 38)"></snice-app-tile>
+  <snice-app-tile name="Calendar" icon="calendar_today" color="rgb(37 99 235)"></snice-app-tile>
+  <snice-app-tile name="Drive" icon="folder" color="rgb(234 88 12)"></snice-app-tile>
+</snice-app-tiles>
+```
+
+```typescript
+import 'snice/components/app-tiles/snice-app-tiles';
+```
+
+## Importing
+
+**ESM (bundler)**
+```typescript
+import 'snice/components/app-tiles/snice-app-tiles';
+```
+
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-app-tiles.min.js"></script>
+```
+
+## Examples
+
+### Material Icons
+
+Use the `icon` attribute with a Material Symbols ligature name.
+
+```html
+<snice-app-tiles columns="3">
+  <snice-app-tile name="Mail" icon="mail" color="rgb(220 38 38)"></snice-app-tile>
+  <snice-app-tile name="Calendar" icon="calendar_today" color="rgb(37 99 235)"></snice-app-tile>
+  <snice-app-tile name="Videos" icon="play_circle" color="rgb(220 38 38)" badge="5"></snice-app-tile>
+</snice-app-tiles>
+```
+
+### Letter Fallback
+
+When no `icon` is provided, the first letter of the name is used with the specified `color`.
+
+```html
+<snice-app-tiles columns="3">
+  <snice-app-tile name="Slack" color="rgb(97 31 105)"></snice-app-tile>
+  <snice-app-tile name="Figma" color="rgb(162 89 255)"></snice-app-tile>
+  <snice-app-tile name="GitHub" color="rgb(82 82 82)"></snice-app-tile>
+</snice-app-tiles>
+```
+
+### Image Icons (Programmatic)
+
+Set the `tiles` property with an array of tile objects to use image URLs.
+
+```javascript
+const tiles = document.querySelector('snice-app-tiles');
+tiles.columns = 3;
+tiles.tiles = [
+  { id: '1', name: 'Chrome', icon: 'https://cdn.example.com/chrome.svg' },
+  { id: '2', name: 'Slack', icon: 'https://cdn.example.com/slack.svg' },
+];
+```
+
+### List Variant
+
+Use `variant="list"` with `columns="1"` for a vertical list layout.
+
+```html
+<snice-app-tiles columns="1" variant="list">
+  <snice-app-tile name="Dashboard" icon="dashboard" color="rgb(37 99 235)"></snice-app-tile>
+  <snice-app-tile name="Analytics" icon="bar_chart" color="rgb(22 163 74)"></snice-app-tile>
+  <snice-app-tile name="Messages" icon="chat" color="rgb(147 51 234)" badge="8"></snice-app-tile>
+</snice-app-tiles>
+```
+
+### Sizes
+
+Use the `size` attribute to change tile size.
+
+```html
+<snice-app-tiles columns="2" size="sm">
+  <snice-app-tile name="Home" icon="home"></snice-app-tile>
+  <snice-app-tile name="Search" icon="search"></snice-app-tile>
+</snice-app-tiles>
+
+<snice-app-tiles columns="2" size="lg">
+  <snice-app-tile name="Music" icon="music_note" color="rgb(220 38 38)"></snice-app-tile>
+  <snice-app-tile name="Games" icon="sports_esports" color="rgb(22 163 74)"></snice-app-tile>
+</snice-app-tiles>
+```
+
+### Badges
+
+Use the `badge` attribute to display a notification badge on a tile.
+
+```html
+<snice-app-tile name="Messages" icon="chat" badge="12"></snice-app-tile>
+<snice-app-tile name="AWS" color="rgb(255 153 0)" badge="!"></snice-app-tile>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `tiles` | `AppTile[]` | `[]` | Array of tile data objects (programmatic mode) |
+| `columns` | `number` | `4` | Number of grid columns |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Tile size |
+| `variant` | `'grid' \| 'list'` | `'grid'` | Layout variant |
+
+### AppTile Interface
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `id` | `string` | Unique identifier |
+| `name` | `string` | Tile label |
+| `icon` | `string` | URL, emoji, or Material Symbols ligature name |
+| `color` | `string?` | Background color for letter/ligature fallback |
+| `href` | `string?` | Navigation URL on click |
+| `badge` | `string?` | Badge content |
+
+### snice-app-tile Attributes
+
+| Attribute | Description |
+|-----------|-------------|
+| `name` | Tile label |
+| `icon` | URL, emoji, or Material Symbols ligature |
+| `color` | Background color |
+| `href` | Navigation URL |
+| `badge` | Badge content |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `tile-click` | `{ tile: AppTile, index: number }` | Fired when a tile is clicked |
+
+## Icon Resolution Order
+
+1. No icon provided: displays first letter of name on a colored circle
+2. `img://` prefix or URL/path: renders as `<img>` element
+3. Emoji characters (no ASCII letters): renders as emoji
+4. ASCII text: renders as Material Symbols ligature

package/docs/components/audio-recorder.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/audio-recorder.md instead)
+
 # Audio Recorder Component
 
 Record audio with visualization, pause/resume, and playback.
@@ -28,6 +30,7 @@ Record audio with visualization, pause/resume, and playback.
 | `showVisualizer` | `boolean` | `true` | Show frequency visualizer |
 | `maxDuration` | `number` | `0` | Max duration (seconds, 0=unlimited) |
 | `showTimer` | `boolean` | `true` | Show recording timer |
+| `showPlayback` | `boolean` | `true` | Show playback controls after recording |
 
 ## Audio Formats
 
@@ -65,6 +68,9 @@ Check if currently recording.
 ### `download(filename?): void`
 Download recorded audio.
 
+### `reset(): void`
+Reset recorder state and discard playback.
+
 ## Events
 
 - `recorder-start` - Recording started

package/docs/components/avatar.md

@@ -0,0 +1,225 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/avatar.md instead)
+
+# Avatar
+`<snice-avatar>`
+
+Displays a user profile image with automatic fallback to name-based initials or a default person icon.
+
+## Basic Usage
+
+```typescript
+import 'snice/components/avatar/snice-avatar';
+```
+
+```html
+<snice-avatar src="/user.jpg" name="John Doe"></snice-avatar>
+```
+
+## Importing
+
+**ESM (bundler)**
+```typescript
+import 'snice/components/avatar/snice-avatar';
+```
+
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-avatar.min.js"></script>
+```
+
+## Examples
+
+### With Image
+
+Use the `src` attribute to display a profile image. The `name` attribute provides alt text and fallback initials.
+
+```html
+<snice-avatar src="/photos/sarah.jpg" name="Sarah Johnson"></snice-avatar>
+<snice-avatar src="/photos/michael.jpg" name="Michael Chen"></snice-avatar>
+<snice-avatar src="/photos/emma.jpg" name="Emma Wilson"></snice-avatar>
+```
+
+### Initials Fallback
+
+When no `src` is provided or the image fails to load, the component displays initials extracted from the `name`.
+
+```html
+<snice-avatar name="John Doe"></snice-avatar>
+<snice-avatar name="Jane Smith"></snice-avatar>
+<snice-avatar name="Alice"></snice-avatar>
+```
+
+### Default Icon
+
+When neither `src` nor `name` is provided, a generic person icon is displayed.
+
+```html
+<snice-avatar></snice-avatar>
+```
+
+### Sizes
+
+Use the `size` attribute to change the avatar dimensions.
+
+```html
+<snice-avatar name="XS" size="xs"></snice-avatar>
+<snice-avatar name="SM" size="small"></snice-avatar>
+<snice-avatar name="MD" size="medium"></snice-avatar>
+<snice-avatar name="LG" size="large"></snice-avatar>
+<snice-avatar name="XL" size="xl"></snice-avatar>
+<snice-avatar name="XX" size="xxl"></snice-avatar>
+```
+
+### Shapes
+
+Use the `shape` attribute to change the avatar shape.
+
+```html
+<snice-avatar name="Circle" shape="circle" size="large"></snice-avatar>
+<snice-avatar name="Square" shape="square" size="large"></snice-avatar>
+<snice-avatar name="Rounded" shape="rounded" size="large"></snice-avatar>
+```
+
+### Auto-generated Colors
+
+Each name produces a consistent background color from a 15-color palette, so the same user always gets the same color.
+
+```html
+<snice-avatar name="Alice Johnson"></snice-avatar>
+<snice-avatar name="Bob Smith"></snice-avatar>
+<snice-avatar name="Carol White"></snice-avatar>
+<snice-avatar name="David Brown"></snice-avatar>
+```
+
+### Custom Fallback Colors
+
+Use `fallback-color` and `fallback-background` to override the auto-generated colors.
+
+```html
+<snice-avatar
+  name="Custom"
+  fallback-color="#fff"
+  fallback-background="#3b82f6">
+</snice-avatar>
+<snice-avatar
+  name="Brand"
+  fallback-color="#000"
+  fallback-background="#f59e0b">
+</snice-avatar>
+```
+
+### Broken Image Fallback
+
+When an image fails to load, the component automatically shows initials instead.
+
+```html
+<snice-avatar
+  src="https://broken-url.com/404.jpg"
+  name="Fallback User">
+</snice-avatar>
+```
+
+### Avatar Group
+
+Stack avatars with negative margins to create an overlapping group.
+
+```html
+<style>
+  .avatar-group {
+    display: flex;
+    align-items: center;
+  }
+  .avatar-group snice-avatar {
+    margin-left: -12px;
+    border: 3px solid white;
+    border-radius: 50%;
+  }
+  .avatar-group snice-avatar:first-child {
+    margin-left: 0;
+  }
+</style>
+
+<div class="avatar-group">
+  <snice-avatar src="/photos/user1.jpg" name="User 1"></snice-avatar>
+  <snice-avatar src="/photos/user2.jpg" name="User 2"></snice-avatar>
+  <snice-avatar src="/photos/user3.jpg" name="User 3"></snice-avatar>
+  <snice-avatar name="+5" fallback-background="#e5e7eb"></snice-avatar>
+</div>
+```
+
+### Profile Card
+
+Combine with other elements for a profile card layout.
+
+```html
+<div style="display: flex; align-items: center; gap: 16px; padding: 16px; border: 1px solid #e5e7eb; border-radius: 8px;">
+  <snice-avatar
+    src="/photos/sarah.jpg"
+    name="Sarah Johnson"
+    size="large">
+  </snice-avatar>
+  <div>
+    <p style="font-weight: 600; margin: 0;">Sarah Johnson</p>
+    <p style="color: #6b7280; font-size: 14px; margin: 4px 0 0 0;">Senior Developer</p>
+  </div>
+</div>
+```
+
+### Comment Thread
+
+Use small avatars alongside user-generated content.
+
+```html
+<div style="display: flex; gap: 12px;">
+  <snice-avatar name="Emma Wilson" size="medium"></snice-avatar>
+  <div>
+    <span style="font-weight: 600;">Emma Wilson</span>
+    <span style="color: #6b7280; font-size: 12px;"> 2 hours ago</span>
+    <p style="margin: 4px 0 0 0;">Great implementation!</p>
+  </div>
+</div>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `src` | `string` | `''` | Image URL |
+| `alt` | `string` | `''` | Alt text for the image (falls back to `name`) |
+| `name` | `string` | `''` | User's name (used for initials and color generation) |
+| `size` | `'xs' \| 'small' \| 'medium' \| 'large' \| 'xl' \| 'xxl'` | `'medium'` | Avatar size |
+| `shape` | `'circle' \| 'square' \| 'rounded'` | `'circle'` | Avatar shape |
+| `fallbackColor` (attr: `fallback-color`) | `string` | `'#ffffff'` | Text color for initials fallback |
+| `fallbackBackground` (attr: `fallback-background`) | `string` | `''` | Background color for initials fallback (overrides auto-color) |
+
+## Methods
+
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `getInitials()` | `name: string` | Extract initials from a name string |
+
+## CSS Custom Properties
+
+| Property | Description | Default |
+|----------|-------------|---------|
+| `--avatar-size` | Avatar dimensions | Varies by `size` attribute |
+| `--avatar-bg` | Background color | Auto-generated from name |
+| `--avatar-color` | Text/icon color | `hsl(0 0% 100%)` |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| — | No exported parts |
+
+## Size Reference
+
+| Size | Dimensions | Font Size |
+|------|-----------|-----------|
+| `xs` | 1.5rem (24px) | 0.625rem (10px) |
+| `small` | 2rem (32px) | 0.75rem (12px) |
+| `medium` | 2.5rem (40px) | 0.875rem (14px) |
+| `large` | 3rem (48px) | 1rem (16px) |
+| `xl` | 4rem (64px) | 1.25rem (20px) |
+| `xxl` | 6rem (96px) | 2rem (32px) |

package/docs/components/badge.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/badge.md instead)
+
 # Badge Component
 
 The badge component displays notification indicators, status markers, and counts. It can be positioned on other elements or used inline, with support for custom colors, sizes, and animations.

package/docs/components/banner.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/banner.md instead)
+
 # Banner Component
 
 The `<snice-banner>` component displays fixed-position notification banners at the top or bottom of the viewport.