snice 4.27.0 → 4.29.0

package/docs/components/color-display.md

@@ -1,8 +1,14 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/color-display.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/color-display.md -->
 
 # Color Display Component
 
-The `<snice-color-display>` component displays colors with a swatch and formatted label.
+Displays colors with a swatch and formatted label. Supports hex, RGB, and HSL formats with configurable swatch sizes.
+
+## Table of Contents
+- [Properties](#properties)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
 
 ## Properties
 
@@ -10,29 +16,45 @@ The `<snice-color-display>` component displays colors with a swatch and formatte
 |----------|------|---------|-------------|
 | `value` | `string` | `''` | Color value (hex format) |
 | `format` | `'hex' \| 'rgb' \| 'hsl'` | `'hex'` | Display format |
-| `showSwatch` | `boolean` | `true` | Show color swatch |
-| `showLabel` | `boolean` | `true` | Show color label |
-| `swatchSize` | `'small' \| 'medium' \| 'large'` | `'medium'` | Swatch size |
+| `showSwatch` (attr: `show-swatch`) | `boolean` | `true` | Show color swatch |
+| `showLabel` (attr: `show-label`) | `boolean` | `true` | Show color label |
+| `swatchSize` (attr: `swatch-size`) | `'small' \| 'medium' \| 'large'` | `'medium'` | Swatch size |
 | `label` | `string` | `''` | Custom label text |
 
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `container` | The outer container |
+| `swatch` | The color swatch element |
+| `label` | The color label text |
+
+```css
+snice-color-display::part(swatch) {
+  border-radius: 50%;
+}
+
+snice-color-display::part(label) {
+  font-family: monospace;
+}
+```
+
 ## Basic Usage
 
 ```html
 <snice-color-display value="#3b82f6"></snice-color-display>
 ```
 
-## Examples
-
-### Basic Colors
-
-```html
-<snice-color-display value="#ff0000"></snice-color-display>
-<snice-color-display value="#00ff00"></snice-color-display>
-<snice-color-display value="#0000ff"></snice-color-display>
+```typescript
+import 'snice/components/color-display/snice-color-display';
 ```
 
+## Examples
+
 ### Color Formats
 
+Use the `format` attribute to change the displayed color format.
+
 ```html
 <snice-color-display value="#3b82f6" format="hex"></snice-color-display>
 <snice-color-display value="#3b82f6" format="rgb"></snice-color-display>
@@ -41,6 +63,8 @@ The `<snice-color-display>` component displays colors with a swatch and formatte
 
 ### Swatch Sizes
 
+Use `swatch-size` to change the swatch dimensions.
+
 ```html
 <snice-color-display value="#10b981" swatch-size="small"></snice-color-display>
 <snice-color-display value="#10b981" swatch-size="medium"></snice-color-display>
@@ -49,6 +73,8 @@ The `<snice-color-display>` component displays colors with a swatch and formatte
 
 ### Custom Labels
 
+Use the `label` attribute to display a custom name instead of the color value.
+
 ```html
 <snice-color-display value="#ef4444" label="Error Red"></snice-color-display>
 <snice-color-display value="#10b981" label="Success Green"></snice-color-display>
@@ -56,51 +82,16 @@ The `<snice-color-display>` component displays colors with a swatch and formatte
 
 ### Swatch Only
 
-```html
-<snice-color-display
-  value="#3b82f6"
-  show-label="false"
-  swatch-size="large"
-></snice-color-display>
-```
-
-### Label Only
+Hide the label for a swatch-only display.
 
 ```html
-<snice-color-display
-  value="#3b82f6"
-  show-swatch="false"
-  format="rgb"
-></snice-color-display>
+<snice-color-display value="#3b82f6" show-label="false" swatch-size="large"></snice-color-display>
 ```
 
-## CSS Parts
-
-Style internal elements from outside the shadow DOM using `::part()`.
-
-| Part | Element | Description |
-|------|---------|-------------|
-| `container` | `<div>` | The outer container |
-| `swatch` | `<div>` | The color swatch element |
-| `label` | `<span>` | The color label text |
-
-```css
-snice-color-display::part(container) {
-  gap: 0.5rem;
-}
+### Label Only
 
-snice-color-display::part(swatch) {
-  border-radius: 50%;
-}
+Hide the swatch for a text-only color value.
 
-snice-color-display::part(label) {
-  font-family: monospace;
-}
+```html
+<snice-color-display value="#3b82f6" show-swatch="false" format="rgb"></snice-color-display>
 ```
-
-## Notes
-
-- Colors must be provided in hex format (#RRGGBB)
-- The component automatically converts to RGB and HSL formats
-- When no custom label is provided, the formatted color value is used
-- Swatch and label can be shown/hidden independently

package/docs/components/color-picker.md

@@ -1,44 +1,52 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/color-picker.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/color-picker.md -->
 
 # Color Picker Component
 
-The `<snice-color-picker>` component provides a color selection interface with format conversion and preset colors.
+A color selection interface with format conversion, preset colors, and form integration.
+
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
 
 ## Properties
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Size variant |
 | `value` | `string` | `'#000000'` | Current color value |
 | `format` | `'hex' \| 'rgb' \| 'hsl'` | `'hex'` | Display format |
-| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Size variant |
 | `label` | `string` | `''` | Label text |
-| `helperText` (attr: `helper-text`) | `string` | `''` | Helper text |
-| `errorText` (attr: `error-text`) | `string` | `''` | Error message |
+| `helperText` (attr: `helper-text`) | `string` | `''` | Helper text below the input |
+| `errorText` (attr: `error-text`) | `string` | `''` | Error message text |
 | `disabled` | `boolean` | `false` | Disabled state |
-| `required` | `boolean` | `false` | Required state |
+| `required` | `boolean` | `false` | Required state for form validation |
 | `invalid` | `boolean` | `false` | Invalid state |
 | `name` | `string` | `''` | Form field name |
-| `showInput` (attr: `show-input`) | `boolean` | `true` | Show text input |
-| `showPresets` (attr: `show-presets`) | `boolean` | `false` | Show preset colors |
-| `presets` | `string[]` | `[...]` | Preset color values |
-| `loading` | `boolean` | `false` | Loading state |
+| `showInput` (attr: `show-input`) | `boolean` | `true` | Show text input field |
+| `showPresets` (attr: `show-presets`) | `boolean` | `false` | Show preset color swatches |
+| `presets` | `string[]` | `[...]` | Array of preset color values |
+| `loading` | `boolean` | `false` | Loading state with spinner |
 
 ## Methods
 
-### `focus(): void`
-Focus the color picker.
-
-### `blur(): void`
-Blur the color picker.
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `focus()` | -- | Focus the color picker input |
+| `blur()` | -- | Remove focus from the color picker input |
 
 ## Events
 
 | Event | Detail | Description |
 |-------|--------|-------------|
-| `color-picker-input` | `{ value: string, colorPicker }` | Fired during color input |
-| `color-picker-change` | `{ value: string, colorPicker }` | Fired when color changes |
-| `color-picker-focus` | `{ colorPicker }` | Fired on input focus |
-| `color-picker-blur` | `{ colorPicker }` | Fired on input blur |
+| `color-picker-input` | `{ value: string, colorPicker }` | Fired during color input as the user adjusts the color |
+| `color-picker-change` | `{ value: string, colorPicker }` | Fired when the color value is committed |
+| `color-picker-focus` | `{ colorPicker }` | Fired when the input receives focus |
+| `color-picker-blur` | `{ colorPicker }` | Fired when the input loses focus |
 
 ## CSS Parts
 
@@ -48,47 +56,106 @@ Blur the color picker.
 | `error-text` | Error text element |
 | `helper-text` | Helper text element |
 
+```css
+snice-color-picker::part(error-text) {
+  font-size: 0.75rem;
+  color: red;
+}
+```
+
 ## Basic Usage
 
 ```html
-<snice-color-picker
-  label="Brand Color"
-  value="#3b82f6"
-  show-presets
-></snice-color-picker>
+<snice-color-picker label="Brand Color" value="#3b82f6"></snice-color-picker>
+```
+
+```typescript
+import 'snice/components/color-picker/snice-color-picker';
 ```
 
 ## Examples
 
-### Basic
+### Color Formats
+
+Use the `format` attribute to change the displayed color format.
 
 ```html
-<snice-color-picker label="Background Color"></snice-color-picker>
+<snice-color-picker format="hex" label="Hex Color"></snice-color-picker>
+<snice-color-picker format="rgb" label="RGB Color"></snice-color-picker>
+<snice-color-picker format="hsl" label="HSL Color"></snice-color-picker>
 ```
 
-### With Presets
+### Sizes
+
+Use the `size` attribute to change the picker dimensions.
 
 ```html
-<snice-color-picker
-  label="Theme Color"
-  show-presets
-></snice-color-picker>
+<snice-color-picker size="small" label="Small"></snice-color-picker>
+<snice-color-picker size="medium" label="Medium"></snice-color-picker>
+<snice-color-picker size="large" label="Large"></snice-color-picker>
 ```
 
-### Different Formats
+### With Preset Colors
+
+Set `show-presets` to display a row of preset color swatches for quick selection.
 
 ```html
-<snice-color-picker format="hex" label="Hex"></snice-color-picker>
-<snice-color-picker format="rgb" label="RGB"></snice-color-picker>
-<snice-color-picker format="hsl" label="HSL"></snice-color-picker>
+<snice-color-picker label="Theme Color" show-presets></snice-color-picker>
 ```
 
 ### Custom Presets
 
+Use the `presets` property to provide your own set of preset colors.
+
 ```html
 <snice-color-picker
   label="Brand Colors"
   show-presets
-  presets='["#ff0000", "#00ff00", "#0000ff"]'
+  presets='["#ff0000", "#00ff00", "#0000ff", "#ffcc00"]'
+></snice-color-picker>
+```
+
+### Without Text Input
+
+Set `show-input="false"` to hide the text input and show only the color swatch.
+
+```html
+<snice-color-picker label="Pick a Color" show-input="false"></snice-color-picker>
+```
+
+### Form Validation
+
+Use `required`, `invalid`, and `error-text` for form validation feedback.
+
+```html
+<snice-color-picker
+  label="Required Color"
+  required
+  invalid
+  error-text="Please select a color"
 ></snice-color-picker>
 ```
+
+### Event Handling
+
+Listen for color changes to sync with your application state.
+
+```javascript
+const picker = document.querySelector('snice-color-picker');
+
+picker.addEventListener('color-picker-change', (e) => {
+  console.log('Color changed to:', e.detail.value);
+});
+
+picker.addEventListener('color-picker-input', (e) => {
+  // Fires continuously as the user adjusts
+  document.body.style.backgroundColor = e.detail.value;
+});
+```
+
+## Accessibility
+
+- Form-associated custom element with native form integration
+- Label association for screen readers
+- Keyboard accessible color input
+- Error and helper text announced to assistive technology

package/docs/components/command-palette.md

@@ -1,8 +1,8 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/command-palette.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/command-palette.md -->
 
 # Command Palette Component
 
-A searchable command palette overlay (⌘K) for quick access to application commands and actions.
+A searchable command palette overlay for quick access to application commands and actions. Opens with Cmd+K / Ctrl+K.
 
 ## Table of Contents
 - [Properties](#properties)
@@ -11,8 +11,7 @@ A searchable command palette overlay (⌘K) for quick access to application comm
 - [CSS Parts](#css-parts)
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
-- [CommandItem Interface](#commanditem-interface)
-- [Keyboard Shortcuts](#keyboard-shortcuts)
+- [Keyboard Navigation](#keyboard-navigation)
 - [Accessibility](#accessibility)
 
 ## Properties
@@ -20,32 +19,81 @@ A searchable command palette overlay (⌘K) for quick access to application comm
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
 | `open` | `boolean` | `false` | Palette visibility |
-| `commands` | `CommandItem[]` | `[]` | Array of commands |
-| `placeholder` | `string` | `'Type a command or search...'` | Search input placeholder |
-| `noResultsText` | `string` | `'No results found'` | Empty state text |
-| `maxResults` | `number` | `50` | Maximum results to display |
-| `showRecentCommands` | `boolean` | `true` | Show recent commands when search is empty |
-| `recentCommandsLimit` | `number` | `5` | Number of recent commands to track |
-| `caseSensitive` | `boolean` | `false` | Case-sensitive search |
+| `commands` | `CommandItem[]` | `[]` | Array of command objects |
+| `placeholder` | `string` | `'Type a command or search...'` | Search input placeholder text |
+| `noResultsText` (attr: `no-results-text`) | `string` | `'No results found'` | Text shown when search yields no results |
+| `maxResults` (attr: `max-results`) | `number` | `50` | Maximum number of results to display |
+| `showRecentCommands` (attr: `show-recent-commands`) | `boolean` | `true` | Show recently used commands when search is empty |
+| `recentCommandsLimit` (attr: `recent-commands-limit`) | `number` | `5` | Number of recent commands to track |
+| `caseSensitive` (attr: `case-sensitive`) | `boolean` | `false` | Enable case-sensitive search matching |
+
+### CommandItem Interface
+
+```typescript
+interface CommandItem {
+  id: string;              // Unique identifier
+  label: string;           // Command name
+  description?: string;    // Command description
+  icon?: string;           // Text/emoji icon
+  iconImage?: string;      // Icon image URL
+  shortcut?: string;       // Keyboard shortcut display text
+  category?: string;       // Category for grouping
+  disabled?: boolean;      // Disable command
+  action?: () => void | Promise<void>;  // Command action
+  data?: any;              // Custom data
+}
+```
 
 ## Methods
 
-- `show()` - Open the palette
-- `close()` - Close the palette
-- `toggle()` - Toggle palette visibility
-- `addCommand(command: CommandItem)` - Add a command
-- `removeCommand(id: string)` - Remove a command
-- `executeCommand(id: string)` - Execute command by ID
-- `clearSearch()` - Clear search input
-- `focus()` - Focus search input
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `show()` | -- | Open the palette |
+| `close()` | -- | Close the palette |
+| `toggle()` | -- | Toggle palette visibility |
+| `addCommand()` | `command: CommandItem` | Add a command dynamically |
+| `removeCommand()` | `id: string` | Remove a command by ID |
+| `executeCommand()` | `id: string` | Execute a command by ID |
+| `clearSearch()` | -- | Clear the search input |
+| `focus()` | -- | Focus the search input |
 
 ## Events
 
-- `command-palette-open` - Fired when palette opens
-- `command-palette-close` - Fired when palette closes
-- `command-select` - Fired when command is selected (detail: { command, palette })
-- `command-execute` - Fired when command is executed (detail: { command, palette })
-- `command-search` - Fired when search changes (detail: { query, results, palette })
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `command-palette-open` | `{ palette }` | Fired when the palette opens |
+| `command-palette-close` | `{ palette }` | Fired when the palette closes |
+| `command-select` | `{ command, palette }` | Fired when a command is highlighted/selected |
+| `command-execute` | `{ command, palette }` | Fired when a command is executed |
+| `command-search` | `{ query, results, palette }` | Fired when the search input changes |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `container` | Main palette container |
+| `search` | Search area wrapper |
+| `input` | Search input element |
+| `results` | Results list container |
+| `empty` | Empty state message |
+| `category` | Category group header |
+| `item` | Individual command item button |
+| `item-icon` | Item icon wrapper |
+| `item-icon-image` | Item icon image element |
+| `item-content` | Item label and description wrapper |
+| `item-label` | Item label text |
+| `item-description` | Item description text |
+| `item-shortcut` | Keyboard shortcut badge |
+
+```css
+snice-command-palette::part(container) {
+  max-width: 800px;
+}
+
+snice-command-palette::part(item) {
+  border-radius: 0.25rem;
+}
+```
 
 ## Basic Usage
 
@@ -67,21 +115,24 @@ A searchable command palette overlay (⌘K) for quick access to application comm
     {
       id: 'save',
       label: 'Save',
-      description: 'Save the current file',
       icon: '💾',
       shortcut: '⌘S',
       category: 'File',
       action: () => console.log('File saved')
     }
   ];
-
-  // Opens automatically with ⌘K or Ctrl+K
 </script>
 ```
 
+```typescript
+import 'snice/components/command-palette/snice-command-palette';
+```
+
 ## Examples
 
-### Basic Commands
+### Categorized Commands
+
+Group commands by category for organized navigation.
 
 ```html
 <snice-command-palette id="palette"></snice-command-palette>
@@ -96,7 +147,9 @@ A searchable command palette overlay (⌘K) for quick access to application comm
 </script>
 ```
 
-### With Actions
+### Commands with Actions
+
+Attach action functions to commands for immediate execution.
 
 ```javascript
 palette.commands = [
@@ -104,9 +157,7 @@ palette.commands = [
     id: 'theme-toggle',
     label: 'Toggle Theme',
     icon: '🌓',
-    action: () => {
-      document.body.classList.toggle('dark-mode');
-    }
+    action: () => document.body.classList.toggle('dark-mode')
   },
   {
     id: 'logout',
@@ -122,6 +173,8 @@ palette.commands = [
 
 ### Custom Trigger
 
+Use `show()` to open the palette from a custom button instead of the keyboard shortcut.
+
 ```html
 <button onclick="palette.show()">Open Commands</button>
 <snice-command-palette id="palette"></snice-command-palette>
@@ -129,6 +182,8 @@ palette.commands = [
 
 ### Event Handling
 
+Listen for command execution to log analytics or trigger side effects.
+
 ```javascript
 palette.addEventListener('command-execute', (e) => {
   console.log('Executed:', e.detail.command.label);
@@ -136,67 +191,18 @@ palette.addEventListener('command-execute', (e) => {
 });
 ```
 
-## CSS Parts
-
-Style internal elements from outside the shadow DOM using `::part()`.
-
-| Part | Element | Description |
-|------|---------|-------------|
-| `container` | `<div>` | Main palette container |
-| `search` | `<div>` | Search area wrapper |
-| `input` | `<input>` | Search input element |
-| `results` | `<div>` | Results list container |
-| `empty` | `<div>` | Empty state message |
-| `category` | `<div>` | Category group header |
-| `item` | `<button>` | Individual command item |
-| `item-icon` | `<div>` | Item icon wrapper |
-| `item-icon-image` | `<img>` | Item icon image |
-| `item-content` | `<div>` | Item label and description wrapper |
-| `item-label` | `<div>` | Item label text |
-| `item-description` | `<div>` | Item description text |
-| `item-shortcut` | `<div>` | Keyboard shortcut badge |
-
-```css
-snice-command-palette::part(container) {
-  max-width: 800px;
-}
-
-snice-command-palette::part(item) {
-  border-radius: 0.25rem;
-}
-```
+## Keyboard Navigation
 
-## CommandItem Interface
-
-```typescript
-interface CommandItem {
-  id: string;              // Unique identifier
-  label: string;           // Command name
-  description?: string;    // Command description
-  icon?: string;           // Text/emoji icon
-  iconImage?: string;      // Icon image URL
-  shortcut?: string;       // Keyboard shortcut display
-  category?: string;       // Command category for grouping
-  disabled?: boolean;      // Disable command
-  action?: () => void | Promise<void>;  // Command action
-  data?: any;             // Custom data
-}
-```
-
-## Keyboard Shortcuts
-
-- `⌘K` or `Ctrl+K` - Toggle palette
-- `Escape` - Close palette
-- `↑` / `↓` - Navigate commands
-- `Enter` - Execute active command
+| Key | Action |
+|-----|--------|
+| `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
-
-## Browser Support
-
-Modern browsers with Custom Elements v1 support
+- Full keyboard navigation with arrow keys
+- ARIA labels and roles on all interactive elements
+- Focus trap when palette is open
+- Screen reader announcements for search results

package/docs/components/comments.md

@@ -1,8 +1,8 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/comments.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/comments.md -->
 
 # Comments Component
 
-The comments component provides a threaded comment system with nested replies, like/unlike functionality, user avatars, relative timestamps, and current-user awareness for delete permissions.
+A threaded comment system with nested replies, like/unlike functionality, user avatars, relative timestamps, and current-user awareness for delete permissions. Supports both programmatic and declarative usage.
 
 ## Table of Contents
 - [Properties](#properties)
@@ -77,6 +77,13 @@ interface Comment {
 | `input-area` | The new comment input area |
 | `list` | The comments list container |
 
+```css
+snice-comments::part(base) {
+  max-width: 600px;
+  margin: 0 auto;
+}
+```
+
 ## Basic Usage
 
 ```html
@@ -91,7 +98,7 @@ import 'snice/components/comments/snice-comments';
 
 ### Basic Comment Thread
 
-Set comments via JavaScript to display a comment thread with the current user set.
+Set comments via JavaScript to display a threaded conversation.
 
 ```html
 <snice-comments id="my-comments" current-user="Alice" allow-replies allow-likes></snice-comments>
@@ -158,7 +165,7 @@ Use the `replies` array within a comment to create threaded conversations. Contr
 </script>
 ```
 
-### Read-Only Comments (No Replies or Likes)
+### Read-Only Comments
 
 Disable replies and likes for a read-only display of past comments.
 
@@ -179,7 +186,7 @@ Disable replies and likes for a read-only display of past comments.
 </script>
 ```
 
-### Listening to Events
+### Event Handling
 
 Listen for comment actions to sync with a backend.
 
@@ -192,7 +199,6 @@ Listen for comment actions to sync with a backend.
 
   el.addEventListener('comment-add', (e) => {
     console.log('New comment:', e.detail.text, 'by', e.detail.author);
-    // POST to your API
   });
 
   el.addEventListener('comment-reply', (e) => {
@@ -229,7 +235,7 @@ Comments can also be defined declaratively using `<snice-comment>` child element
 
 ## Accessibility
 
-- **Keyboard support**: Tab through comments, reply buttons, and like buttons. Enter or Space to activate controls.
-- **Timestamps**: Displayed as relative times (e.g., "2 hours ago") for quick scanning
-- **Current user**: Delete controls only appear on the current user's own comments to prevent confusion
-- **Screen readers**: Comment structure and author information are conveyed through semantic markup
+- Keyboard support: Tab through comments, reply buttons, and like buttons. Enter or Space to activate controls.
+- Timestamps displayed as relative times (e.g., "2 hours ago") for quick scanning
+- Delete controls only appear on the current user's own comments
+- Semantic markup conveys comment structure and author information to screen readers