snice 4.27.0 → 4.29.0

package/docs/components/file-upload.md

@@ -1,16 +1,16 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/file-upload.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/file-upload.md -->
 
-# File Upload Component
+# File Upload
 
-The `<snice-file-upload>` component provides a file upload interface with drag-and-drop support, file previews, and validation.
+The `<snice-file-upload>` component provides a file upload interface with drag-and-drop support, file previews, and validation. It is a form-associated custom element.
 
 ## Table of Contents
 - [Properties](#properties)
 - [Methods](#methods)
 - [Events](#events)
+- [CSS Parts](#css-parts)
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
-- [Features](#features)
 
 ## Properties
 
@@ -20,64 +20,49 @@ The `<snice-file-upload>` component provides a file upload interface with drag-a
 | `variant` | `'outlined' \| 'filled'` | `'outlined'` | Visual style variant |
 | `accept` | `string` | `''` | Allowed file types (same as input accept) |
 | `multiple` | `boolean` | `false` | Allow multiple file selection |
-| `label` | `string` | `''` | Label text |
-| `helperText` | `string` | `''` | Helper text below upload area |
-| `errorText` | `string` | `''` | Error message (shown when invalid) |
 | `disabled` | `boolean` | `false` | Whether upload is disabled |
 | `required` | `boolean` | `false` | Whether upload is required |
 | `invalid` | `boolean` | `false` | Whether to show invalid state |
-| `maxSize` | `number` | `-1` | Maximum file size in bytes (-1 = no limit) |
-| `maxFiles` | `number` | `-1` | Maximum number of files (-1 = no limit) |
+| `label` | `string` | `''` | Label text |
+| `helperText` (attr: `helper-text`) | `string` | `''` | Helper text below upload area |
+| `errorText` (attr: `error-text`) | `string` | `''` | Error message (shown when invalid) |
+| `maxSize` (attr: `max-size`) | `number` | `-1` | Maximum file size in bytes (-1 = no limit) |
+| `maxFiles` (attr: `max-files`) | `number` | `-1` | Maximum number of files (-1 = no limit) |
 | `name` | `string` | `''` | Form field name |
-| `dragDrop` | `boolean` | `true` | Enable drag-and-drop |
-| `showPreview` | `boolean` | `true` | Show image previews |
+| `dragDrop` (attr: `drag-drop`) | `boolean` | `true` | Enable drag-and-drop |
+| `showPreview` (attr: `show-preview`) | `boolean` | `true` | Show image previews |
 | `files` | `FileList \| null` | `null` | Selected files (read-only) |
 
 ## Methods
 
-### `clear(): void`
-Remove all selected files.
-
-```typescript
-upload.clear();
-```
-
-### `removeFile(index: number): void`
-Remove a specific file by index.
-
-```typescript
-upload.removeFile(0); // Remove first file
-```
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `clear()` | -- | Remove all selected files |
+| `removeFile(index)` | `index: number` | Remove a specific file by index |
 
 ## Events
 
-### `file-upload-change`
-Fired when files are added or removed.
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `file-upload-change` | `{ files: File[], fileUpload: SniceFileUploadElement }` | Fired when files are added or removed |
+| `file-upload-error` | `{ message: string, fileUpload: SniceFileUploadElement }` | Fired when file validation fails |
 
-**Detail**: `{ files: File[], fileUpload: SniceFileUploadElement }`
-
-```typescript
-upload.addEventListener('file-upload-change', (e) => {
-  console.log('Selected files:', e.detail.files);
-  e.detail.files.forEach(file => {
-    console.log(`- ${file.name} (${file.size} bytes)`);
-  });
-});
-```
+## CSS Parts
 
-### `file-upload-error`
-Fired when file validation fails.
+| Part | Description |
+|------|-------------|
+| `upload-area` | Drop zone container |
+| `input` | Hidden file input |
+| `file-item` | Individual file entry |
+| `error-text` | Error text element |
+| `helper-text` | Helper text element |
 
-**Detail**: `{ message: string, fileUpload: SniceFileUploadElement }`
+## Basic Usage
 
 ```typescript
-upload.addEventListener('file-upload-error', (e) => {
-  console.error('Upload error:', e.detail.message);
-});
+import 'snice/components/file-upload/snice-file-upload';
 ```
 
-## Basic Usage
-
 ```html
 <snice-file-upload
   label="Upload Documents"
@@ -87,8 +72,6 @@ upload.addEventListener('file-upload-error', (e) => {
 ```
 
 ```typescript
-import 'snice/components/file-upload/snice-file-upload';
-
 const upload = document.querySelector('snice-file-upload');
 upload.addEventListener('file-upload-change', (e) => {
   console.log('Files:', e.detail.files);
@@ -164,37 +147,6 @@ upload.addEventListener('file-upload-change', (e) => {
 ></snice-file-upload>
 ```
 
-### File Type Restrictions
-
-```html
-<!-- Images only -->
-<snice-file-upload accept="image/*" label="Images"></snice-file-upload>
-
-<!-- Specific formats -->
-<snice-file-upload accept=".pdf,.doc,.docx" label="Documents"></snice-file-upload>
-
-<!-- Multiple types -->
-<snice-file-upload accept="image/*,.pdf" label="Images and PDFs"></snice-file-upload>
-```
-
-### With Size Validation
-
-```html
-<snice-file-upload
-  label="Upload Photo"
-  accept="image/*"
-  max-size="5242880"
-  helper-text="Maximum 5MB"
-></snice-file-upload>
-
-<script>
-const upload = document.querySelector('snice-file-upload');
-upload.addEventListener('file-upload-error', (e) => {
-  alert(e.detail.message);
-});
-</script>
-```
-
 ### Form Integration
 
 ```html
@@ -213,63 +165,24 @@ upload.addEventListener('file-upload-error', (e) => {
 <script>
 document.getElementById('upload-form').addEventListener('submit', async (e) => {
   e.preventDefault();
-
   const formData = new FormData(e.target);
   const files = formData.getAll('documents');
-
   console.log(`Uploading ${files.length} file(s)...`);
-
-  // Upload to server
-  const response = await fetch('/api/upload', {
-    method: 'POST',
-    body: formData
-  });
-
-  console.log('Upload complete!');
 });
 </script>
 ```
 
 ### Managing Files Programmatically
 
-```html
-<snice-file-upload id="file-upload" multiple></snice-file-upload>
-<button onclick="clearFiles()">Clear All</button>
-<button onclick="removeFirst()">Remove First</button>
-
-<script>
-const upload = document.getElementById('file-upload');
-
-function clearFiles() {
-  upload.clear();
-}
-
-function removeFirst() {
-  upload.removeFile(0);
-}
+```typescript
+upload.clear();
+upload.removeFile(0);
 
 upload.addEventListener('file-upload-change', (e) => {
   console.log(`${e.detail.files.length} file(s) selected`);
 });
-</script>
-```
-
-## CSS Parts
-
-| Part | Description |
-|------|-------------|
-| `upload-area` | Drop zone container |
-| `input` | Hidden file input |
-| `file-item` | Individual file entry |
-| `error-text` | Error text element |
-| `helper-text` | Helper text element |
 
-## Features
-
-- **Drag and Drop**: Native drag-and-drop support with visual feedback
-- **Image Preview**: Automatic thumbnail generation for image files
-- **File Validation**: Size and type validation with error messaging
-- **Multiple Files**: Support for single or multiple file selection
-- **File Management**: Add and remove files before upload
-- **Form Integration**: Form-associated custom element
-- **Accessibility**: Full keyboard support and ARIA attributes
+upload.addEventListener('file-upload-error', (e) => {
+  console.error('Upload error:', e.detail.message);
+});
+```

package/docs/components/flip-card.md

@@ -1,6 +1,6 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/flip-card.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/flip-card.md -->
 
-# Flip Card Component
+# Flip Card
 
 The flip card component creates a two-sided card with a CSS 3D flip animation. Content is placed in front and back slots, and the card can be flipped by clicking, keyboard interaction, or programmatically.
 
@@ -9,10 +9,11 @@ The flip card component creates a two-sided card with a CSS 3D flip animation. C
 - [Methods](#methods)
 - [Events](#events)
 - [Slots](#slots)
-- [CSS Custom Properties](#css-custom-properties)
 - [CSS Parts](#css-parts)
+- [CSS Custom Properties](#css-custom-properties)
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
+- [Keyboard Navigation](#keyboard-navigation)
 - [Accessibility](#accessibility)
 
 ## Properties
@@ -29,7 +30,7 @@ The flip card component creates a two-sided card with a CSS 3D flip animation. C
 | Method | Arguments | Description |
 |--------|-----------|-------------|
 | `flip()` | -- | Toggle between front and back faces |
-| `flipTo()` | `side: 'front' \| 'back'` | Flip to a specific side |
+| `flipTo(side)` | `side: 'front' \| 'back'` | Flip to a specific side |
 
 ## Events
 
@@ -44,21 +45,13 @@ The flip card component creates a two-sided card with a CSS 3D flip animation. C
 | `front` | Content displayed on the front face of the card |
 | `back` | Content displayed on the back face of the card |
 
-## CSS Custom Properties
-
-| Property | Description |
-|----------|-------------|
-| `--flip-duration` | Animation duration (automatically set from the `duration` property) |
-
 ## CSS Parts
 
-Style internal elements from outside the shadow DOM using `::part()`.
-
-| Part | Element | Description |
-|------|---------|-------------|
-| `base` | `<div>` | The outer flip card container |
-| `front` | `<div>` | The front face container |
-| `back` | `<div>` | The back face container |
+| Part | Description |
+|------|-------------|
+| `base` | The outer flip card container |
+| `front` | The front face container |
+| `back` | The back face container |
 
 ```css
 snice-flip-card::part(base) {
@@ -74,8 +67,18 @@ snice-flip-card::part(back) {
 }
 ```
 
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--flip-duration` | Animation duration (automatically set from the `duration` property) |
+
 ## Basic Usage
 
+```typescript
+import 'snice/components/flip-card/snice-flip-card';
+```
+
 ```html
 <snice-flip-card style="width: 300px; height: 200px;">
   <div slot="front">Front side</div>
@@ -83,10 +86,6 @@ snice-flip-card::part(back) {
 </snice-flip-card>
 ```
 
-```typescript
-import 'snice/components/flip-card/snice-flip-card';
-```
-
 ## Examples
 
 ### Horizontal Flip (Default)
@@ -126,13 +125,11 @@ Use `direction="vertical"` to flip the card around the X axis.
 Set `duration` to control the speed of the flip animation.
 
 ```html
-<!-- Slow flip -->
 <snice-flip-card duration="1200" style="width: 250px; height: 180px;">
   <div slot="front">Slow flip (1.2s)</div>
   <div slot="back">Back side</div>
 </snice-flip-card>
 
-<!-- Fast flip -->
 <snice-flip-card duration="200" style="width: 250px; height: 180px;">
   <div slot="front">Fast flip (0.2s)</div>
   <div slot="back">Back side</div>
@@ -155,17 +152,13 @@ Disable click-to-flip and control the card from JavaScript.
   </div>
 </snice-flip-card>
 
-<div style="margin-top: 1rem; display: flex; gap: 0.5rem;">
-  <button onclick="document.getElementById('controlled-card').flipTo('front')">Show Front</button>
-  <button onclick="document.getElementById('controlled-card').flipTo('back')">Show Back</button>
-  <button onclick="document.getElementById('controlled-card').flip()">Toggle</button>
-</div>
+<button onclick="document.getElementById('controlled-card').flipTo('front')">Show Front</button>
+<button onclick="document.getElementById('controlled-card').flipTo('back')">Show Back</button>
+<button onclick="document.getElementById('controlled-card').flip()">Toggle</button>
 ```
 
 ### Flashcard Study Deck
 
-Build a flashcard-style study app by listening to flip events.
-
 ```html
 <snice-flip-card id="flashcard" direction="vertical" style="width: 350px; height: 250px;">
   <div slot="front" style="display: flex; align-items: center; justify-content: center; font-size: 1.25rem; padding: 2rem; text-align: center;">
@@ -177,8 +170,6 @@ Build a flashcard-style study app by listening to flip events.
 </snice-flip-card>
 
 <script type="module">
-  import 'snice/components/flip-card/snice-flip-card';
-
   const card = document.getElementById('flashcard');
   card.addEventListener('flip-change', (e) => {
     console.log(`Now showing: ${e.detail.side}`);
@@ -186,9 +177,14 @@ Build a flashcard-style study app by listening to flip events.
 </script>
 ```
 
+## Keyboard Navigation
+
+When `click-to-flip` is enabled:
+- **Enter** / **Space** -- Toggle the card flip
+
 ## Accessibility
 
 - **Keyboard support**: When `click-to-flip` is enabled, pressing Enter or Space toggles the card
-- **Focus management**: The card is focusable and has `tabindex="0"` when click-to-flip is enabled
-- **ARIA attributes**: The component conveys state for assistive technologies
+- **Focus management**: The card is focusable with `tabindex="0"` when click-to-flip is enabled
+- **ARIA attributes**: The component uses `role="button"` and `aria-label` to convey state for assistive technologies
 - **Visible content**: Both sides of the card accept arbitrary slotted content, allowing for accessible markup on each face

package/docs/components/flow.md

@@ -1,70 +1,98 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/flow.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/flow.md -->
 
 # Flow
-`<snice-flow>`
 
 A node-based flow/diagram editor component for building visual workflows, data pipelines, and node graphs. Features draggable nodes with input/output ports, bezier curve edges, zoom/pan canvas, snap-to-grid, and a minimap overview.
 
-## Importing
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `nodes` | `FlowNode[]` | `[]` | Array of node definitions (set via JS) |
+| `edges` | `FlowEdge[]` | `[]` | Array of edge definitions (set via JS) |
+| `snapToGrid` (attr: `snap-to-grid`) | `boolean` | `true` | Snap node positions to grid |
+| `gridSize` (attr: `grid-size`) | `number` | `20` | Grid spacing in pixels |
+| `zoomEnabled` (attr: `zoom-enabled`) | `boolean` | `true` | Enable mouse wheel zoom |
+| `panEnabled` (attr: `pan-enabled`) | `boolean` | `true` | Enable background pan |
+| `minimap` | `boolean` | `true` | Show minimap overview |
+| `editable` | `boolean` | `true` | Allow drawing new edges |
+
+### FlowNode Interface
 
-**ESM (bundler)**
 ```typescript
-import 'snice/components/flow/snice-flow';
-```
+interface FlowNode {
+  id: string;
+  x: number;
+  y: number;
+  type?: string;                    // Shown as small label above title
+  data?: Record<string, unknown>;   // Custom data payload
+  label?: string;                   // Node title
+  width?: number;                   // Default: 160
+  height?: number;                  // Default: 80
+  inputs?: FlowPort[];              // Input ports (left side)
+  outputs?: FlowPort[];             // Output ports (right side)
+  color?: string;                   // Header background color
+  selected?: boolean;
+}
 
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-flow.min.js"></script>
+interface FlowPort {
+  id: string;
+  label?: string;
+  type?: string;
+}
 ```
 
-## Properties
+### FlowEdge Interface
 
-| Property | Type | Default | Attribute | Description |
-|----------|------|---------|-----------|-------------|
-| `nodes` | `FlowNode[]` | `[]` | - | Array of node definitions (set via JS) |
-| `edges` | `FlowEdge[]` | `[]` | - | Array of edge definitions (set via JS) |
-| `snapToGrid` | `boolean` | `true` | `snap-to-grid` | Snap node positions to grid |
-| `gridSize` | `number` | `20` | `grid-size` | Grid spacing in pixels |
-| `zoomEnabled` | `boolean` | `true` | `zoom-enabled` | Enable mouse wheel zoom |
-| `panEnabled` | `boolean` | `true` | `pan-enabled` | Enable background pan |
-| `minimap` | `boolean` | `true` | `minimap` | Show minimap overview |
-| `editable` | `boolean` | `true` | `editable` | Allow drawing new edges |
+```typescript
+interface FlowEdge {
+  id: string;
+  source: string;          // Source node id
+  target: string;          // Target node id
+  sourcePort?: string;     // Source port id
+  targetPort?: string;     // Target port id
+  label?: string;          // Edge label (shown at midpoint)
+  color?: string;          // Custom stroke color
+  animated?: boolean;      // Dashed animated stroke
+}
+```
 
 ## Methods
 
-| Method | Description |
-|--------|-------------|
-| `addNode(node)` | Add a node to the canvas |
-| `removeNode(id)` | Remove a node and its connected edges |
-| `addEdge(edge)` | Add an edge between two ports |
-| `removeEdge(id)` | Remove an edge |
-| `fitView()` | Auto-zoom to fit all nodes in view |
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `addNode(node)` | `node: FlowNode` | Add a node to the canvas |
+| `removeNode(id)` | `id: string` | Remove a node and its connected edges |
+| `addEdge(edge)` | `edge: FlowEdge` | Add an edge between two ports |
+| `removeEdge(id)` | `id: string` | Remove an edge |
+| `fitView()` | -- | Auto-zoom to fit all nodes in view |
 
 ## Events
 
 | Event | Detail | Description |
 |-------|--------|-------------|
-| `node-drag` | `{ node, x, y }` | Node was dragged to new position |
-| `node-select` | `{ node }` | Node selected (null when deselected) |
-| `edge-connect` | `{ edge }` | New edge created by dragging between ports |
-| `edge-disconnect` | `{ edge }` | Edge removed |
-| `canvas-click` | `{ x, y }` | Background canvas clicked |
-
-## CSS Custom Properties
-
-The component uses standard snice theme tokens with fallbacks. Override with custom properties on the host element.
+| `node-drag` | `{ node: FlowNode, x: number, y: number }` | Node was dragged to new position |
+| `node-select` | `{ node: FlowNode \| null }` | Node selected (null when deselected) |
+| `edge-connect` | `{ edge: FlowEdge }` | New edge created by dragging between ports |
+| `edge-disconnect` | `{ edge: FlowEdge }` | Edge removed |
+| `canvas-click` | `{ x: number, y: number }` | Background canvas clicked |
 
 ## CSS Parts
 
-Style internal elements from outside the shadow DOM using `::part()`.
-
-| Part | Element | Description |
-|------|---------|-------------|
-| `base` | `<div>` | Outer flow container |
-| `canvas` | `<svg>` | SVG layer for edges and connections |
-| `nodes` | `<div>` | Container for all node elements |
-| `minimap` | `<div>` | Minimap overview panel |
+| Part | Description |
+|------|-------------|
+| `base` | Outer flow container |
+| `canvas` | SVG layer for edges and connections |
+| `nodes` | Container for all node elements |
+| `minimap` | Minimap overview panel |
 
 ```css
 snice-flow::part(base) {
@@ -159,7 +187,6 @@ flow.edges = [
 ### Programmatic API
 
 ```javascript
-// Add nodes and edges dynamically
 flow.addNode({
   id: 'new-node', x: 200, y: 200, label: 'New Node',
   inputs: [{ id: 'in', label: 'In' }],
@@ -171,55 +198,13 @@ flow.addEdge({
   sourcePort: 'out', targetPort: 'in',
 });
 
-// Remove
 flow.removeNode('new-node'); // also removes connected edges
 flow.removeEdge('new-edge');
 
-// Fit all nodes into view
 flow.fitView();
 ```
 
-### Drawing Edges
-
-Users can create connections by clicking and dragging from a port dot on one node to a port dot on another node. A preview bezier curve shows while dragging.
-
-## Types
-
-```typescript
-interface FlowNode {
-  id: string;
-  x: number;
-  y: number;
-  type?: string;                    // Shown as small label above title
-  data?: Record<string, unknown>;   // Custom data payload
-  label?: string;                   // Node title
-  width?: number;                   // Default: 160
-  height?: number;                  // Default: 80
-  inputs?: FlowPort[];              // Input ports (left side)
-  outputs?: FlowPort[];             // Output ports (right side)
-  color?: string;                   // Header background color
-  selected?: boolean;
-}
-
-interface FlowPort {
-  id: string;
-  label?: string;
-  type?: string;
-}
-
-interface FlowEdge {
-  id: string;
-  source: string;          // Source node id
-  target: string;          // Target node id
-  sourcePort?: string;     // Source port id
-  targetPort?: string;     // Target port id
-  label?: string;          // Edge label (shown at midpoint)
-  color?: string;          // Custom stroke color
-  animated?: boolean;      // Dashed animated stroke
-}
-```
-
-## Interaction
+### Interaction
 
 - **Drag nodes**: Click and drag a node to move it. Snaps to grid if enabled.
 - **Draw edges**: Click and drag from a port dot to another port dot.