snice 4.9.0 → 4.10.0

package/dist/index.esm.js

@@ -1,5 +1,5 @@
 /*!
- * snice v4.8.0
+ * snice v4.9.0
  * Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.

package/dist/index.iife.js

@@ -1,5 +1,5 @@
 /*!
- * snice v4.8.0
+ * snice v4.9.0
  * Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.

package/dist/symbols.cjs

@@ -1,5 +1,5 @@
 /*!
- * snice v4.8.0
+ * snice v4.9.0
  * Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.

package/dist/symbols.esm.js

@@ -1,5 +1,5 @@
 /*!
- * snice v4.8.0
+ * snice v4.9.0
  * Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.

package/dist/transitions.cjs

@@ -1,5 +1,5 @@
 /*!
- * snice v4.8.0
+ * snice v4.9.0
  * Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.

package/dist/transitions.esm.js

@@ -1,5 +1,5 @@
 /*!
- * snice v4.8.0
+ * snice v4.9.0
  * Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.

package/docs/ai/DEVELOPMENT.md

@@ -89,7 +89,7 @@ All CDN builds use the shared runtime (external `snice` imports). Load `snice-ru
 - IIFE: `.js` + `.min.js`
 - Sourcemaps + README
 
-**Size:** Runtime ~18KB gzip, components ~1-27KB each
+**Size:** Runtime ~18KB gzip, components ~1-93KB each
 
 **Features:**
 - Shared runtime (external snice imports)

package/docs/ai/api.md

@@ -35,12 +35,12 @@
 ## Properties
 
 ```typescript
-@property(options?: { type?, attribute?, reflect? })
+@property(options?: { type?, attribute?, converter?, hasChanged? })
 // Syncs with attributes, triggers re-render
 // Types: String (default), Number, Boolean, Object, Array
 
 @watch(...propertyNames: string[])
-// Called on property change: (oldVal, newVal) => void
+// Called on property change: (oldVal, newVal, propertyName) => void
 ```
 
 ## Lifecycle
@@ -274,6 +274,9 @@ import {
   observe,
   ready, dispose, moved, adopted,
   Router,
-  debounce, throttle, once, memoize
+  debounce, throttle, once, memoize,
+  useNativeElementControllers,   // Enable controller= on native HTML elements
+  cleanupNativeElementControllers,
+  attachController, detachController, getController
 } from 'snice';
 ```

package/docs/ai/components/accordion.md

@@ -131,39 +131,6 @@ item.collapse();
 - Accessibility: aria-expanded, button roles
 - Smooth animations
 
-## Common Patterns
-
-**FAQ:**
-```html
-<snice-accordion>
-  <snice-accordion-item item-id="q1">
-    <span slot="header">Question?</span>
-    <p>Answer.</p>
-  </snice-accordion-item>
-</snice-accordion>
-```
-
-**Settings:**
-```html
-<snice-accordion multiple>
-  <snice-accordion-item item-id="general">
-    <span slot="header">General</span>
-    <!-- Settings form -->
-  </snice-accordion-item>
-</snice-accordion>
-```
-
-**Lazy loading:**
-```typescript
-accordion.addEventListener('accordion-open', async (e) => {
-  if (!loaded[e.detail.itemId]) {
-    const data = await fetch(`/api/${e.detail.itemId}`);
-    // Update content
-    loaded[e.detail.itemId] = true;
-  }
-});
-```
-
 ## Notes
 
 - Items are light DOM children (not slotted)
@@ -171,4 +138,3 @@ accordion.addEventListener('accordion-open', async (e) => {
 - Item IDs auto-generated if not provided
 - Disabled items cannot be toggled
 - Header slot required for trigger content
-- Full ARIA support for screen readers

package/docs/ai/components/app-tiles.md

@@ -0,0 +1,77 @@
+# snice-app-tiles
+
+App launcher grid like Google's app drawer or a phone home screen.
+
+## Properties
+
+```typescript
+// snice-app-tiles
+tiles: AppTile[] = [];           // Programmatic tile data
+columns: number = 4;             // Grid columns
+size: 'sm' | 'md' | 'lg' = 'md'; // Tile size
+variant: 'grid' | 'list' = 'grid'; // Layout variant
+
+// AppTile interface
+interface AppTile {
+  id: string;
+  name: string;
+  icon: string;       // URL, emoji, or Material Symbols ligature name
+  color?: string;     // Background color for letter/ligature fallback
+  href?: string;      // Navigate on click
+  badge?: string;     // Badge content (uses snice-badge)
+}
+```
+
+## Child Element
+
+`<snice-app-tile>` — declarative child for defining tiles in HTML.
+
+- `name` - Tile label
+- `icon` - URL, emoji, or Material Symbols ligature
+- `color` - Background color
+- `href` - Navigation URL
+- `badge` - Badge content
+
+## Events
+
+- `tile-click` -> `{ tile: AppTile, index: number }`
+
+## Icon Resolution
+
+1. No icon -> letter fallback (first char of name, colored circle)
+2. `img://` prefix or URL/path -> `<img>` element
+3. Emoji (no ASCII letters) -> emoji display
+4. ASCII text -> Material Symbols ligature
+
+## Usage
+
+```html
+<!-- Declarative -->
+<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)" badge="3"></snice-app-tile>
+</snice-app-tiles>
+
+<!-- Programmatic with image icons -->
+<snice-app-tiles id="tiles" columns="3"></snice-app-tiles>
+<script>
+  const tiles = document.querySelector('#tiles');
+  tiles.tiles = [
+    { id: '1', name: 'Chrome', icon: 'https://example.com/chrome.svg' },
+    { id: '2', name: 'Slack', icon: 'https://example.com/slack.svg' },
+  ];
+</script>
+
+<!-- Letter fallback (no icon) -->
+<snice-app-tiles columns="3">
+  <snice-app-tile name="Slack" color="rgb(97 31 105)"></snice-app-tile>
+  <snice-app-tile name="GitHub" color="rgb(82 82 82)"></snice-app-tile>
+</snice-app-tiles>
+
+<!-- List variant -->
+<snice-app-tiles columns="1" variant="list">
+  <snice-app-tile name="Dashboard" icon="dashboard"></snice-app-tile>
+  <snice-app-tile name="Settings" icon="settings"></snice-app-tile>
+</snice-app-tiles>
+```

package/docs/ai/components/audio-recorder.md

@@ -12,6 +12,7 @@ showControls: boolean = true;
 showVisualizer: boolean = true;
 maxDuration: number = 0;
 showTimer: boolean = true;
+showPlayback: boolean = true;
 ```
 
 ## Methods
@@ -26,6 +27,7 @@ getState(): 'inactive'|'recording'|'paused'
 getDuration(): number
 isRecording(): boolean
 download(filename?: string): void
+reset(): void
 ```
 
 ## AudioRecording

package/docs/ai/components/badge.md

@@ -17,6 +17,13 @@ pulse: boolean = false;
 offset: number = 0;
 ```
 
+## Methods
+
+- `setBadgeContent(content)` - Set text content
+- `setBadgeCount(count)` - Set numeric count
+- `showDot()` - Switch to dot mode
+- `hide()` - Clear all content
+
 ## Usage
 
 ```html

package/docs/ai/components/book.md

@@ -0,0 +1,78 @@
+# snice-book
+
+Page-flipping book component with spread/single modes, cover page, touch/keyboard navigation, and animated page turns.
+
+## Properties
+
+```ts
+currentPage: number = 0          // attr: current-page
+mode: BookMode = 'spread'        // attr: mode — 'single' | 'spread'
+coverImage: string = ''          // attr: cover-image — URL for cover page image
+title: string = ''               // Book title shown on cover
+author: string = ''              // Author name shown on cover
+readonly totalPages: number      // Getter, count of slotted page elements
+```
+
+## Slots
+
+- `(default)` — Page elements; each child becomes one page
+
+## Events
+
+- `page-turn` -> `{ page: number, direction: 'forward' | 'backward' }`
+- `page-flip-start` -> `{ fromPage: number, toPage: number, direction: 'forward' | 'backward' }`
+- `page-flip-end` -> `{ page: number, direction: 'forward' | 'backward' }`
+
+## Methods
+
+- `goToPage(page: number): void` — Navigate to specific page (auto-aligns to spread in spread mode)
+- `nextPage(): void` — Advance by 1 (single) or 2 (spread) pages
+- `prevPage(): void` — Go back by 1 or 2 pages
+- `firstPage(): void` — Jump to page 0
+- `lastPage(): void` — Jump to last page
+
+## CSS Custom Properties
+
+```css
+--book-bg           /* Page background */
+--book-text          /* Text color */
+--book-text-secondary /* Secondary text */
+--book-border        /* Border color */
+--book-primary       /* Primary accent */
+--book-shadow        /* Book shadow */
+--book-page-bg       /* Individual page background */
+--book-page-line     /* Ruled line color */
+--book-spine-bg      /* Spine color */
+--book-cover-bg      /* Cover background */
+--book-flip-duration /* Flip animation duration, default 0.6s */
+```
+
+## CSS Parts
+
+- `spine` — The book spine element
+- `pages` — The pages container
+- `nav` — Navigation controls bar
+
+## Keyboard
+
+- ArrowRight/ArrowDown — Next page
+- ArrowLeft/ArrowUp — Previous page
+- Home — First page
+- End — Last page
+
+## Usage
+
+```html
+<snice-book title="My Book" author="Jane Doe" cover-image="/cover.jpg" mode="spread">
+  <div>Page 1 content</div>
+  <div>Page 2 content</div>
+  <div>Page 3 content</div>
+  <div>Page 4 content</div>
+</snice-book>
+```
+
+```js
+const book = document.querySelector('snice-book');
+book.goToPage(2);
+book.addEventListener('page-turn', e => console.log(e.detail.page));
+```

package/docs/ai/components/button.md

@@ -7,6 +7,7 @@ Interactive button with variants and states.
 ```typescript
 variant: 'default'|'primary'|'success'|'warning'|'danger'|'text' = 'default';
 size: 'small'|'medium'|'large' = 'medium';
+type: 'button'|'submit'|'reset' = 'button';
 disabled: boolean = false;
 loading: boolean = false;
 outline: boolean = false;
@@ -23,6 +24,10 @@ iconPlacement: 'start'|'end' = 'start';
 
 - `icon` - Custom icon content (overrides `icon` property)
 
+## Events
+
+- `button-click` → `{ originalEvent: MouseEvent }`
+
 ## Methods
 
 - `focus(options?)` - Focus button

package/docs/ai/components/chart.md

@@ -111,36 +111,12 @@ chart.datasets = [{
   backgroundColor: '#2196f3'
 }];
 
-// Radar chart
-chart.type = 'radar';
-chart.datasets = [
-  { label: 'Team A', data: [80, 90, 70, 85, 75], borderColor: '#2196f3' },
-  { label: 'Team B', data: [70, 85, 80, 75, 85], borderColor: '#4caf50' }
-];
-chart.labels = ['Speed', 'Strength', 'Agility', 'Defense', 'Skill'];
-
-// Mixed chart
-chart.type = 'mixed';
-chart.datasets = [
-  { label: 'Bar', type: 'bar', data: [10, 20, 30], backgroundColor: '#2196f3' },
-  { label: 'Line', type: 'line', data: [15, 25, 20], borderColor: '#4caf50' }
-];
-
 // Options
 chart.options = {
   legend: { position: 'bottom', clickable: true },
-  tooltip: {
-    trigger: 'hover',
-    format: (value, datasetIndex, pointIndex) => `Value: ${value}`
-  },
   animation: { enabled: true, duration: 1000 },
   yAxis: { min: 0, max: 100, ticks: 5, grid: true }
 };
-
-// Methods
-chart.addDataset({ label: 'New', data: [1, 2, 3] });
-chart.toggleDataset(0);
-const svg = chart.exportImage('svg');
 ```
 
 ```html

package/docs/ai/components/chat.md

@@ -47,49 +47,6 @@ Slack-style chat interface with messages, typing indicators, reactions, and file
 - `file` - File attachment
 - `system` - System notification
 
-## CSS Variables
-
-```css
---snice-chat-height
---snice-chat-border-radius
---snice-chat-text-color
---snice-chat-background
---snice-chat-border-color
---snice-chat-author-color
---snice-chat-timestamp-color
---snice-chat-system-color
---snice-chat-placeholder-color
---snice-chat-scrollbar-color
---snice-chat-scrollbar-hover-color
---snice-chat-avatar-background
---snice-chat-avatar-text-color
---snice-chat-attachment-border
---snice-chat-attachment-background
---snice-chat-attachment-icon-background
---snice-chat-attachment-icon-color
---snice-chat-reaction-background
---snice-chat-reaction-border
---snice-chat-reaction-hover-background
---snice-chat-reaction-active-background
---snice-chat-reaction-active-color
---snice-chat-reaction-active-border
---snice-chat-actions-background
---snice-chat-action-color
---snice-chat-action-hover-background
---snice-chat-typing-color
---snice-chat-typing-dot-color
---snice-chat-input-background
---snice-chat-input-container-background
---snice-chat-input-border
---snice-chat-input-focus-border
---snice-chat-button-color
---snice-chat-button-hover-background
---snice-chat-send-color
---snice-chat-send-background
---snice-chat-send-hover-background
---snice-chat-empty-color
-```
-
 ## Types
 
 ```typescript
@@ -123,67 +80,22 @@ interface MessageReaction {
 }
 ```
 
-## Example
+## Usage
 
 ```javascript
 const chat = document.querySelector('snice-chat');
 
 // Add message
 chat.addMessage({
-  type: 'text',
-  content: 'Hello!',
-  author: 'Alice',
-  avatar: 'https://example.com/alice.jpg',
-  timestamp: new Date(),
-  formats: [],
-});
-
-// Add image
-chat.addMessage({
-  type: 'image',
-  content: '',
-  author: 'Bob',
-  timestamp: new Date(),
-  formats: [],
-  attachment: {
-    type: 'image',
-    url: 'https://example.com/image.jpg',
-    name: 'photo.jpg',
-  },
+  type: 'text', content: 'Hello!', author: 'Alice', timestamp: new Date(), formats: [],
 });
 
-// Add reaction
-chat.addEventListener('message-react', (e) => {
-  const message = chat.messages.find((m) => m.id === e.detail.messageId);
-  const reactions = message.reactions || [];
-  reactions.push({ emoji: e.detail.emoji, count: 1, users: [chat.currentUser] });
-  chat.updateMessage(e.detail.messageId, { reactions });
+// Handle send
+chat.addEventListener('message-send', (e) => {
+  chat.addMessage({ type: 'text', content: e.detail.message, author: 'You', timestamp: new Date(), formats: [] });
 });
 
-// Typing indicator
+// Typing indicators
 chat.addTypingIndicator('Alice');
-setTimeout(() => chat.removeTypingIndicator('Alice'), 2000);
-
-// Send message
-chat.addEventListener('message-send', (e) => {
-  chat.addMessage({
-    type: 'text',
-    content: e.detail.message,
-    author: 'You',
-    timestamp: new Date(),
-    formats: [],
-  });
-});
+chat.removeTypingIndicator('Alice');
 ```
-
-## Features
-
-- Text, image, file, system messages
-- Edit, delete, react to messages
-- Typing indicators
-- User avatars with initials fallback
-- Timestamps
-- Auto-scroll to new messages
-- File upload support
-- Emoji reactions with counts
-- Message actions (edit, delete)

package/docs/ai/components/code-block.md

@@ -110,94 +110,15 @@ Load from `components/code-block/grammars/` (or `dist/components/code-block/gram
 - `bash.json` — Bash/Shell
 - `snice.json` — Snice (TypeScript + html``/css`` template highlighting)
 
-### Snice Grammar
-
-Extends TypeScript with awareness of snice's template DSL:
-- **`html\``** tagged templates → HTML mode with tag/attribute highlighting
-- **`css\``** tagged templates → CSS mode with property/selector highlighting
-- **`<if>`, `<case>`, `<when>`, `<default>`** → highlighted as keywords (not regular tags)
-- **`.prop=`** property bindings → "property" token
-- **`?attr=`** boolean bindings → "attr-name" token
-- **`@event=`** event bindings → "function" token (includes `@event:modifier` and `@event.modifier`)
-- **`${...}`** interpolations → back to TypeScript mode
-- Handles `html/*html*/\`` editor hint pattern
-
-### Loading Grammars
-
-```html
-<!-- Grammar from URL -->
-<snice-code-block grammar="grammars/typescript.json" language="typescript" id="cb"></snice-code-block>
-<script>
-  document.getElementById('cb').code = 'const x: number = 42;';
-</script>
-
-<!-- Inline grammar object -->
-<snice-code-block id="cb2" language="custom"></snice-code-block>
-<script>
-  document.getElementById('cb2').grammar = {
-    name: 'custom',
-    keywords: ['func', 'var', 'return'],
-    tokenizer: {
-      root: [
-        ['//.*$', 'comment'],
-        ['"[^"]*"', 'string'],
-        ['\\b\\d+\\b', 'number'],
-        ['[a-zA-Z_]\\w*', { cases: { '@keywords': 'keyword', '@default': '' } }]
-      ]
-    }
-  };
-  document.getElementById('cb2').code = 'func main() { return 42; }';
-</script>
-```
-
-### Programmatic Registration
-
-```typescript
-import { registerGrammar, unregisterGrammar, getGrammar } from 'snice/components/code-block/highlighter';
-
-// Register so language string lookup works
-const grammar = await fetch('grammars/typescript.json').then(r => r.json());
-registerGrammar('typescript', grammar);
-registerGrammar('ts', grammar);  // alias
-
-// Then use by name
-highlightCode(code, 'typescript');
-```
-
-### Grammar Format
-
-```typescript
-interface Grammar {
-  name: string;
-  fileTypes?: string[];
-  defaultToken?: string;
-  ignoreCase?: boolean;
-  tokenizer: Record<string, GrammarEntry[]>;
-  [key: string]: any;  // Lookup tables (keywords, builtins, etc.)
-}
-
-// Rule: [regex, token] | [regex, token, nextState] | { include: '@state' }
-// Token: string | { cases: { '@table': 'token', '@default': 'token' } }
-// State: '@stateName' (push) | '@pop' (return)
-```
-
-### Highlighter API (programmatic)
+### Highlighter API
 
 ```typescript
 import { highlightCode, tokenize, registerGrammar, unregisterGrammar, getGrammar } from 'snice/components/code-block/highlighter';
 
-highlightCode(code, grammarObject);      // Use grammar directly → HTML string
-highlightCode(code, 'myLang');           // Use registered grammar (or plaintext if not found)
-tokenize(code, grammarObject);           // Returns Token[]
-registerGrammar('myLang', grammar);      // Register grammar for name lookup
-unregisterGrammar('myLang');             // Remove registered grammar
-getGrammar('myLang');                    // Get registered grammar or undefined
+highlightCode(code, grammarOrName);  // → HTML string
+registerGrammar('myLang', grammar);  // Register for name lookup
 ```
 
-## Token CSS Classes
-
-`keyword`, `string`, `comment`, `tag`, `function`, `class-name`, `number`, `constant`, `attr-name`, `attr-value`, `property`, `operator`, `punctuation`, `builtin`, `regex`
-
 ## Usage
 
 ```html

package/docs/ai/components/color-display.md

@@ -7,9 +7,9 @@ Displays colors with swatch and label.
 ```typescript
 value: string = '';
 format: 'hex'|'rgb'|'hsl' = 'hex';
-showSwatch: boolean = true;
-showLabel: boolean = true;
-swatchSize: 'small'|'medium'|'large' = 'medium';
+showSwatch: boolean = true;      // attribute: show-swatch
+showLabel: boolean = true;       // attribute: show-label
+swatchSize: 'small'|'medium'|'large' = 'medium'; // attribute: swatch-size
 label: string = '';
 ```
 

package/docs/ai/components/color-picker.md

@@ -9,14 +9,14 @@ value: string = '#000000';
 format: 'hex'|'rgb'|'hsl' = 'hex';
 size: 'small'|'medium'|'large' = 'medium';
 label: string = '';
-helperText: string = '';
-errorText: string = '';
+helperText: string = '';       // attribute: helper-text
+errorText: string = '';        // attribute: error-text
 disabled: boolean = false;
 required: boolean = false;
 invalid: boolean = false;
 name: string = '';
-showInput: boolean = true;
-showPresets: boolean = false;
+showInput: boolean = true;     // attribute: show-input
+showPresets: boolean = false;  // attribute: show-presets
 presets: string[] = [...];
 loading: boolean = false;
 ```