snice 4.27.0 → 4.29.0

package/docs/components/form-builder.md

@@ -1,30 +1,73 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/form-builder.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/form-builder.md -->
 
 # Form Builder
-`<snice-form-builder>`
 
 Drag-and-drop form designer that outputs a JSON schema describing the form structure.
 
-## 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 |
+|----------|------|---------|-------------|
+| `schema` | `FormSchema` | `{ fields: [] }` | JSON schema (input/output, set via JS) |
+| `mode` | `'edit' \| 'preview'` | `'edit'` | Current mode |
+| `fieldTypes` | `FormFieldType[]` | all types | Available field types in the palette (set via JS) |
+
+### FormSchema Interface
 
-**ESM (bundler)**
 ```typescript
-import 'snice/components/form-builder/snice-form-builder';
+interface FormSchema {
+  title?: string;
+  description?: string;
+  fields: FormField[];
+}
 ```
 
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-form-builder.min.js"></script>
+### FormField Interface
+
+```typescript
+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;       // For paragraph fields
+  width?: 'full' | 'half';
+}
 ```
 
-## Properties
+### FormFieldType
+
+```typescript
+type FormFieldType =
+  | 'text' | 'number' | 'email' | 'phone'
+  | 'select' | 'date' | 'checkbox' | 'radio'
+  | 'file' | 'signature' | 'section' | 'paragraph';
+```
+
+### FormFieldOption Interface
 
-| Property | Attribute | Type | Default | Description |
-|----------|-----------|------|---------|-------------|
-| `schema` | `schema` | `FormSchema` | `{ fields: [] }` | JSON schema (input/output) |
-| `mode` | `mode` | `'edit' \| 'preview'` | `'edit'` | Current mode |
-| `fieldTypes` | `field-types` | `FormFieldType[]` | all types | Available field types in the palette |
+```typescript
+interface FormFieldOption {
+  label: string;
+  value: string;
+}
+```
 
 ## Methods
 
@@ -91,8 +134,6 @@ fb.setSchema({
 
 ### Adding Fields Programmatically
 
-Use `addField()` to append a new field to the form.
-
 ```javascript
 fb.addField('text');
 fb.addField('email');
@@ -101,8 +142,6 @@ fb.addField('select');
 
 ### Preview Mode
 
-Set the `mode` attribute to `"preview"` or call `preview()` to test the form.
-
 ```html
 <snice-form-builder mode="preview"></snice-form-builder>
 ```
@@ -114,7 +153,7 @@ fb.mode = 'edit'; // Switch back to edit mode
 
 ### Custom Field Types
 
-Use the `field-types` property to limit available field types.
+Use the `fieldTypes` property to limit available field types.
 
 ```javascript
 fb.fieldTypes = ['text', 'email', 'select', 'checkbox'];
@@ -122,12 +161,9 @@ fb.fieldTypes = ['text', 'email', 'select', 'checkbox'];
 
 ### Listening to Changes
 
-React to schema changes as the user designs the form.
-
 ```javascript
 fb.addEventListener('schema-change', (e) => {
   const schema = e.detail.schema;
-  // Save to backend or localStorage
   localStorage.setItem('form-draft', JSON.stringify(schema));
 });
 
@@ -167,76 +203,13 @@ fb.setSchema({
 
 ### Getting the Schema
 
-Retrieve the current schema as a plain object.
-
 ```javascript
 const schema = fb.getSchema();
 console.log(JSON.stringify(schema, null, 2));
 
-// Send to backend
 fetch('/api/forms', {
   method: 'POST',
   headers: { 'Content-Type': 'application/json' },
   body: JSON.stringify(schema)
 });
 ```
-
-## FormSchema Interface
-
-```typescript
-interface FormSchema {
-  title?: string;
-  description?: string;
-  fields: FormField[];
-}
-```
-
-## FormField Interface
-
-```typescript
-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;       // For paragraph fields
-  width?: 'full' | 'half';
-}
-```
-
-## FormFieldType
-
-```typescript
-type FormFieldType =
-  | 'text' | 'number' | 'email' | 'phone'
-  | 'select' | 'date' | 'checkbox' | 'radio'
-  | 'file' | 'signature' | 'section' | 'paragraph';
-```
-
-## FormFieldOption Interface
-
-```typescript
-interface FormFieldOption {
-  label: string;
-  value: string;
-}
-```
-
-## Features
-
-- Drag fields from the palette into the canvas to add them
-- Click fields to select and edit properties in the side panel
-- Drag to reorder fields within the canvas
-- Duplicate or delete fields with action buttons
-- Toggle between edit and preview modes
-- Section headers and paragraphs for form organization
-- Customizable available field types
-- JSON schema output for form persistence and rendering

package/docs/components/form-layout.md

@@ -1,32 +1,26 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/form-layout.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/form-layout.md -->
 
 # Form Layout
-`<snice-form-layout>`
 
 Structured grid layout for forms with label/field alignment and responsive columns.
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/form-layout/snice-form-layout';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-form-layout.min.js"></script>
-```
+## Table of Contents
+- [Properties](#properties)
+- [Slots](#slots)
+- [CSS Parts](#css-parts)
+- [CSS Custom Properties](#css-custom-properties)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
 
 ## Properties
 
-| Property | Attribute | Type | Default | Description |
-|----------|-----------|------|---------|-------------|
-| `columns` | `columns` | `number` | `1` | Number of grid columns |
-| `labelPosition` | `label-position` | `'top' \| 'left' \| 'right'` | `'top'` | Label placement relative to fields |
-| `labelWidth` | `label-width` | `string` | `'8rem'` | Label width when position is left/right |
-| `gap` | `gap` | `'small' \| 'medium' \| 'large'` | `'medium'` | Spacing between fields |
-| `variant` | `variant` | `'default' \| 'compact' \| 'inline'` | `'default'` | Layout variant |
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `columns` | `number` | `1` | Number of grid columns |
+| `labelPosition` (attr: `label-position`) | `'top' \| 'left' \| 'right'` | `'top'` | Label placement relative to fields |
+| `labelWidth` (attr: `label-width`) | `string` | `'8rem'` | Label width when position is left/right |
+| `gap` | `'small' \| 'medium' \| 'large'` | `'medium'` | Spacing between fields |
+| `variant` | `'default' \| 'compact' \| 'inline'` | `'default'` | Layout variant |
 
 ## Slots
 
@@ -34,6 +28,12 @@ import 'snice/components/form-layout/snice-form-layout';
 |------|-------------|
 | (default) | Form fields (inputs, selects, textareas, etc.) |
 
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `base` | The form layout grid container |
+
 ## CSS Custom Properties
 
 | Property | Description | Default |
@@ -41,12 +41,6 @@ import 'snice/components/form-layout/snice-form-layout';
 | `--form-columns` | Number of grid columns (set via `columns` prop) | `1` |
 | `--form-label-width` | Width of labels in left/right mode (set via `label-width` prop) | `8rem` |
 
-## CSS Parts
-
-| Part | Description |
-|------|-------------|
-| `base` | The form layout grid container |
-
 ## Basic Usage
 
 ```typescript
@@ -146,7 +140,3 @@ Use CSS `grid-column` on slotted children to span multiple columns.
   <snice-textarea label="Bio" style="grid-column: 1 / -1;"></snice-textarea>
 </snice-form-layout>
 ```
-
-## Responsive Behavior
-
-The form layout automatically collapses to a single column on screens smaller than 640px. When `label-position` is set to `left` or `right`, labels will switch to `top` position on mobile for better readability.

package/docs/components/funnel.md

@@ -1,6 +1,6 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/funnel.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/funnel.md -->
 
-# Funnel Component
+# Funnel
 
 The funnel component renders an SVG-based funnel/conversion chart, ideal for visualizing pipeline stages, conversion funnels, and drop-off analysis. Each stage is rendered as a trapezoid shape that narrows proportionally to its value.
 
@@ -11,19 +11,19 @@ The funnel component renders an SVG-based funnel/conversion chart, ideal for vis
 - [CSS Parts](#css-parts)
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
+- [Keyboard Navigation](#keyboard-navigation)
 - [Accessibility](#accessibility)
-- [Browser Support](#browser-support)
 
 ## Properties
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `data` | `FunnelStage[]` | `[]` | Array of stage objects with label, value, and optional color |
+| `data` | `FunnelStage[]` | `[]` | Array of stage objects with label, value, and optional color (set via JS) |
 | `variant` | `'default' \| 'gradient'` | `'default'` | Color variant - default uses distinct colors, gradient uses opacity fade |
 | `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Funnel layout direction |
-| `show-labels` | `boolean` | `true` | Whether to display stage labels |
-| `show-values` | `boolean` | `true` | Whether to display stage values |
-| `show-percentages` | `boolean` | `true` | Whether to display conversion percentages |
+| `showLabels` (attr: `show-labels`) | `boolean` | `true` | Whether to display stage labels |
+| `showValues` (attr: `show-values`) | `boolean` | `true` | Whether to display stage values |
+| `showPercentages` (attr: `show-percentages`) | `boolean` | `true` | Whether to display conversion percentages |
 | `animation` | `boolean` | `false` | Whether to animate stages on initial render |
 
 ### FunnelStage Interface
@@ -71,13 +71,11 @@ funnel.addEventListener('funnel-click', (e) => {
 
 ## CSS Parts
 
-Style internal elements from outside the shadow DOM using `::part()`.
-
-| Part | Element | Description |
-|------|---------|-------------|
-| `base` | `<div>` | Outer funnel container |
-| `chart` | `<div>` | SVG chart rendering area |
-| `tooltip` | `<div>` | Hover tooltip element |
+| Part | Description |
+|------|-------------|
+| `base` | Outer funnel container |
+| `chart` | SVG chart rendering area |
+| `tooltip` | Hover tooltip element |
 
 ```css
 snice-funnel::part(base) {
@@ -91,12 +89,14 @@ snice-funnel::part(tooltip) {
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/funnel/snice-funnel';
+```
+
 ```html
 <snice-funnel id="my-funnel"></snice-funnel>
 
 <script type="module">
-  import 'snice/components/funnel/snice-funnel';
-
   const funnel = document.getElementById('my-funnel');
   funnel.data = [
     { label: 'Visitors', value: 10000 },
@@ -186,6 +186,11 @@ The gradient variant uses decreasing opacity of the primary color for a smoother
 </script>
 ```
 
+## Keyboard Navigation
+
+- **Enter** / **Space** -- Activate a focused stage (fires `funnel-click`)
+- **Tab** -- Navigate between stages
+
 ## Accessibility
 
 - **ARIA role**: The SVG has `role="img"` with `aria-label="Funnel chart"`
@@ -193,9 +198,3 @@ The gradient variant uses decreasing opacity of the primary color for a smoother
 - **ARIA labels**: Each stage has a descriptive `aria-label` including the label, value, and percentage
 - **Keyboard support**: Stages can be activated with Enter or Space keys
 - **Focus styles**: Visible focus ring on keyboard navigation
-- **Color contrast**: Default colors meet WCAG AA standards
-
-## Browser Support
-
-- Modern browsers (Chrome, Firefox, Safari, Edge)
-- Requires Custom Elements v1 and Shadow DOM support

package/docs/components/gantt.md

@@ -1,4 +1,4 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/gantt.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/gantt.md -->
 
 # Gantt Component
 
@@ -77,14 +77,14 @@ snice-gantt::part(task-list) {
 
 ## Basic Usage
 
-```html
-<snice-gantt></snice-gantt>
-```
-
 ```typescript
 import 'snice/components/gantt/snice-gantt';
 ```
 
+```html
+<snice-gantt></snice-gantt>
+```
+
 ## Examples
 
 ### Basic Project Timeline

package/docs/components/gauge.md

@@ -1,4 +1,4 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/gauge.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/gauge.md -->
 
 # Gauge Component
 
@@ -10,8 +10,6 @@ The gauge component renders an SVG-based semicircle gauge/meter chart, ideal for
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
 - [Accessibility](#accessibility)
-- [Browser Support](#browser-support)
-- [Variant Colors](#variant-colors)
 
 ## Properties
 
@@ -50,6 +48,10 @@ snice-gauge::part(label) {
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/gauge/snice-gauge';
+```
+
 ```html
 <!-- Simple gauge -->
 <snice-gauge value="75"></snice-gauge>
@@ -58,10 +60,6 @@ snice-gauge::part(label) {
 <snice-gauge value="42" label="CPU Usage"></snice-gauge>
 ```
 
-```typescript
-import 'snice/components/gauge/snice-gauge';
-```
-
 ## Examples
 
 ### Basic Gauge
@@ -172,19 +170,3 @@ import 'snice/components/gauge/snice-gauge';
 - **ARIA label**: Uses the `label` property for `aria-label`, falls back to "Gauge: {value}"
 - **Color contrast**: All variant colors meet WCAG AA standards against their backgrounds
 - **No motion sensitivity**: Arc animation uses CSS transitions which respect `prefers-reduced-motion`
-
-## Browser Support
-
-- Modern browsers (Chrome, Firefox, Safari, Edge)
-- Requires Custom Elements v1 and Shadow DOM support
-
-## Variant Colors
-
-| Variant | Color Scheme | Use Case |
-|---------|-------------|----------|
-| `default` | Gray | Neutral metrics |
-| `primary` | Blue | Primary metrics, general data |
-| `success` | Green | Positive values, health checks |
-| `warning` | Orange | Attention needed, thresholds |
-| `error` | Red | Critical values, alerts |
-| `info` | Light blue | Informational data |

package/docs/components/heatmap.md

@@ -1,4 +1,4 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/heatmap.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/heatmap.md -->
 
 # Heatmap Component
 
@@ -10,21 +10,18 @@ The heatmap component displays a GitHub-style contribution calendar heatmap. It
 - [CSS Parts](#css-parts)
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
-- [Intensity Levels](#intensity-levels)
-- [Color Schemes](#color-schemes)
 - [Accessibility](#accessibility)
-- [Browser Support](#browser-support)
 
 ## Properties
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
 | `data` | `HeatmapDataPoint[]` | `[]` | Array of data points with date and value |
-| `color-scheme` | `'green' \| 'blue' \| 'purple' \| 'orange' \| 'red'` | `'green'` | Color scheme for intensity levels |
-| `show-labels` | `boolean` | `true` | Show day and month labels |
-| `cell-size` | `number` | `12` | Cell size in pixels |
-| `cell-gap` | `number` | `3` | Gap between cells in pixels |
-| `show-tooltip` | `boolean` | `true` | Show tooltip on cell hover |
+| `colorScheme` (attr: `color-scheme`) | `'green' \| 'blue' \| 'purple' \| 'orange' \| 'red'` | `'green'` | Color scheme for intensity levels |
+| `showLabels` (attr: `show-labels`) | `boolean` | `true` | Show day and month labels |
+| `cellSize` (attr: `cell-size`) | `number` | `12` | Cell size in pixels |
+| `cellGap` (attr: `cell-gap`) | `number` | `3` | Gap between cells in pixels |
+| `showTooltip` (attr: `show-tooltip`) | `boolean` | `true` | Show tooltip on cell hover |
 | `weeks` | `number` | `52` | Number of weeks to display |
 
 ### HeatmapDataPoint
@@ -38,21 +35,9 @@ interface HeatmapDataPoint {
 
 ## Events
 
-### `cell-click`
-
-Fired when a cell is clicked.
-
-```typescript
-heatmap.addEventListener('cell-click', (e: CustomEvent) => {
-  console.log(e.detail.date);  // '2026-01-15'
-  console.log(e.detail.value); // 5
-});
-```
-
-| Detail Property | Type | Description |
-|-----------------|------|-------------|
-| `date` | `string` | ISO date of the clicked cell |
-| `value` | `number` | Value of the clicked cell |
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `cell-click` | `{ date: string, value: number }` | Fired when a cell is clicked |
 
 ## CSS Parts
 
@@ -77,6 +62,10 @@ snice-heatmap::part(tooltip) {
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/heatmap/snice-heatmap';
+```
+
 ```html
 <snice-heatmap id="my-heatmap"></snice-heatmap>
 
@@ -90,10 +79,6 @@ snice-heatmap::part(tooltip) {
 </script>
 ```
 
-```typescript
-import 'snice/components/heatmap/snice-heatmap';
-```
-
 ## Examples
 
 ### Default Green Heatmap
@@ -167,36 +152,9 @@ import 'snice/components/heatmap/snice-heatmap';
 </script>
 ```
 
-## Intensity Levels
-
-Cell colors are calculated based on quartiles of the maximum value in the dataset:
-
-| Level | Range | Description |
-|-------|-------|-------------|
-| 0 | No data | Empty (gray) |
-| 1 | 1-25% of max | Low activity |
-| 2 | 26-50% of max | Medium activity |
-| 3 | 51-75% of max | High activity |
-| 4 | 76-100% of max | Very high activity |
-
-## Color Schemes
-
-| Scheme | Level 1 | Level 2 | Level 3 | Level 4 |
-|--------|---------|---------|---------|---------|
-| `green` | #9be9a8 | #40c463 | #30a14e | #216e39 |
-| `blue` | #9ecae1 | #4292c6 | #2171b5 | #084594 |
-| `purple` | #c9b1e0 | #9b72cf | #7b4fbf | #5a2d91 |
-| `orange` | #fdcc8a | #fc8d59 | #e34a33 | #b30000 |
-| `red` | #fcae91 | #fb6a4a | #de2d26 | #a50f15 |
-
 ## Accessibility
 
 - **ARIA labels**: Each cell has an `aria-label` describing the date and contribution count
 - **Keyboard navigation**: Cells are focusable buttons
 - **Tooltips**: Visual hover feedback with date and value details
 - **Color contrast**: Intensity levels are distinguishable at all levels
-
-## Browser Support
-
-- Modern browsers (Chrome, Firefox, Safari, Edge)
-- Requires Custom Elements v1 and Shadow DOM support

package/docs/components/image.md

@@ -1,4 +1,4 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/image.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/image.md -->
 
 # Image Component
 
@@ -6,9 +6,9 @@ The `<snice-image>` component provides a flexible image display with variants, s
 
 ## Table of Contents
 - [Properties](#properties)
+- [CSS Parts](#css-parts)
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
-- [CSS Parts](#css-parts)
 
 ## Properties
 
@@ -27,8 +27,34 @@ The `<snice-image>` component provides a flexible image display with variants, s
 | `width` | `string` | `''` | Custom width (CSS value) |
 | `height` | `string` | `''` | Custom height (CSS value) |
 
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `container` | Image container div |
+| `image` | The img element |
+| `placeholder` | Placeholder element (shown when loading or no src) |
+
+```css
+snice-image::part(container) {
+  /* Image container */
+}
+
+snice-image::part(image) {
+  /* The img element */
+}
+
+snice-image::part(placeholder) {
+  /* Placeholder element */
+}
+```
+
 ## Basic Usage
 
+```typescript
+import 'snice/components/image/snice-image';
+```
+
 ```html
 <snice-image
   src="https://example.com/image.jpg"
@@ -95,33 +121,3 @@ The `<snice-image>` component provides a flexible image display with variants, s
 <!-- Shows placeholder when no src -->
 <snice-image variant="circle" size="medium"></snice-image>
 ```
-
-## CSS Parts
-
-| Part | Description |
-|------|-------------|
-| `container` | Image container div |
-| `image` | The img element |
-| `placeholder` | Placeholder element (shown when loading or no src) |
-
-```css
-snice-image::part(container) {
-  /* Image container */
-}
-
-snice-image::part(image) {
-  /* The img element */
-}
-
-snice-image::part(placeholder) {
-  /* Placeholder element */
-}
-```
-
-## Notes
-
-- Images are lazy-loaded by default for better performance
-- Placeholder is shown when `src` is empty
-- Fallback image is used when main image fails to load
-- Size presets provide consistent image dimensions
-- Custom width/height override size presets