snice 4.27.0 → 4.29.0

package/docs/ai/components/file-upload.md

@@ -1,12 +1,12 @@
 # snice-file-upload
 
-File upload with drag-and-drop and preview.
+File upload with drag-and-drop, preview, and form association.
 
 ## Properties
 
 ```typescript
-variant: 'outlined'|'filled' = 'outlined';
 size: 'small'|'medium'|'large' = 'medium';
+variant: 'outlined'|'filled' = 'outlined';
 accept: string = '';
 multiple: boolean = false;
 disabled: boolean = false;
@@ -20,13 +20,18 @@ maxFiles: number = -1;         // attribute: max-files
 name: string = '';
 dragDrop: boolean = true;      // attribute: drag-drop
 showPreview: boolean = true;   // attribute: show-preview
-files: FileList | null;
+files: FileList | null;        // read-only
 ```
 
 ## Methods
 
 - `clear()` - Clear all files
-- `removeFile(index)` - Remove file by index
+- `removeFile(index: number)` - Remove file by index
+
+## Events
+
+- `file-upload-change` → `{ files: File[], fileUpload }`
+- `file-upload-error` → `{ message: string, fileUpload }`
 
 ## CSS Parts
 
@@ -36,66 +41,25 @@ files: FileList | null;
 - `error-text` - Error text element
 - `helper-text` - Helper text element
 
-## Events
-
-- `file-upload-change` → `{ files, fileUpload }`
-- `file-upload-error` → `{ message, fileUpload }`
+## Basic Usage
 
-## Usage
+```typescript
+import 'snice/components/file-upload/snice-file-upload';
+```
 
 ```html
-<!-- Basic -->
 <snice-file-upload label="Upload File"></snice-file-upload>
-
-<!-- Multiple files -->
 <snice-file-upload multiple label="Upload Files"></snice-file-upload>
-
-<!-- File type restrictions -->
 <snice-file-upload accept="image/*" label="Images only"></snice-file-upload>
-<snice-file-upload accept=".pdf,.doc,.docx"></snice-file-upload>
-
-<!-- Size limit (5MB) -->
 <snice-file-upload max-size="5242880"></snice-file-upload>
-
-<!-- File count limit -->
 <snice-file-upload multiple max-files="5"></snice-file-upload>
-
-<!-- No drag-drop -->
 <snice-file-upload drag-drop="false"></snice-file-upload>
-
-<!-- No preview -->
-<snice-file-upload show-preview="false"></snice-file-upload>
-
-<!-- Variants -->
-<snice-file-upload variant="outlined"></snice-file-upload>
-<snice-file-upload variant="filled"></snice-file-upload>
-
-<!-- Sizes -->
-<snice-file-upload size="small"></snice-file-upload>
-<snice-file-upload size="medium"></snice-file-upload>
-<snice-file-upload size="large"></snice-file-upload>
-
-<!-- Events -->
-<snice-file-upload></snice-file-upload>
+<snice-file-upload variant="filled" size="small"></snice-file-upload>
 ```
 
 ```typescript
-upload.addEventListener('file-upload-change', (e) => {
-  console.log('Files:', e.detail.files);
-});
-upload.addEventListener('file-upload-error', (e) => {
-  console.error('Error:', e.detail.message);
-});
+upload.addEventListener('file-upload-change', e => console.log(e.detail.files));
+upload.addEventListener('file-upload-error', e => console.error(e.detail.message));
 ```
 
-## Features
-
-- Form-associated custom element
-- Drag-and-drop support
-- Image preview
-- File type filtering
-- Size validation
-- File count limits
-- Multiple file selection
-- 2 variants, 3 sizes
-- Accessible
+Form-associated custom element. Works with native `<form>` and `FormData`.

package/docs/ai/components/flip-card.md

@@ -1,35 +1,29 @@
 # snice-flip-card
 
-3D card flip component with front/back faces, horizontal/vertical flip direction, and click or programmatic control.
+3D card flip component with front/back faces, horizontal/vertical direction, click or programmatic control.
 
 ## Properties
 
-```ts
-flipped: boolean = false                 // attr: flipped — Whether back face is showing
-clickToFlip: boolean = true              // attr: click-to-flip — Enable click/keyboard to toggle
-direction: FlipDirection = 'horizontal'  // attr: direction — 'horizontal' | 'vertical'
-duration: number = 600                   // attr: duration — Flip animation duration in ms
+```typescript
+flipped: boolean = false;                 // Whether back face is showing
+clickToFlip: boolean = true;              // attribute: click-to-flip
+direction: 'horizontal'|'vertical' = 'horizontal';
+duration: number = 600;                   // Flip animation duration in ms
 ```
 
-## Slots
+## Methods
 
-- `front` — Content for the front face
-- `back` — Content for the back face
+- `flip()` - Toggle between front and back
+- `flipTo(side: 'front'|'back')` - Flip to a specific side
 
 ## Events
 
-- `flip-change` -> `{ flipped: boolean, side: 'front' | 'back' }` — Fires on flip state change
-
-## Methods
-
-- `flip(): void` — Toggle between front and back
-- `flipTo(side: 'front' | 'back'): void` — Flip to a specific side
+- `flip-change` → `{ flipped: boolean, side: 'front'|'back' }`
 
-## CSS Custom Properties
+## Slots
 
-```css
---flip-duration   /* Animation duration, set automatically from duration property */
-```
+- `front` - Content for the front face
+- `back` - Content for the back face
 
 ## CSS Parts
 
@@ -37,12 +31,15 @@ duration: number = 600                   // attr: duration — Flip animation du
 - `front` - The front face container
 - `back` - The back face container
 
-## Keyboard
+## CSS Custom Properties
 
-When `click-to-flip` is enabled:
-- Enter / Space — Toggle flip
+- `--flip-duration` - Animation duration (set automatically from `duration` property)
 
-## Usage
+## Basic Usage
+
+```typescript
+import 'snice/components/flip-card/snice-flip-card';
+```
 
 ```html
 <snice-flip-card direction="horizontal" style="width: 300px; height: 200px;">
@@ -55,3 +52,14 @@ When `click-to-flip` is enabled:
 card.flipTo('back');
 card.addEventListener('flip-change', e => console.log(e.detail.side));
 ```
+
+## Keyboard Navigation
+
+When `click-to-flip` is enabled:
+- Enter / Space - Toggle flip
+
+## Accessibility
+
+- `role="button"` with `aria-label` on the card
+- `tabindex="0"` when click-to-flip is enabled
+- Enter/Space keyboard activation

package/docs/ai/components/flow.md

@@ -7,67 +7,58 @@ Node-based flow/diagram editor with draggable nodes, input/output ports, bezier
 ```typescript
 nodes: FlowNode[] = [];           // attribute: false (set via JS)
 edges: FlowEdge[] = [];           // attribute: false (set via JS)
-snapToGrid: boolean = true;       // attr: snap-to-grid
-gridSize: number = 20;            // attr: grid-size
-zoomEnabled: boolean = true;      // attr: zoom-enabled
-panEnabled: boolean = true;       // attr: pan-enabled
+snapToGrid: boolean = true;       // attribute: snap-to-grid
+gridSize: number = 20;            // attribute: grid-size
+zoomEnabled: boolean = true;      // attribute: zoom-enabled
+panEnabled: boolean = true;       // attribute: pan-enabled
 minimap: boolean = true;
 editable: boolean = true;
 ```
 
-## Types
-
 ```typescript
 interface FlowNode {
-  id: string;
-  x: number;
-  y: number;
-  type?: string;
-  data?: Record<string, unknown>;
-  label?: string;
-  width?: number;        // default: 160
-  height?: number;       // default: 80
-  inputs?: FlowPort[];
-  outputs?: FlowPort[];
-  color?: string;        // header background color
-  selected?: boolean;
-}
-
-interface FlowPort {
-  id: string;
-  label?: string;
-  type?: string;
+  id: string; x: number; y: number;
+  type?: string; data?: Record<string, unknown>; label?: string;
+  width?: number; height?: number; // defaults: 160, 80
+  inputs?: FlowPort[]; outputs?: FlowPort[];
+  color?: string; selected?: boolean;
 }
-
+interface FlowPort { id: string; label?: string; type?: string; }
 interface FlowEdge {
-  id: string;
-  source: string;        // node id
-  target: string;        // node id
-  sourcePort?: string;   // port id
-  targetPort?: string;   // port id
-  label?: string;
-  color?: string;
-  animated?: boolean;    // dashed animated stroke
+  id: string; source: string; target: string;
+  sourcePort?: string; targetPort?: string;
+  label?: string; color?: string; animated?: boolean;
 }
 ```
 
 ## Methods
 
-- `addNode(node: FlowNode): void`
-- `removeNode(id: string): void` - also removes connected edges
-- `addEdge(edge: FlowEdge): void`
-- `removeEdge(id: string): void`
-- `fitView(): void` - auto-zoom to fit all nodes
+- `addNode(node: FlowNode)` - Add a node
+- `removeNode(id: string)` - Remove node and connected edges
+- `addEdge(edge: FlowEdge)` - Add an edge
+- `removeEdge(id: string)` - Remove an edge
+- `fitView()` - Auto-zoom to fit all nodes
 
 ## Events
 
-- `node-drag` -> `{ node: FlowNode, x: number, y: number }`
-- `node-select` -> `{ node: FlowNode | null }`
-- `edge-connect` -> `{ edge: FlowEdge }`
-- `edge-disconnect` -> `{ edge: FlowEdge }`
-- `canvas-click` -> `{ x: number, y: number }`
+- `node-drag` → `{ node: FlowNode, x: number, y: number }`
+- `node-select` → `{ node: FlowNode | null }`
+- `edge-connect` → `{ edge: FlowEdge }`
+- `edge-disconnect` → `{ edge: FlowEdge }`
+- `canvas-click` → `{ x: number, y: number }`
+
+## CSS Parts
+
+- `base` - Outer flow container
+- `canvas` - SVG edge/connection layer
+- `nodes` - Node elements container
+- `minimap` - Minimap overview panel
+
+## Basic Usage
 
-## Usage
+```typescript
+import 'snice/components/flow/snice-flow';
+```
 
 ```html
 <snice-flow id="flow" snap-to-grid minimap style="height:450px"></snice-flow>
@@ -85,25 +76,6 @@ flow.edges = [
   { id: 'e1', source: 'a', target: 'b',
     sourcePort: 'out', targetPort: 'in' },
 ];
+flow.addNode({ id: 'c', x: 500, y: 50, label: 'End', inputs: [{ id: 'in' }] });
+flow.fitView();
 ```
-
-**CSS Parts:**
-- `base` - Outer flow container div
-- `canvas` - SVG edge/connection layer
-- `nodes` - Node elements container
-- `minimap` - Minimap overview panel
-
-## Features
-
-- Draggable nodes with snap-to-grid
-- Input/output ports on nodes
-- Bezier curve edges with arrow markers
-- Draw edges by dragging from port to port
-- Zoom (mouse wheel) and pan (drag background)
-- Node selection with visual highlight
-- Edge selection
-- Minimap showing viewport indicator
-- Dot grid background
-- Animated edge support (dashed flowing)
-- Custom node header colors
-- Responsive via ResizeObserver

package/docs/ai/components/form-builder.md

@@ -5,63 +5,58 @@ Drag-and-drop form designer that outputs JSON schema.
 ## Properties
 
 ```typescript
-schema: FormSchema = { fields: [] };
-mode: 'edit' | 'preview' = 'edit';
-fieldTypes: FormFieldType[] = ['text','number','email','phone','select','date','checkbox','radio','file','signature','section','paragraph']; // attribute: field-types
+schema: FormSchema = { fields: [] };      // attribute: false (set via JS)
+mode: 'edit'|'preview' = 'edit';
+fieldTypes: FormFieldType[] = [...all];    // attribute: false (set via JS)
 ```
 
-## Interfaces
-
 ```typescript
 type FormFieldType = 'text'|'number'|'email'|'phone'|'select'|'date'|'checkbox'|'radio'|'file'|'signature'|'section'|'paragraph';
-
 interface FormFieldOption { label: string; value: string; }
-
 interface FormField {
-  id: string;
-  type: FormFieldType;
-  label: string;
-  placeholder?: string;
-  required?: boolean;
-  options?: FormFieldOption[];
-  defaultValue?: string;
-  helpText?: string;
-  min?: number;
-  max?: number;
-  pattern?: string;
-  accept?: string;
-  content?: string; // paragraph
-  width?: 'full' | 'half';
-}
-
-interface FormSchema {
-  title?: string;
-  description?: string;
-  fields: FormField[];
+  id: string; type: FormFieldType; label: string;
+  placeholder?: string; required?: boolean; options?: FormFieldOption[];
+  defaultValue?: string; helpText?: string; min?: number; max?: number;
+  pattern?: string; accept?: string; content?: string; width?: 'full'|'half';
 }
+interface FormSchema { title?: string; description?: string; fields: FormField[]; }
 ```
 
 ## Methods
 
-```typescript
-getSchema(): FormSchema               // deep copy
-setSchema(schema: FormSchema): void
-addField(type: FormFieldType): void
-removeField(id: string): void
-preview(): void                        // switch to preview mode
-```
+- `getSchema(): FormSchema` - Deep copy of current schema
+- `setSchema(schema: FormSchema)` - Set the form schema
+- `addField(type: FormFieldType)` - Add a new field
+- `removeField(id: string)` - Remove a field
+- `preview()` - Switch to preview mode
 
 ## Events
 
-- `schema-change` -> `{ schema: FormSchema }`
-- `field-add` -> `{ field: FormField }`
-- `field-remove` -> `{ field: FormField }`
-- `field-reorder` -> `{ oldIndex: number, newIndex: number, field: FormField }`
+- `schema-change` → `{ schema: FormSchema }`
+- `field-add` → `{ field: FormField }`
+- `field-remove` → `{ field: FormField }`
+- `field-reorder` → `{ oldIndex: number, newIndex: number, field: FormField }`
+
+## CSS Parts
 
-## Usage
+- `base` - Outer form builder container (edit mode)
+- `mode-toggle` - Edit/preview toggle bar
+- `toolbar` - Field type palette sidebar
+- `canvas` - Main field list area
+- `properties` - Field properties panel
+- `preview` - Preview mode container
+
+## Basic Usage
+
+```typescript
+import 'snice/components/form-builder/snice-form-builder';
+```
+
+```html
+<snice-form-builder></snice-form-builder>
+```
 
 ```typescript
-// Set schema
 fb.setSchema({
   title: 'Contact Form',
   fields: [
@@ -73,45 +68,10 @@ fb.setSchema({
     ]}
   ]
 });
-
-// Add/remove
 fb.addField('text');
 fb.removeField('name');
-
-// Get schema
 const schema = fb.getSchema();
-
-// Preview
 fb.preview();
-
-// Events
 fb.addEventListener('schema-change', e => console.log(e.detail.schema));
-```
-
-```html
-<!-- Limit field types -->
-<snice-form-builder></snice-form-builder>
-```
-
-```typescript
 fb.fieldTypes = ['text', 'email', 'select', 'checkbox'];
 ```
-
-**CSS Parts:**
-- `base` - Outer form builder container (edit mode)
-- `mode-toggle` - Edit/preview toggle bar
-- `toolbar` - Field type palette sidebar
-- `canvas` - Main field list area
-- `properties` - Field properties panel
-- `preview` - Preview mode container
-
-## Features
-
-- Drag from palette to add fields
-- Click to edit field properties
-- Drag to reorder fields
-- Duplicate/delete fields
-- Edit/preview mode toggle
-- Section headers and paragraphs
-- Customizable field types
-- JSON schema output

package/docs/ai/components/form-layout.md

@@ -5,9 +5,9 @@ Structured grid layout for forms with label/field alignment and responsive colum
 ## Properties
 
 ```typescript
-columns: number = 1;                                      // Number of columns
-labelPosition: 'top'|'left'|'right' = 'top';              // attribute: label-position
-labelWidth: string = '8rem';                               // attribute: label-width, width when labels left/right
+columns: number = 1;
+labelPosition: 'top'|'left'|'right' = 'top';    // attribute: label-position
+labelWidth: string = '8rem';                       // attribute: label-width
 gap: 'small'|'medium'|'large' = 'medium';
 variant: 'default'|'compact'|'inline' = 'default';
 ```
@@ -16,57 +16,47 @@ variant: 'default'|'compact'|'inline' = 'default';
 
 - `(default)` - Form fields (inputs, selects, textareas, etc.)
 
-## Events
-
-None — this is a layout-only component.
-
 ## CSS Parts
 
 - `base` - Root layout container
 
 ## CSS Custom Properties
 
-- `--form-columns` - Number of grid columns (set automatically from `columns` prop)
+- `--form-columns` - Number of grid columns (set from `columns` prop)
 - `--form-label-width` - Label width for left/right positions (set from `label-width` prop)
 
-## Usage
+## Basic Usage
+
+```typescript
+import 'snice/components/form-layout/snice-form-layout';
+```
 
 ```html
-<!-- Single column -->
 <snice-form-layout>
   <snice-input label="Name"></snice-input>
   <snice-input label="Email"></snice-input>
 </snice-form-layout>
 
-<!-- Two columns -->
 <snice-form-layout columns="2">
   <snice-input label="First Name"></snice-input>
   <snice-input label="Last Name"></snice-input>
 </snice-form-layout>
 
-<!-- Labels on left -->
 <snice-form-layout label-position="left" label-width="10rem">
   <snice-input label="Username"></snice-input>
   <snice-input label="Password" type="password"></snice-input>
 </snice-form-layout>
 
-<!-- Compact with small gap -->
 <snice-form-layout variant="compact" gap="small" columns="3">
   <snice-input label="City"></snice-input>
   <snice-input label="State"></snice-input>
   <snice-input label="Zip"></snice-input>
 </snice-form-layout>
 
-<!-- Inline variant (flex row) -->
 <snice-form-layout variant="inline">
   <snice-input label="Search"></snice-input>
   <snice-select label="Category"></snice-select>
 </snice-form-layout>
 ```
 
-## Features
-
-- Responsive: collapses to single column on mobile (<640px)
-- Labels go top on mobile regardless of `label-position`
-- Three gap sizes, three layout variants
-- CSS custom properties exposed for slotted children label positioning
+No events -- layout-only component. Responsive: collapses to single column on mobile (<640px).

package/docs/ai/components/funnel.md

@@ -5,39 +5,42 @@ SVG-based funnel chart for conversion tracking and pipeline visualization.
 ## Properties
 
 ```typescript
-data: FunnelStage[] = [];           // Array of { label, value, color? }
+data: FunnelStage[] = [];                    // attribute: false (set via JS)
 variant: 'default'|'gradient' = 'default';
 orientation: 'vertical'|'horizontal' = 'vertical';
-showLabels: boolean = true;          // attribute: show-labels
-showValues: boolean = true;          // attribute: show-values
-showPercentages: boolean = true;     // attribute: show-percentages
+showLabels: boolean = true;                  // attribute: show-labels
+showValues: boolean = true;                  // attribute: show-values
+showPercentages: boolean = true;             // attribute: show-percentages
 animation: boolean = false;
 ```
 
-## Types
-
 ```typescript
-interface FunnelStage {
-  label: string;
-  value: number;
-  color?: string;
-}
+interface FunnelStage { label: string; value: number; color?: string; }
 ```
 
 ## Methods
 
-- `setStages(stages: FunnelStage[])` — replace all stages
-- `exportImage(format?: 'png'|'svg')` — returns data URL string
+- `setStages(stages: FunnelStage[])` - Replace all stages
+- `exportImage(format?: 'png'|'svg'): string` - Returns data URL
 
 ## Events
 
-- `funnel-click` → `{ stage: FunnelStage; index: number }` — stage clicked
-- `funnel-hover` → `{ stage: FunnelStage; index: number }` — stage hovered
+- `funnel-click` → `{ stage: FunnelStage, index: number }`
+- `funnel-hover` → `{ stage: FunnelStage, index: number }`
+
+## CSS Parts
+
+- `base` - Outer funnel container
+- `chart` - SVG chart rendering area
+- `tooltip` - Hover tooltip element
+
+## Basic Usage
 
-## Usage
+```typescript
+import 'snice/components/funnel/snice-funnel';
+```
 
 ```html
-<!-- Basic -->
 <snice-funnel></snice-funnel>
 ```
 
@@ -50,41 +53,23 @@ funnel.data = [
 ```
 
 ```html
-<!-- Gradient variant -->
 <snice-funnel variant="gradient"></snice-funnel>
-
-<!-- Horizontal -->
 <snice-funnel orientation="horizontal"></snice-funnel>
-
-<!-- Custom colors -->
-data = [
-  { label: 'A', value: 100, color: 'rgb(37 99 235)' },
-  { label: 'B', value: 50, color: 'rgb(22 163 74)' },
-]
-
-<!-- Hide elements -->
 <snice-funnel show-labels="false" show-values="false"></snice-funnel>
-
-<!-- With animation -->
 <snice-funnel animation></snice-funnel>
 ```
 
-**CSS Parts:**
-- `base` - Outer funnel container div
-- `chart` - SVG chart rendering area
-- `tooltip` - Hover tooltip element
+```typescript
+funnel.addEventListener('funnel-click', e => console.log(e.detail.stage));
+const svgUrl = funnel.exportImage('svg');
+```
+
+## Keyboard Navigation
+
+- Enter/Space - Activate focused stage
+- Tab - Navigate between stages
+
+## Accessibility
 
-## Features
-
-- SVG trapezoid shapes per stage
-- Vertical (default) and horizontal orientation
-- 2 variants: default (distinct colors), gradient (opacity fade)
-- Custom color per stage, falls back to theme palette
-- Labels, values (auto-formatted K/M), percentages
-- Tooltip on hover
-- Click + hover events
-- Keyboard accessible (Enter/Space)
-- ARIA: role="img" on SVG, role="button" + aria-label on stages
-- CSS animation on initial render
-- Responsive via SVG viewBox
-- Works without theme (CSS fallbacks)
+- SVG: `role="img"` with `aria-label="Funnel chart"`
+- Stages: `role="button"`, `tabindex="0"`, descriptive `aria-label`