snice 4.9.0 → 4.10.0

package/docs/ai/components/tabs.md

@@ -1,59 +1,44 @@
 # snice-tabs
 
-Tabbed interface with container, tab buttons, and content panels.
+Tabbed interface with tab buttons and content panels.
 
-## Components
-
-### snice-tabs (Container)
+## snice-tabs (Container)
 
 ```typescript
-selected: number = 0;                              // Active tab index
-placement: 'top'|'bottom'|'start'|'end' = 'top';  // Tab navigation position
-noScrollControls: boolean = false;                 // Hide scroll buttons
-transition: string = 'none';                       // Panel transition effect
+selected: number = 0;
+placement: 'top'|'bottom'|'start'|'end' = 'top';
+noScrollControls: boolean = false;  // attr: no-scroll-controls
+transition: string = 'none';
 ```
 
-**Methods:**
-```typescript
-selectTab(index: number)           // Select tab by index
-show(index: number)                 // Alias for selectTab
-getTab(index: number)               // Get tab element
-getPanel(index: number)             // Get panel element
-```
+## snice-tab (Tab Button)
 
-**Events:**
 ```typescript
-'tab-change' // { index, oldIndex, tab, panel }
+disabled: boolean = false;
+closable: boolean = false;
 ```
 
-### snice-tab (Tab Button)
+## snice-tab-panel (Content Panel)
 
 ```typescript
-disabled: boolean = false;   // Disabled state
-closable: boolean = false;   // Show close button
+name: string = '';
+transitionIn: string = '';        // attr: transition-in
+transitionOut: string = '';       // attr: transition-out
+transitionDuration: number = 300; // attr: transition-duration
 ```
 
-**Methods:**
-```typescript
-focus()   // Focus the tab
-blur()    // Remove focus
-```
+## Events
 
-**Events:**
-```typescript
-'tab-select' // { tab }
-'tab-close'      // { tab }
-```
+- `tab-change` → `{ index, oldIndex, tab, panel }` - Tab switched
+- `tab-select` → `{ tab }` - Tab clicked
+- `tab-close` → `{ tab }` - Close button clicked
 
-### snice-tab-panel (Content Panel)
+## Methods
 
-```typescript
-name: string = '';                         // Panel identifier
-transitionIn: string = '';                 // Transition when showing
-transitionOut: string = '';                // Transition when hiding
-transitioning: 'in'|'out'|'' = '';        // Transition state
-transitionDuration: number = 300;          // Transition duration (ms)
-```
+- `selectTab(index)` - Select tab by index
+- `show(index)` - Alias for selectTab
+- `getTab(index)` - Get tab element
+- `getPanel(index)` - Get panel element
 
 ## Usage
 
@@ -61,23 +46,17 @@ transitionDuration: number = 300;          // Transition duration (ms)
 <snice-tabs>
   <snice-tab slot="nav">Tab 1</snice-tab>
   <snice-tab slot="nav">Tab 2</snice-tab>
-
   <snice-tab-panel>Content 1</snice-tab-panel>
   <snice-tab-panel>Content 2</snice-tab-panel>
 </snice-tabs>
-```
 
-```typescript
-tabs.addEventListener('tab-change', (e) => {
-  console.log(e.detail.index);
-});
+<!-- Placement -->
+<snice-tabs placement="bottom">...</snice-tabs>
+<snice-tabs placement="start">...</snice-tabs>
 
-tabs.selectTab(1);
-```
-
-## Notes
+<!-- Closable -->
+<snice-tab slot="nav" closable>Closable Tab</snice-tab>
 
-- Tabs use `slot="nav"` attribute
-- Panels in default slot
-- Automatically manages ARIA attributes
-- Supports keyboard navigation
+<!-- Disabled -->
+<snice-tab slot="nav" disabled>Disabled Tab</snice-tab>
+```

package/docs/ai/components/tag-input.md

@@ -0,0 +1,70 @@
+# snice-tag-input
+
+Tag/chip input with autocomplete suggestions, keyboard navigation, and comma-separated entry.
+
+## Properties
+
+```ts
+value: string[] = []
+suggestions: string[] = []
+maxTags: number = 0              // 0 = unlimited (attribute: max-tags)
+allowDuplicates: boolean = false // attribute: allow-duplicates
+placeholder: string = 'Add a tag...'
+disabled: boolean = false
+readonly: boolean = false
+label: string = ''
+name: string = ''
+```
+
+## Methods
+
+- `addTag(tag: string)` - Add a tag programmatically
+- `removeTag(index: number)` - Remove tag at index
+- `clear()` - Remove all tags
+- `focus()` - Focus the input field
+
+## Events
+
+- `tag-add` -> `{ tag: string; value: string[] }`
+- `tag-remove` -> `{ tag: string; index: number; value: string[] }`
+- `tag-change` -> `{ value: string[] }`
+
+## Input Behavior
+
+- Enter: Add current input as tag (or select highlighted suggestion)
+- Comma: Split input and add each part as a tag
+- Backspace on empty input: Remove last tag
+- ArrowUp/ArrowDown: Navigate suggestions
+- Escape: Close suggestions dropdown
+
+## CSS Custom Properties
+
+- `--snice-color-border` - Container border (default: `rgb(226 226 226)`)
+- `--snice-color-primary` - Focus ring, tag color (default: `rgb(37 99 235)`)
+- `--snice-color-primary-subtle` - Tag background (default: `rgb(239 246 255)`)
+- `--snice-color-background` - Input background (default: `rgb(255 255 255)`)
+- `--snice-color-text` - Text color (default: `rgb(23 23 23)`)
+- `--snice-color-text-tertiary` - Placeholder color
+- `--snice-focus-ring-width` - Focus ring width (default: `2px`)
+- `--snice-focus-ring-color` - Focus ring color
+- `--snice-shadow-lg` - Suggestions dropdown shadow
+
+## Usage
+
+```html
+<snice-tag-input
+  label="Skills"
+  placeholder="Add a skill..."
+  max-tags="5"
+></snice-tag-input>
+```
+
+```js
+const tagInput = document.querySelector('snice-tag-input');
+tagInput.suggestions = ['JavaScript', 'TypeScript', 'Python', 'Rust', 'Go'];
+tagInput.value = ['JavaScript'];
+
+tagInput.addEventListener('tag-change', (e) => {
+  console.log('Tags:', e.detail.value);
+});
+```

package/docs/ai/components/terminal.md

@@ -1,147 +1,65 @@
 # snice-terminal
 
-Shell terminal emulator with command execution, history, ANSI colors, and keyboard navigation.
-
-## Usage
-
-```html
-<snice-terminal prompt="$ " cwd="~"></snice-terminal>
-```
+Shell terminal emulator with command execution, history, and ANSI colors.
 
 ## Properties
 
-- `prompt: string` - Terminal prompt (default: `"$ "`)
-- `cwd: string` - Current working directory (default: `"~"`)
-- `readonly: boolean` - Disable input (default: `false`)
-- `maxLines: number` - Max lines in history (default: `1000`)
-- `showTimestamps: boolean` - Show line timestamps (default: `false`)
-
-## Methods
-
-- `write(content: string, type?: TerminalLineType): void` - Write without newline
-- `writeln(content: string, type?: TerminalLineType): void` - Write with newline
-- `writeLines(lines: Array<{ content: string; type?: TerminalLineType }>): void` - Write multiple lines
-- `writeError(content: string): void` - Write error line
-- `clear(): void` - Clear terminal
-- `focus(): void` - Focus input
-- `getHistory(): string[]` - Get command history
-- `clearHistory(): void` - Clear command history
-
-## Events
-
-- `@snice/terminal-command: CustomEvent<{ command: string; args: string[] }>` - Command entered
-- `@snice/terminal-clear: CustomEvent<{}>` - Terminal cleared
-- `@snice/terminal-ready: CustomEvent<{}>` - Terminal ready
-
-## Request/Response Pattern
-
-Terminal uses `@request('terminal-command')` decorator pattern:
-
 ```typescript
-// Terminal component makes request
-@request('terminal-command')
-async *executeCommand(commandLine: string): any {
-  const response = await (yield payload);
-  return response;
-}
-
-// Controller responds
-@respond('terminal-command')
-async handleCommand(payload: TerminalCommandRequest) {
-  const { command, args, cwd } = payload;
-  // Execute command
-  return { output: 'result', exitCode: 0 };
-}
+prompt: string = '$ ';
+cwd: string = '~';
+readonly: boolean = false;
+maxLines: number = 1000;       // attr: max-lines
+showTimestamps: boolean = false; // attr: show-timestamps
 ```
 
-## Line Types
-
-- `input` - User input
-- `output` - Command output
-- `error` - Error message
-- `info` - Info message
-- `success` - Success message
-- `warning` - Warning message
+## Events
 
-## Keyboard Shortcuts
+- `terminal-command` → `{ command, args }` - Command entered
+- `terminal-clear` → `{}` - Terminal cleared
+- `terminal-ready` → `{}` - Terminal ready
 
-- `Enter` - Execute command
-- `↑/↓` - Navigate history
-- `Ctrl+C` - Cancel input
-- `Ctrl+L` - Clear terminal
-- `Tab` - Command completion (TODO)
+## Methods
 
-## ANSI Color Support
+- `write(content, type?)` - Write without newline
+- `writeln(content, type?)` - Write with newline
+- `writeLines(lines)` - Write multiple lines
+- `writeError(content)` - Write error line
+- `clear()` - Clear terminal
+- `focus()` - Focus input
+- `getHistory()` - Get command history
+- `clearHistory()` - Clear command history
 
-Supports ANSI escape codes for colors:
-- `30-37` - Standard colors
-- `90-97` - Bright colors
+## Line Types
 
-Special output `\x1B[CLEAR]` clears terminal.
+`input` | `output` | `error` | `info` | `success` | `warning`
 
-## CSS Variables
+## CSS Custom Properties
 
 ```css
 --snice-terminal-background
 --snice-terminal-foreground
 --snice-terminal-border
---snice-terminal-scrollbar
---snice-terminal-scrollbar-thumb
+--snice-terminal-prompt-color
 --snice-terminal-input-color
 --snice-terminal-output-color
 --snice-terminal-error-color
 --snice-terminal-info-color
 --snice-terminal-success-color
 --snice-terminal-warning-color
---snice-terminal-prompt-color
---snice-terminal-selection
-```
-
-## Types
-
-```typescript
-type TerminalLineType = 'input' | 'output' | 'error' | 'info' | 'success' | 'warning';
-
-interface TerminalCommandRequest {
-  command: string;
-  args: string[];
-  cwd?: string;
-  history?: string[];
-}
-
-interface TerminalCommandResponse {
-  output?: string;
-  error?: string;
-  exitCode?: number;
-}
 ```
 
-## Example
-
-```javascript
-const terminal = document.querySelector('snice-terminal');
+## Usage
 
-// Listen for commands (event pattern)
-terminal.addEventListener('terminal-command', (e) => {
-  console.log('Command:', e.detail.command, e.detail.args);
-});
+```html
+<snice-terminal prompt="$ " cwd="~"></snice-terminal>
 
-// Handle commands (@respond pattern)
-class TerminalController extends HTMLElement {
-  @respond('terminal-command')
-  async handleCommand(req) {
-    if (req.command === 'echo') {
-      return { output: req.args.join(' '), exitCode: 0 };
-    }
-    if (req.command === 'clear') {
-      return { output: '\x1B[CLEAR]' };
-    }
-    return { error: `Command not found: ${req.command}`, exitCode: 127 };
-  }
-}
+<script>
+  const terminal = document.querySelector('snice-terminal');
+  terminal.writeln('Welcome!', 'info');
+  terminal.writeError('Something failed');
 
-// Write to terminal
-terminal.writeln('Welcome to the terminal!', 'info');
-terminal.writeln('\x1b[32mGreen text\x1b[0m', 'output');
-terminal.writeError('Error: Something went wrong');
+  terminal.addEventListener('terminal-command', (e) => {
+    console.log('Command:', e.detail.command, e.detail.args);
+  });
+</script>
 ```

package/docs/ai/components/testimonial.md

@@ -0,0 +1,56 @@
+# snice-testimonial
+
+Testimonial/quote card with author info, avatar, star rating, and variant styles.
+
+## Properties
+
+```ts
+quote: string = ''
+author: string = ''
+avatar: string = ''            // URL for author avatar image
+role: string = ''              // e.g. "CEO"
+company: string = ''           // e.g. "Acme Inc" (renders as "role at company")
+rating: number = 0             // 0-5 star rating (0 = hidden)
+variant: 'card' | 'minimal' | 'featured' = 'card'
+```
+
+## Variants
+
+- `card` - Default. Background, border, and shadow
+- `minimal` - Left border accent, no background
+- `featured` - Primary-colored background with inverse text
+
+## CSS Custom Properties
+
+- `--snice-color-background-element` - Card background (default: `rgb(252 251 249)`)
+- `--snice-color-border` - Card border (default: `rgb(226 226 226)`)
+- `--snice-color-primary` - Quote icon, minimal border, featured bg (default: `rgb(37 99 235)`)
+- `--snice-color-text` - Text color (default: `rgb(23 23 23)`)
+- `--snice-color-text-secondary` - Author role color
+- `--snice-color-text-inverse` - Featured variant text (default: `rgb(250 250 250)`)
+- `--snice-color-warning` - Star rating color (default: `rgb(234 179 8)`)
+- `--snice-shadow-sm` - Card shadow
+- `--snice-spacing-lg` - Card padding (default: `1.5rem`)
+- `--snice-border-radius-lg` - Card border radius (default: `0.5rem`)
+
+## Usage
+
+```html
+<snice-testimonial
+  quote="This product changed my workflow completely."
+  author="Jane Doe"
+  role="CTO"
+  company="Acme Corp"
+  avatar="https://example.com/jane.jpg"
+  rating="5"
+  variant="card"
+></snice-testimonial>
+
+<!-- Featured style -->
+<snice-testimonial
+  quote="Outstanding experience from start to finish."
+  author="John Smith"
+  rating="4"
+  variant="featured"
+></snice-testimonial>
+```

package/docs/ai/components/textarea.md

@@ -1,6 +1,6 @@
 # snice-textarea
 
-Multi-line text input field with auto-grow and character count.
+Multi-line text input with auto-grow and character count. Form-associated.
 
 ## Properties
 
@@ -15,74 +15,42 @@ required: boolean = false;
 invalid: boolean = false;
 readonly: boolean = false;
 label: string = '';
-helperText: string = '';
-errorText: string = '';
+helperText: string = '';       // attr: helper-text
+errorText: string = '';        // attr: error-text
 rows: number = 3;
 cols: number = -1;
 minlength: number = -1;
 maxlength: number = -1;
 autocomplete: string = '';
 name: string = '';
-autoGrow: boolean = false;
+autoGrow: boolean = false;    // attr: auto-grow
 loading: boolean = false;
 ```
 
+## Events
+
+- `textarea-input` → `{ value, textarea }` - On input
+- `textarea-change` → `{ value, textarea }` - On change
+- `textarea-focus` → `{ textarea }` - On focus
+- `textarea-blur` → `{ textarea }` - On blur
+
 ## Methods
 
 - `focus()` - Focus textarea
 - `blur()` - Blur textarea
 - `select()` - Select text
 
-## Events
-
-- `textarea-input` - {value, textarea}
-- `textarea-change` - {value, textarea}
-- `textarea-focus` - {textarea}
-- `textarea-blur` - {textarea}
-
 ## Usage
 
 ```html
-<!-- Basic -->
 <snice-textarea label="Comments" placeholder="Enter comments"></snice-textarea>
-
-<!-- Variants -->
-<snice-textarea variant="outlined"></snice-textarea>
 <snice-textarea variant="filled"></snice-textarea>
 <snice-textarea variant="underlined"></snice-textarea>
-
-<!-- Rows -->
 <snice-textarea rows="5"></snice-textarea>
-
-<!-- Auto-grow -->
 <snice-textarea auto-grow></snice-textarea>
-
-<!-- Character count -->
 <snice-textarea maxlength="500"></snice-textarea>
-
-<!-- Resize options -->
-<snice-textarea resize="none"></snice-textarea>
 <snice-textarea resize="both"></snice-textarea>
-
-<!-- Sizes -->
 <snice-textarea size="small"></snice-textarea>
-<snice-textarea size="medium"></snice-textarea>
-<snice-textarea size="large"></snice-textarea>
-
-<!-- Helper text -->
 <snice-textarea helper-text="Max 500 characters"></snice-textarea>
-
-<!-- Error state -->
 <snice-textarea invalid error-text="Required field"></snice-textarea>
 ```
-
-## Features
-
-- Form-associated custom element
-- 3 visual variants
-- Auto-grow height option
-- Character counter
-- Resizable (4 modes)
-- Helper and error text
-- 3 sizes
-- Keyboard accessible

package/docs/ai/components/theme.md

@@ -0,0 +1,120 @@
+# theme.css
+
+CSS-only design token system. No component — just import the stylesheet.
+
+## Usage
+
+```html
+<link rel="stylesheet" href="snice/components/theme/theme.css">
+```
+
+## Themes
+
+- Default: light theme on `:root`
+- `data-theme="dark"`: dark theme
+- `data-theme="light"`: force light
+- No attribute: follows `prefers-color-scheme`
+
+```html
+<html data-theme="dark">...</html>
+```
+
+## Tokens
+
+### Colors
+
+```css
+--snice-color-primary
+--snice-color-success
+--snice-color-warning
+--snice-color-danger
+--snice-color-neutral
+--snice-color-text
+--snice-color-text-secondary
+--snice-color-text-tertiary
+--snice-color-text-inverse
+--snice-color-background
+--snice-color-background-secondary
+--snice-color-background-tertiary
+--snice-color-background-element
+--snice-color-background-input
+--snice-color-border
+--snice-color-border-hover
+--snice-color-border-focus
+```
+
+### Spacing
+
+```css
+--snice-spacing-3xs: 0.125rem;  /* 2px */
+--snice-spacing-2xs: 0.25rem;   /* 4px */
+--snice-spacing-xs: 0.5rem;     /* 8px */
+--snice-spacing-sm: 0.75rem;    /* 12px */
+--snice-spacing-md: 1rem;       /* 16px */
+--snice-spacing-lg: 1.5rem;     /* 24px */
+--snice-spacing-xl: 2rem;       /* 32px */
+--snice-spacing-2xl: 3rem;      /* 48px */
+--snice-spacing-3xl: 4rem;      /* 64px */
+```
+
+### Typography
+
+```css
+--snice-font-family: system font stack
+--snice-font-family-mono: monospace stack
+--snice-font-size-2xs..4xl: 10px..36px
+--snice-font-weight-light..bold: 300..700
+--snice-line-height-dense|normal|loose: 1.25|1.5|1.75
+```
+
+### Border Radius
+
+```css
+--snice-border-radius-sm..xl: 2px..16px
+--snice-border-radius-circle: 50%
+--snice-border-radius-pill: 9999px
+```
+
+### Shadows
+
+```css
+--snice-shadow-xs..2xl
+--snice-shadow-inset-sm|md
+```
+
+### Transitions
+
+```css
+--snice-transition-fast: 150ms
+--snice-transition-medium: 250ms
+--snice-transition-slow: 350ms
+```
+
+### Z-Index
+
+```css
+--snice-z-index-dropdown: 1000
+--snice-z-index-sticky: 1020
+--snice-z-index-fixed: 1030
+--snice-z-index-modal-backdrop: 1040
+--snice-z-index-modal: 1050
+--snice-z-index-popover: 1060
+--snice-z-index-tooltip: 1070
+```
+
+### Focus
+
+```css
+--snice-focus-ring-width: 2px
+--snice-focus-ring-color: blue-500/0.5
+--snice-focus-ring-offset: 2px
+```
+
+### Color Primitives (HSL)
+
+Gray, blue, green, red, yellow scales from 50-950:
+
+```css
+--snice-color-blue-500: 217 91% 60%;
+color: hsl(var(--snice-color-blue-500));
+```