snice 4.28.0 → 4.30.0

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

@@ -1,224 +1,103 @@
 # snice-code-block
 
-Code display with syntax highlighting, line numbers, copy.
-
-## Code Content
-
-Code can be provided via **slotted text content** (preferred) or the `code` property:
-
-```html
-<!-- Slotted (preferred) -->
-<snice-code-block language="javascript">
-const x = 1;
-</snice-code-block>
-
-<!-- Property (programmatic) -->
-<snice-code-block id="cb"></snice-code-block>
-```
-
-```typescript
-cb.code = 'const x = 1;';
-```
-
-Slotted content is hidden and re-rendered with highlighting in the shadow DOM. If both are provided, slotted content sets the `code` property on ready.
+Code display with syntax highlighting, line numbers, copy, and grammar-based formatting.
 
 ## Properties
 
 ```typescript
-code: string = '';              // Set via slot or property (not recommended as attribute)
+code: string = '';                // Set via slot or property
 language: 'javascript'|'typescript'|'html'|'css'|'json'|'python'|'bash'|'plaintext' = 'plaintext';
 grammar: GrammarDefinition | string | null = null;  // Grammar object or URL to JSON
-showLineNumbers: boolean = false;
-startLine: number = 1;
-highlightLines: number[] = [];
+showLineNumbers: boolean = false;  // attribute: show-line-numbers
+startLine: number = 1;            // attribute: start-line
+highlightLines: number[] = [];    // attribute: highlight-lines
 copyable: boolean = true;
 filename: string = '';
-format: string = '';             // Formatter name from grammar (e.g. "pretty"), or any truthy string with setFormatter()
-theme: '' | 'dark' | 'light' = '';  // Force theme; empty = auto-detect from page/OS
+format: string = '';              // Formatter name (e.g. "pretty"), or truthy string with setFormatter()
+theme: '' | 'dark' | 'light' = '';  // Force theme; empty = auto-detect
+fetchMode: 'native' | 'virtual' | 'event' = 'native';  // attribute: fetch-mode
 ```
 
-## Fetch Mode
-
-```typescript
-fetchMode: 'native' | 'virtual' | 'event' = 'native'  // attribute: fetch-mode
-```
-
-Controls how grammar JSON is loaded when `grammar` is a URL string.
+## Methods
 
-- **`native`** (default) — `fetch(url).then(r => r.json())`. No external wiring needed.
-- **`virtual`** — Uses `@request/@respond` pattern (`snice/code-block/load-grammar`). Requires a `@respond` handler.
-- **`event`** — Dispatches `grammar-request` CustomEvent with `{ url, language, codeBlock }` detail. Listener calls `codeBlock.setGrammar()` to provide grammar.
+- `copy()` - Copy code to clipboard
+- `highlight()` - Trigger syntax highlighting
+- `setHighlighter(fn)` - Set external highlighter
+- `setFormatter(fn)` - Set formatter function
+- `setGrammar(grammar)` - Set grammar object programmatically
 
-**Note:** If using `@respond('snice/code-block/load-grammar')`, add `fetch-mode="virtual"`. Default is `native`.
+## Events
 
-### Native (default)
+- `code-copy` -> `{ code, codeBlock }`
+- `code-before-format` / `code-after-format` -> `{ code, language, codeBlock }`
+- `code-before-highlight` / `code-after-highlight` -> `{ code, language, codeBlock }`
+- `grammar-request` -> `{ url, language, codeBlock }` (only fetch-mode="event")
+- `grammar-loaded` -> `{ grammar, url, language, codeBlock }`
 
-```html
-<snice-code-block grammar="grammars/typescript.json" code="const x = 1"></snice-code-block>
-```
+## Slots
 
-### Virtual
+- `(default)` - Code content as slotted text (auto-dedented)
 
-```html
-<snice-code-block grammar="grammars/typescript.json" fetch-mode="virtual" code="const x = 1"></snice-code-block>
-```
+## CSS Parts
 
-Requires `@respond('snice/code-block/load-grammar')` handler (controller or page).
+- `container` - Outer wrapper
+- `header` - Header bar (filename + copy button)
+- `filename` - Filename display
+- `copy-button` - Copy button
+- `content` - Scrollable code area
+- `pre` - Pre-formatted container
+- `code` - Code element with tokens
 
-### Event
+## Basic Usage
 
 ```html
-<snice-code-block grammar="grammars/typescript.json" fetch-mode="event" code="const x = 1"></snice-code-block>
-```
-
-```typescript
-cb.addEventListener('grammar-request', async (e) => {
-  const grammar = await fetch(e.detail.url).then(r => r.json());
-  e.detail.codeBlock.setGrammar(grammar);
-});
+<snice-code-block language="javascript" grammar="grammars/typescript.json">
+const x = 1;
+</snice-code-block>
 ```
 
-Event detail type:
 ```typescript
-interface GrammarRequestDetail {
-  url: string;
-  language: CodeLanguage;
-  codeBlock: SniceCodeBlockElement;
-}
+import 'snice/components/code-block/snice-code-block';
+cb.code = 'const x = 1;';
 ```
 
-## Methods
-
-- `copy()` - Copy code to clipboard
-- `highlight()` - Manually trigger syntax highlighting
-- `setHighlighter(fn)` - Set external highlighter for this instance
-- `setFormatter(fn)` - Set formatter function for this instance
-- `setGrammar(grammar)` - Provide grammar object directly (used with `fetch-mode="event"`)
-
-## Events
+## Fetch Mode
 
-- `code-copy` (detail: { code, codeBlock })
-- `code-before-format` (detail: { code, language, codeBlock })
-- `code-after-format` (detail: { code, language, codeBlock })
-- `code-before-highlight` (detail: { code, language, codeBlock })
-- `code-after-highlight` (detail: { code, language, codeBlock })
-- `grammar-request` (detail: { url, language, codeBlock }) — only dispatched when `fetch-mode="event"`
-- `grammar-loaded` (detail: { grammar, url, language, codeBlock }) — fired after grammar is successfully loaded (any fetch mode) or set via `setGrammar()`
+- `native` (default) - fetch(url)
+- `virtual` - @request/@respond pattern
+- `event` - Dispatches `grammar-request`, listener calls `setGrammar()`
 
 ## Formatters
 
-Code formatters run as a pre-step before highlighting. Set `format` to a formatter name.
-
-### Grammar-Based Formatters (Declarative)
+Grammar-based: `format="pretty"` (grammars: json, typescript, css, snice)
 
-Grammars can include a `formatters` section with named rule sets. Use `format="name"` to select one:
-
-```html
-<snice-code-block grammar="grammars/json.json" format="pretty" code='{"a":1}'></snice-code-block>
-```
-
-Grammars with `"pretty"` formatters: `json.json`, `typescript.json`, `css.json`, `snice.json`.
-
-```typescript
-interface FormatRules {
-  tabSize?: number;          // Indent width (default 2)
-  useTabs?: boolean;         // Tabs instead of spaces
-  newlineAfter?: string;     // Regex char class — newline after these chars
-  newlineBefore?: string;    // Regex char class — newline before these chars
-  spaceAfter?: string;       // Regex char class — space after
-  spaceBefore?: string;      // Regex char class — space before
-  spaceAround?: string;      // Regex char class — space both sides
-  indent?: string;           // Regex char class — increase indent
-  dedent?: string;           // Regex char class — decrease indent
-  trimTrailing?: boolean;    // Trim trailing whitespace (default true)
-  collapseBlankLines?: number; // Max consecutive blank lines
-  skipStrings?: boolean;     // Skip rules inside strings (default true)
-  skipComments?: boolean;    // Skip rules inside comments (default true)
-}
-```
-
-### Imperative Formatters
-
-`setFormatter(fn)` overrides grammar-based formatters when both are present.
+Imperative: `setFormatter(fn)` overrides grammar formatters
 
-```typescript
-type FormatterFunction = (code: string, language: string) => string | Promise<string>;
-```
-
-**`formatters/json.ts`** — JSON pretty-printer (zero-dependency):
 ```typescript
 import { createJsonFormatter } from 'snice/components/code-block/formatters/json';
 codeBlock.setFormatter(createJsonFormatter({ indent: 2 }));
 codeBlock.format = 'pretty';
 ```
 
-**`formatters/indent.ts`** — Indent normalizer (zero-dependency):
-```typescript
-import { createIndentFormatter } from 'snice/components/code-block/formatters/indent';
-codeBlock.setFormatter(createIndentFormatter({ tabSize: 2, useTabs: false }));
-codeBlock.format = 'pretty';
-```
-
-**`formatters/prettier.ts`** — Prettier adapter:
-```typescript
-import { setupPrettierFormatter } from 'snice/components/code-block/formatters/prettier';
-import * as prettier from 'prettier/standalone';
-import parserBabel from 'prettier/plugins/babel';
-codeBlock.setFormatter(setupPrettierFormatter(prettier, [parserBabel]));
-codeBlock.format = 'pretty';
-```
+## Grammar Files
 
-### Whitespace Handling
-
-Slotted content is automatically dedented — common leading indentation from HTML nesting is stripped while preserving relative indentation.
+- `typescript.json` - TypeScript/JavaScript
+- `html.json` - HTML/XML
+- `css.json` - CSS/SCSS/Less
+- `json.json` - JSON
+- `python.json` - Python
+- `bash.json` - Bash/Shell
+- `snice.json` - Snice (TS + template highlighting)
 
 ## Theming
 
-Auto-follows `data-theme` attribute on page or OS `prefers-color-scheme`. Dark (One Dark) and light (One Light) built-in.
-
-- No attribute / `theme=""` → auto-detect from `[data-theme]` or OS preference
-- `theme="dark"` → force One Dark regardless of page theme
-- `theme="light"` → force One Light regardless of page theme
-
-Override individual colors: `--code-keyword-color`, `--code-function-color`, etc.
-Override structural colors: `--code-block-bg`, `--code-block-text`, `--code-block-header-bg`.
-
-## Grammar System
-
-JSON-driven tokenizer with Monarch-inspired state machine. Grammars are **external JSON files**, not bundled in the component.
-
-### Available Grammar Files
-
-Load from `components/code-block/grammars/` (or `dist/components/code-block/grammars/` in builds):
-- `typescript.json` — TypeScript/JavaScript
-- `html.json` — HTML/XML
-- `css.json` — CSS/SCSS/Less
-- `json.json` — JSON
-- `python.json` — Python
-- `bash.json` — Bash/Shell
-- `snice.json` — Snice (TypeScript + html``/css`` template highlighting)
-
-### Highlighter API
-
-```typescript
-import { highlightCode, tokenize, registerGrammar, unregisterGrammar, getGrammar } from 'snice/components/code-block/highlighter';
-
-highlightCode(code, grammarOrName);  // → HTML string
-registerGrammar('myLang', grammar);  // Register for name lookup
-```
+Auto-follows `data-theme` or OS `prefers-color-scheme`. Force with `theme="dark"|"light"`.
 
-## Usage
+Token colors: `--code-keyword-color`, `--code-function-color`, `--code-string-color`, etc.
+Structural: `--code-block-bg`, `--code-block-text`, `--code-block-header-bg`.
 
-```html
-<!-- Slotted content (preferred) -->
-<snice-code-block language="javascript" grammar="grammars/typescript.json" show-line-numbers filename="app.js">
-console.log('hello');
-</snice-code-block>
+## Accessibility
 
-<!-- Programmatic -->
-<snice-code-block language="javascript" grammar="grammars/typescript.json" show-line-numbers filename="app.js"></snice-code-block>
-```
-
-```typescript
-codeBlock.code = `console.log('hello');`;
-```
+- Auto theme detection (light/dark)
+- Semantic pre/code elements
+- Copy button

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

@@ -7,48 +7,28 @@ Displays colors with swatch and label.
 ```typescript
 value: string = '';
 format: 'hex'|'rgb'|'hsl' = 'hex';
-showSwatch: boolean = true;      // attribute: show-swatch
-showLabel: boolean = true;       // attribute: show-label
+showSwatch: boolean = true;       // attribute: show-swatch
+showLabel: boolean = true;        // attribute: show-label
 swatchSize: 'small'|'medium'|'large' = 'medium'; // attribute: swatch-size
 label: string = '';
 ```
 
-## Usage
+## CSS Parts
+
+- `container` - Outer container
+- `swatch` - Color swatch element
+- `label` - Color label text
+
+## Basic Usage
 
 ```html
-<!-- Basic -->
 <snice-color-display value="#3b82f6"></snice-color-display>
-
-<!-- Formats -->
-<snice-color-display value="#ff0000" format="hex"></snice-color-display>
 <snice-color-display value="#ff0000" format="rgb"></snice-color-display>
-<snice-color-display value="#ff0000" format="hsl"></snice-color-display>
-
-<!-- Sizes -->
-<snice-color-display value="#10b981" swatch-size="small"></snice-color-display>
-<snice-color-display value="#10b981" swatch-size="medium"></snice-color-display>
 <snice-color-display value="#10b981" swatch-size="large"></snice-color-display>
-
-<!-- Custom label -->
 <snice-color-display value="#ef4444" label="Error Red"></snice-color-display>
-
-<!-- Swatch only -->
 <snice-color-display value="#3b82f6" show-label="false"></snice-color-display>
-
-<!-- Label only -->
-<snice-color-display value="#3b82f6" show-swatch="false"></snice-color-display>
 ```
 
-## CSS Parts
-
-- `container` - Outer container
-- `swatch` - Color swatch element
-- `label` - Color label text
-
-## Features
-
-- Auto-converts hex to RGB/HSL
-- 3 swatch sizes (16px, 24px, 32px)
-- Custom labels supported
-- Swatch and label toggle
-- Monospace font for color values
+```typescript
+import 'snice/components/color-display/snice-color-display';
+```

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

@@ -1,13 +1,13 @@
 # snice-color-picker
 
-Color picker with format conversion and presets.
+Color picker with format conversion, presets, and form integration.
 
 ## Properties
 
 ```typescript
+size: 'small'|'medium'|'large' = 'medium';
 value: string = '#000000';
 format: 'hex'|'rgb'|'hsl' = 'hex';
-size: 'small'|'medium'|'large' = 'medium';
 label: string = '';
 helperText: string = '';       // attribute: helper-text
 errorText: string = '';        // attribute: error-text
@@ -23,8 +23,15 @@ loading: boolean = false;
 
 ## Methods
 
-- `focus()` - Focus picker
-- `blur()` - Blur picker
+- `focus()` - Focus picker input
+- `blur()` - Remove focus
+
+## Events
+
+- `color-picker-input` -> `{ value, colorPicker }` - During color adjustment
+- `color-picker-change` -> `{ value, colorPicker }` - Color committed
+- `color-picker-focus` -> `{ colorPicker }` - Input focused
+- `color-picker-blur` -> `{ colorPicker }` - Input blurred
 
 ## CSS Parts
 
@@ -32,51 +39,22 @@ loading: boolean = false;
 - `error-text` - Error text element
 - `helper-text` - Helper text element
 
-## Events
-
-- `color-picker-input` → `{ value, colorPicker }`
-- `color-picker-change` → `{ value, colorPicker }`
-- `color-picker-focus` → `{ colorPicker }`
-- `color-picker-blur` → `{ colorPicker }`
-
-## Usage
+## Basic Usage
 
 ```html
-<!-- Basic -->
 <snice-color-picker label="Color" value="#ff0000"></snice-color-picker>
-
-<!-- Formats -->
-<snice-color-picker format="hex"></snice-color-picker>
-<snice-color-picker format="rgb"></snice-color-picker>
-<snice-color-picker format="hsl"></snice-color-picker>
-
-<!-- With presets -->
-<snice-color-picker show-presets></snice-color-picker>
-
-<!-- No input -->
-<snice-color-picker show-input="false"></snice-color-picker>
-
-<!-- Sizes -->
-<snice-color-picker size="small"></snice-color-picker>
-<snice-color-picker size="medium"></snice-color-picker>
-<snice-color-picker size="large"></snice-color-picker>
-
-<!-- Events -->
-<snice-color-picker></snice-color-picker>
 ```
 
 ```typescript
+import 'snice/components/color-picker/snice-color-picker';
+
 picker.addEventListener('color-picker-change', (e) => {
   console.log('Color:', e.detail.value);
 });
 ```
 
-## Features
+## Accessibility
 
 - Form-associated custom element
-- Native color picker integration
-- 3 color formats (hex, rgb, hsl)
-- Format conversion
-- Color presets
-- 3 sizes
-- Accessible
+- Label association, error/helper text announced
+- Keyboard accessible

package/docs/ai/components/command-palette.md

@@ -1,6 +1,6 @@
 # snice-command-palette
 
-Searchable command palette overlay (⌘K) for quick command access.
+Searchable command palette overlay (Cmd+K / Ctrl+K) for quick command access.
 
 ## Properties
 
@@ -8,14 +8,14 @@ Searchable command palette overlay (⌘K) for quick command access.
 open: boolean = false;
 commands: CommandItem[] = [];
 placeholder: string = 'Type a command or search...';
-noResultsText: string = 'No results found';
-maxResults: number = 50;
-showRecentCommands: boolean = true;
-recentCommandsLimit: number = 5;
-caseSensitive: boolean = false;
+noResultsText: string = 'No results found';    // attribute: no-results-text
+maxResults: number = 50;                        // attribute: max-results
+showRecentCommands: boolean = true;             // attribute: show-recent-commands
+recentCommandsLimit: number = 5;               // attribute: recent-commands-limit
+caseSensitive: boolean = false;                // attribute: case-sensitive
 ```
 
-## CommandItem Interface
+### CommandItem Interface
 
 ```typescript
 interface CommandItem {
@@ -38,71 +38,18 @@ interface CommandItem {
 - `close()` - Close palette
 - `toggle()` - Toggle visibility
 - `addCommand(command: CommandItem)` - Add command
-- `removeCommand(id: string)` - Remove command
-- `executeCommand(id: string)` - Execute by ID
-- `clearSearch()` - Clear search
-- `focus()` - Focus input
+- `removeCommand(id: string)` - Remove command by ID
+- `executeCommand(id: string)` - Execute command by ID
+- `clearSearch()` - Clear search input
+- `focus()` - Focus search input
 
 ## Events
 
-- `command-palette-open` - Opened (detail: { palette })
-- `command-palette-close` - Closed (detail: { palette })
-- `command-select` - Command selected (detail: { command, palette })
-- `command-execute` - Command executed (detail: { command, palette })
-- `command-search` - Search changed (detail: { query, results, palette })
-
-## Usage
-
-```html
-<!-- Basic -->
-<snice-command-palette></snice-command-palette>
-```
-
-```typescript
-palette.commands = [
-  {
-    id: 'new',
-    label: 'New File',
-    description: 'Create a new file',
-    icon: '📄',
-    shortcut: '⌘N',
-    category: 'File',
-    action: () => console.log('New file')
-  },
-  {
-    id: 'save',
-    label: 'Save',
-    icon: '💾',
-    shortcut: '⌘S',
-    category: 'File',
-    action: () => console.log('Saved')
-  }
-];
-```
-
-Opens with Cmd+K or Ctrl+K.
-
-```html
-<!-- Manual trigger -->
-<button onclick="palette.show()">Open</button>
-```
-
-```typescript
-// With async actions
-palette.commands = [{
-  id: 'logout',
-  label: 'Logout',
-  action: async () => {
-    await fetch('/api/logout', { method: 'POST' });
-    location.href = '/login';
-  }
-}];
-
-// Events
-palette.addEventListener('command-execute', (e) => {
-  console.log('Executed:', e.detail.command.label);
-});
-```
+- `command-palette-open` -> `{ palette }` - Palette opened
+- `command-palette-close` -> `{ palette }` - Palette closed
+- `command-select` -> `{ command, palette }` - Command highlighted
+- `command-execute` -> `{ command, palette }` - Command executed
+- `command-search` -> `{ query, results, palette }` - Search changed
 
 ## CSS Parts
 
@@ -111,11 +58,42 @@ palette.addEventListener('command-execute', (e) => {
 - `input` - Search input element
 - `results` - Results list container
 - `empty` - Empty state message
-- `category` - Category header
+- `category` - Category group header
 - `item` - Command item button
 - `item-icon` - Item icon wrapper
 - `item-icon-image` - Item icon image
 - `item-content` - Item label + description wrapper
 - `item-label` - Item label text
 - `item-description` - Item description text
-- `item-shortcut` - Item keyboard shortcut badge
+- `item-shortcut` - Keyboard shortcut badge
+
+## Basic Usage
+
+```html
+<snice-command-palette id="palette"></snice-command-palette>
+```
+
+```typescript
+import 'snice/components/command-palette/snice-command-palette';
+
+palette.commands = [
+  { id: 'new', label: 'New File', icon: '📄', shortcut: '⌘N', category: 'File', action: () => {} },
+  { id: 'save', label: 'Save', icon: '💾', shortcut: '⌘S', category: 'File', action: () => {} }
+];
+
+palette.addEventListener('command-execute', (e) => console.log(e.detail.command.label));
+```
+
+## Keyboard Navigation
+
+- `Cmd+K` / `Ctrl+K` - Toggle palette
+- `Escape` - Close palette
+- `Arrow Up` / `Arrow Down` - Navigate commands
+- `Enter` - Execute active command
+
+## Accessibility
+
+- Full keyboard navigation
+- ARIA labels and roles
+- Focus trap when open
+- Screen reader announcements