snice 4.27.0 → 4.29.0

package/docs/components/kanban.md

@@ -1,128 +1,86 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/kanban.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/kanban.md -->
 
 # Kanban Component
 
-Drag-and-drop kanban board with columns and cards.
+Drag-and-drop kanban board with columns and cards. Supports labels with custom colors and icons, filtering, search, and programmatic card management.
+
+## 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 |
 |----------|------|---------|-------------|
-| `columns` | `KanbanColumn[]` | `[]` | Board columns |
-| `allowDragDrop` | `boolean` | `true` | Enable drag and drop |
-| `showCardCount` | `boolean` | `true` | Show card count per column |
-
-## Methods
-
-### `addColumn(column: KanbanColumn): void`
-Add new column to board.
-
-```javascript
-kanban.addColumn({
-  id: 'review',
-  title: 'In Review',
-  cards: []
-});
-```
-
-### `removeColumn(id: string | number): void`
-Remove column from board.
-
-```javascript
-kanban.removeColumn('review');
-```
-
-### `addCard(columnId: string | number, card: KanbanCard): void`
-Add card to specific column.
-
-```javascript
-kanban.addCard('todo', {
-  id: 10,
-  title: 'New Task',
-  assignee: 'John'
-});
-```
-
-### `removeCard(cardId: string | number): void`
-Remove card from board.
-
-```javascript
-kanban.removeCard(10);
-```
+| `columns` | `KanbanColumn[]` | `[]` | Board columns (set via JavaScript) |
+| `allowDragDrop` (attr: `allow-drag-drop`) | `boolean` | `true` | Enable drag and drop |
+| `showCardCount` (attr: `show-card-count`) | `boolean` | `true` | Show card count per column |
 
-### `moveCard(cardId: string | number, targetColumnId: string | number, targetIndex?: number): void`
-Move card to different column (and optionally specific position).
+### KanbanColumn Interface
 
-```javascript
-// Move to different column
-kanban.moveCard(1, 'done');
-
-// Move to specific position in column
-kanban.moveCard(1, 'done', 0); // Move to top
-```
-
-### `filterByLabels(labels: string[]): void`
-Filter cards by labels (shows cards with ANY of the specified labels).
-
-```javascript
-kanban.filterByLabels(['bug', 'high-priority']);
-```
-
-### `search(query: string): void`
-Search cards by title or description.
-
-```javascript
-kanban.search('landing page');
+```typescript
+interface KanbanColumn {
+  id: string | number;
+  title: string;
+  cards: KanbanCard[];
+  color?: string;
+  limit?: number;
+  collapsed?: boolean;
+}
 ```
 
-### `clearFilters(): void`
-Clear all active filters (labels and search).
+### KanbanCard Interface
 
-```javascript
-kanban.clearFilters();
+```typescript
+interface KanbanCard {
+  id: string | number;
+  title: string;
+  description?: string;
+  assignee?: string;
+  labels?: (string | KanbanLabel)[];  // String or full label object
+  color?: string;
+  data?: any;
+}
 ```
 
-### `getColumn(id: string | number): KanbanColumn | undefined`
-Get column by ID.
+### KanbanLabel Interface
 
-```javascript
-const column = kanban.getColumn('todo');
-console.log(`${column.title} has ${column.cards.length} cards`);
+```typescript
+interface KanbanLabel {
+  text: string;
+  color?: string;            // Text color
+  background?: string;       // Background color
+  icon?: string;            // Emoji or text icon
+  iconPosition?: 'left' | 'right';  // Icon placement
+}
 ```
 
-### `getCard(id: string | number): KanbanCard | undefined`
-Get card by ID.
+## Methods
 
-```javascript
-const card = kanban.getCard(1);
-console.log(card.title);
-```
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `addColumn()` | `column: KanbanColumn` | Add new column to board |
+| `removeColumn()` | `id: string \| number` | Remove column from board |
+| `addCard()` | `columnId: string \| number, card: KanbanCard` | Add card to specific column |
+| `removeCard()` | `cardId: string \| number` | Remove card from board |
+| `moveCard()` | `cardId: string \| number, targetColumnId: string \| number, targetIndex?: number` | Move card to different column and optional position |
+| `getColumn()` | `id: string \| number` | Get column by ID |
+| `getCard()` | `id: string \| number` | Get card by ID |
+| `filterByLabels()` | `labels: string[]` | Filter cards by labels (shows cards with ANY match) |
+| `search()` | `query: string` | Search cards by title or description |
+| `clearFilters()` | — | Clear all active filters |
 
 ## Events
 
-### `kanban-card-move`
-Dispatched when card is moved between columns.
-
-```javascript
-kanban.addEventListener('kanban-card-move', (e) => {
-  console.log('Card:', e.detail.card);
-  console.log('From:', e.detail.fromColumn);
-  console.log('To:', e.detail.toColumn);
-});
-```
-
-**Detail:** `{ card: KanbanCard, fromColumn: string | number, toColumn: string | number, kanban: SniceKanbanElement }`
-
-### `kanban-card-click`
-Dispatched when card is clicked.
-
-```javascript
-kanban.addEventListener('kanban-card-click', (e) => {
-  showCardDetails(e.detail.card);
-});
-```
-
-**Detail:** `{ card: KanbanCard, kanban: SniceKanbanElement }`
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `kanban-card-move` | `{ card: KanbanCard, fromColumn: string \| number, toColumn: string \| number, kanban: SniceKanbanElement }` | Fired when card is moved between columns |
+| `kanban-card-click` | `{ card: KanbanCard, kanban: SniceKanbanElement }` | Fired when card is clicked |
 
 ## CSS Parts
 
@@ -148,20 +106,29 @@ snice-kanban::part(column-cards) {
 ## Basic Usage
 
 ```typescript
-kanban.columns = [
-  {
-    id: 'todo',
-    title: 'To Do',
-    cards: [
-      { id: 1, title: 'Task 1', description: 'Do something' }
-    ]
-  },
-  {
-    id: 'done',
-    title: 'Done',
-    cards: []
-  }
-];
+import 'snice/components/kanban/snice-kanban';
+```
+
+```html
+<snice-kanban id="board"></snice-kanban>
+
+<script>
+  const kanban = document.getElementById('board');
+  kanban.columns = [
+    {
+      id: 'todo',
+      title: 'To Do',
+      cards: [
+        { id: 1, title: 'Task 1', description: 'Do something' }
+      ]
+    },
+    {
+      id: 'done',
+      title: 'Done',
+      cards: []
+    }
+  ];
+</script>
 ```
 
 ## Examples
@@ -180,9 +147,7 @@ kanban.columns = [
         id: 1,
         title: 'Redesign dashboard',
         labels: [
-          // Simple string label (uses default theme styling)
           'feature',
-          // Rich label with custom colors and icon
           {
             text: 'High Priority',
             color: '#dc2626',
@@ -191,64 +156,12 @@ kanban.columns = [
             iconPosition: 'left'
           }
         ]
-      },
-      {
-        id: 2,
-        title: 'Analytics dashboard',
-        labels: [
-          {
-            text: 'Analytics',
-            color: '#0891b2',
-            background: '#cffafe',
-            icon: '📊',
-            iconPosition: 'left'
-          },
-          {
-            text: 'Shipped',
-            color: '#16a34a',
-            background: '#dcfce7',
-            icon: '🚀',
-            iconPosition: 'right' // Icon on the right
-          }
-        ]
       }
     ]
   }
 ];
 ```
 
-### Filtering and Search
-
-Filter cards by labels or search by text:
-
-```javascript
-// Filter by single label
-kanban.filterByLabels(['bug']);
-
-// Filter by multiple labels (shows cards with ANY of these labels)
-kanban.filterByLabels(['bug', 'high-priority']);
-
-// Search by title or description
-kanban.search('landing page');
-
-// Combine filters and search (both apply)
-kanban.filterByLabels(['feature']);
-kanban.search('dashboard');
-
-// Clear all filters
-kanban.clearFilters();
-```
-
-### Basic Board
-
-```javascript
-kanban.columns = [
-  { id: 'todo', title: 'To Do', cards: [] },
-  { id: 'doing', title: 'Doing', cards: [] },
-  { id: 'done', title: 'Done', cards: [] }
-];
-```
-
 ### With Column Colors
 
 ```javascript
@@ -259,53 +172,27 @@ kanban.columns = [
 ];
 ```
 
-### With WIP Limits
+### Filtering and Search
 
 ```javascript
-kanban.columns = [
-  { id: 'todo', title: 'To Do', cards: [] },
-  { id: 'doing', title: 'Doing', limit: 3, cards: [] },
-  { id: 'done', title: 'Done', cards: [] }
-];
-```
+// Filter by labels (shows cards with ANY of these labels)
+kanban.filterByLabels(['bug', 'high-priority']);
 
-### Rich Cards
+// Search by title or description
+kanban.search('landing page');
 
-```javascript
-kanban.columns = [
-  {
-    id: 'todo',
-    title: 'To Do',
-    cards: [
-      {
-        id: 1,
-        title: 'Design Landing Page',
-        description: 'Create mockups and wireframes',
-        assignee: 'Alice',
-        labels: [
-          'design',
-          { text: 'high-priority', color: '#dc2626', background: '#fee2e2', icon: '⚡' }
-        ],
-        color: '#f44336'
-      }
-    ]
-  }
-];
+// Clear all filters
+kanban.clearFilters();
 ```
 
 ### Event Handling
 
 ```javascript
 kanban.addEventListener('kanban-card-move', (e) => {
-  // Update backend
   updateCardStatus(e.detail.card.id, e.detail.toColumn);
-
-  // Show notification
-  showNotification(`Moved "${e.detail.card.title}" to ${e.detail.toColumn}`);
 });
 
 kanban.addEventListener('kanban-card-click', (e) => {
-  // Show modal with card details
   showCardModal(e.detail.card);
 });
 ```
@@ -314,149 +201,16 @@ kanban.addEventListener('kanban-card-click', (e) => {
 
 ```javascript
 // Add new card
-function addTask(title, columnId) {
-  const newCard = {
-    id: Date.now(),
-    title,
-    assignee: currentUser.name
-  };
-
-  kanban.addCard(columnId, newCard);
-}
+kanban.addCard('todo', { id: Date.now(), title: 'New Task' });
 
 // Move card
-function completeTask(cardId) {
-  kanban.moveCard(cardId, 'done');
-}
-
-// Remove card
-function deleteTask(cardId) {
-  kanban.removeCard(cardId);
-}
-```
-
-### Project Management
-
-```javascript
-kanban.columns = [
-  {
-    id: 'backlog',
-    title: 'Backlog',
-    cards: [
-      { id: 1, title: 'Feature A', labels: ['feature'], assignee: 'John' },
-      { id: 2, title: 'Bug Fix B', labels: ['bug'], color: '#f44336' }
-    ]
-  },
-  {
-    id: 'sprint',
-    title: 'Current Sprint',
-    limit: 5,
-    color: '#ff9800',
-    cards: [
-      {
-        id: 3,
-        title: 'Implement Auth',
-        description: 'JWT-based authentication',
-        assignee: 'Sarah',
-        labels: ['backend', 'security']
-      }
-    ]
-  },
-  {
-    id: 'review',
-    title: 'Code Review',
-    color: '#9c27b0',
-    cards: []
-  },
-  {
-    id: 'deployed',
-    title: 'Deployed',
-    color: '#4caf50',
-    cards: []
-  }
-];
-```
-
-### Personal Task Board
-
-```javascript
-kanban.columns = [
-  {
-    id: 'today',
-    title: 'Today',
-    limit: 3,
-    cards: [
-      { id: 1, title: 'Morning workout', labels: ['health'] },
-      { id: 2, title: 'Team meeting', labels: ['work'] }
-    ]
-  },
-  {
-    id: 'this-week',
-    title: 'This Week',
-    cards: []
-  },
-  {
-    id: 'completed',
-    title: 'Completed',
-    cards: []
-  }
-];
-```
-
-### Bug Tracking
-
-```javascript
-kanban.columns = [
-  {
-    id: 'reported',
-    title: 'Reported',
-    cards: bugs.map(bug => ({
-      id: bug.id,
-      title: bug.title,
-      description: bug.description,
-      assignee: bug.reporter,
-      labels: [bug.severity, bug.priority],
-      color: bug.severity === 'critical' ? '#f44336' : '#ff9800'
-    }))
-  },
-  {
-    id: 'investigating',
-    title: 'Investigating',
-    limit: 5,
-    cards: []
-  },
-  {
-    id: 'fixing',
-    title: 'Fixing',
-    limit: 3,
-    cards: []
-  },
-  {
-    id: 'fixed',
-    title: 'Fixed',
-    cards: []
-  }
-];
-```
-
-### Sales Pipeline
+kanban.moveCard(1, 'done');
 
-```javascript
-kanban.columns = [
-  { id: 'lead', title: 'New Leads', cards: [] },
-  { id: 'contacted', title: 'Contacted', cards: [] },
-  { id: 'qualified', title: 'Qualified', cards: [] },
-  { id: 'proposal', title: 'Proposal Sent', cards: [] },
-  { id: 'closed', title: 'Closed Won', color: '#4caf50', cards: [] }
-];
+// Move to specific position
+kanban.moveCard(1, 'done', 0); // Move to top
 
-// Add deal
-kanban.addCard('lead', {
-  id: deal.id,
-  title: deal.company,
-  description: `$${deal.value}`,
-  assignee: deal.owner
-});
+// Remove card
+kanban.removeCard(2);
 ```
 
 ### Disable Drag and Drop
@@ -479,68 +233,19 @@ kanban.addEventListener('kanban-card-move', async (e) => {
     await fetch('/api/cards/' + e.detail.card.id, {
       method: 'PATCH',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        columnId: e.detail.toColumn
-      })
+      body: JSON.stringify({ columnId: e.detail.toColumn })
     });
   } catch (error) {
-    // Revert on error
     kanban.moveCard(e.detail.card.id, e.detail.fromColumn);
     alert('Failed to move card');
   }
 });
 ```
 
-## KanbanColumn Interface
-
-```typescript
-interface KanbanColumn {
-  id: string | number;
-  title: string;
-  cards: KanbanCard[];
-  color?: string;
-  limit?: number;
-  collapsed?: boolean;
-}
-```
-
-## KanbanLabel Interface
-
-```typescript
-interface KanbanLabel {
-  text: string;
-  color?: string;            // Text color
-  background?: string;       // Background color
-  icon?: string;            // Emoji or text icon
-  iconPosition?: 'left' | 'right';  // Icon placement
-}
-```
-
-## KanbanCard Interface
-
-```typescript
-interface KanbanCard {
-  id: string | number;
-  title: string;
-  description?: string;
-  assignee?: string;
-  labels?: (string | KanbanLabel)[];  // String or full label object
-  color?: string;
-  data?: any;
-}
-```
-
 ## Accessibility
 
 - Keyboard navigation for cards
 - ARIA labels for drag and drop
 - Focus management
 - Screen reader announcements
-
-## Browser Support
-
-- Modern browsers with Custom Elements v1 support
-- HTML5 Drag and Drop API
-- View Transitions API (optional, for smooth animations)
-- Drag and drop between columns and within same column
-- Touch events for mobile (future enhancement)
+- View Transitions API animations (when available)

package/docs/components/key-value.md

@@ -1,22 +1,26 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/key-value.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/key-value.md -->
 
 # Key Value
 `<snice-key-value>`
 
 A key-value pair editor for building UIs like HTTP header editors, environment variable configurators, and settings panels. Supports both declarative child elements and imperative JavaScript APIs.
 
-## Importing
+## Table of Contents
+- [Components](#components)
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [Slots](#slots)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
 
-**ESM (bundler)**
-```typescript
-import 'snice/components/key-value/snice-key-value';
-```
+## Components
 
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-key-value.min.js"></script>
-```
+| Element | Description |
+|---------|-------------|
+| `<snice-key-value>` | Container/editor component |
+| `<snice-kv-pair>` | Data container child element (no shadow DOM) |
 
 ## Properties
 
@@ -67,6 +71,12 @@ import 'snice/components/key-value/snice-key-value';
 | `kv-change` | `{ items: KeyValueItem[] }` | Fired on any change (add, remove, edit) |
 | `kv-copy` | `{ items: KeyValueItem[] }` | Fired when copy button is clicked |
 
+## Slots
+
+| Slot Name | Description |
+|-----------|-------------|
+| (default) | `<snice-kv-pair>` child elements for declarative data |
+
 ## CSS Parts
 
 | Part | Description |
@@ -75,7 +85,7 @@ import 'snice/components/key-value/snice-key-value';
 | `title` | The title element |
 | `copy-button` | The copy button |
 | `rows` | The rows container |
-| `row` | An individual row |
+| `row` | An individual row (edit mode) |
 | `key-input` | The key input field |
 | `value-input` | The value input field |
 | `description-input` | The description input field |