snice 4.27.0 → 4.29.0

package/docs/ai/components/date-time-picker.md

@@ -1,13 +1,13 @@
 # snice-date-time-picker
 
-Combined date and time picker. Calendar for date, scrollable columns for time.
+Combined date and time picker. Calendar for date, scrollable columns for time. Form-associated.
 
 ## Properties
 
 ```typescript
 value: string = '';                                   // ISO datetime (YYYY-MM-DDTHH:MM or YYYY-MM-DDTHH:MM:SS)
-dateFormat: DateTimePickerDateFormat = 'yyyy-mm-dd';   // attribute: date-format — 'yyyy-mm-dd'|'mm/dd/yyyy'|'dd/mm/yyyy'|'yyyy/mm/dd'|'dd-mm-yyyy'|'mm-dd-yyyy'|'mmmm dd, yyyy'
-timeFormat: '12h'|'24h' = '24h';                      // attribute: time-format
+dateFormat: DateTimePickerDateFormat = 'yyyy-mm-dd';  // attribute: date-format
+timeFormat: '12h'|'24h' = '24h';                     // attribute: time-format
 size: 'small'|'medium'|'large' = 'medium';
 min: string = '';                                     // Min date (YYYY-MM-DD)
 max: string = '';                                     // Max date (YYYY-MM-DD)
@@ -26,6 +26,8 @@ name: string = '';
 variant: 'dropdown'|'inline' = 'dropdown';
 ```
 
+Date formats: `'yyyy-mm-dd'`|`'mm/dd/yyyy'`|`'dd/mm/yyyy'`|`'yyyy/mm/dd'`|`'dd-mm-yyyy'`|`'mm-dd-yyyy'`|`'mmmm dd, yyyy'`
+
 ## Methods
 
 - `open()` - Open panel
@@ -37,36 +39,25 @@ variant: 'dropdown'|'inline' = 'dropdown';
 
 ## Events
 
-- `datetime-change` -> `{ value, date, dateString, timeString, iso, dateTimePicker }`
-- `datetimepicker-focus` -> `{ dateTimePicker }`
-- `datetimepicker-blur` -> `{ dateTimePicker }`
-- `datetimepicker-open` -> `{ dateTimePicker }`
-- `datetimepicker-close` -> `{ dateTimePicker }`
-- `datetimepicker-clear` -> `{ dateTimePicker }`
-
-## Usage
+- `datetime-change` → `{ value, date, dateString, timeString, iso, dateTimePicker }`
+- `datetimepicker-focus` → `{ dateTimePicker }`
+- `datetimepicker-blur` → `{ dateTimePicker }`
+- `datetimepicker-open` → `{ dateTimePicker }`
+- `datetimepicker-close` → `{ dateTimePicker }`
+- `datetimepicker-clear` → `{ dateTimePicker }`
 
-```html
-<!-- Basic -->
-<snice-date-time-picker label="Appointment"></snice-date-time-picker>
+## CSS Parts
 
-<!-- With value -->
-<snice-date-time-picker value="2024-12-25T14:30"></snice-date-time-picker>
+`base`, `label`, `input`, `toggle`, `panel`, `calendar`, `time`, `clear`, `spinner`, `helper-text`, `error-text`
 
-<!-- 12h format -->
-<snice-date-time-picker time-format="12h" value="2024-12-25T14:30"></snice-date-time-picker>
+## Basic Usage
 
-<!-- With seconds -->
+```html
+<snice-date-time-picker label="Appointment"></snice-date-time-picker>
+<snice-date-time-picker value="2024-12-25T14:30" time-format="12h"></snice-date-time-picker>
 <snice-date-time-picker show-seconds value="2024-12-25T14:30:45"></snice-date-time-picker>
-
-<!-- Date constraints -->
-<snice-date-time-picker min="2024-01-01" max="2024-12-31"></snice-date-time-picker>
-
-<!-- Inline (always visible) -->
 <snice-date-time-picker variant="inline" value="2024-06-15T10:00"></snice-date-time-picker>
-
-<!-- Event handling -->
-<snice-date-time-picker id="dtp"></snice-date-time-picker>
+<snice-date-time-picker min="2024-01-01" max="2024-12-31"></snice-date-time-picker>
 ```
 
 ```typescript
@@ -76,24 +67,10 @@ dtp.addEventListener('datetime-change', (e) => {
   console.log('Time:', e.detail.timeString);
 });
 ```
-```
-
-## CSS Parts
-
-`base`, `label`, `input`, `toggle`, `panel`, `calendar`, `time`, `clear`, `spinner`, `helper-text`, `error-text`
 
-## Features
+## Accessibility
 
-- Form-associated custom element
-- Calendar with month navigation + time selector columns side-by-side
-- Year picker (click year in header → 12-year grid, navigate ranges, click to select)
-- Dropdown or inline variant
-- 12h/24h time format with AM/PM toggle
-- Optional seconds selector
-- 3 sizes (small, medium, large)
-- Loading state with spinner
-- Clearable with clear button
-- Min/max date constraints
-- Configurable date display format
-- Constraint Validation API (checkValidity, reportValidity, setCustomValidity)
-- Responsive: stacks vertically on mobile
+- Form-associated with ElementInternals
+- Calendar uses popover="manual"
+- Responsive: stacks vertically on mobile (<480px)
+- Year picker via calendar header year button

package/docs/ai/components/diff.md

@@ -4,23 +4,19 @@ Text diff viewer with unified and split (side-by-side) modes, line numbers, coll
 
 ## Properties
 
-```ts
-oldText: string = ''             // attr: old-text — Original text
-newText: string = ''             // attr: new-text — Modified text
-language: string = ''            // attr: language — Language hint (for future syntax highlighting)
-mode: DiffMode = 'unified'      // attr: mode — 'unified' | 'split'
-lineNumbers: boolean = true      // attr: line-numbers — Show line number gutters
-contextLines: number = 3         // attr: context-lines — Unchanged lines shown around changes
-markers: boolean = true          // attr: markers — Show +/- markers column
+```typescript
+oldText: string = '';            // attr: old-text
+newText: string = '';            // attr: new-text
+language: string = '';           // Language hint (future syntax highlighting)
+mode: 'unified'|'split' = 'unified';
+lineNumbers: boolean = true;     // attr: line-numbers
+contextLines: number = 3;        // attr: context-lines
+markers: boolean = true;         // Show +/- markers column
 ```
 
-## Events
-
-- `diff-computed` -> `{ hunks: DiffHunk[], additions: number, deletions: number }` — Fires after diff is calculated
-
-## Types
+### Types
 
-```ts
+```typescript
 interface DiffLine {
   type: 'added' | 'removed' | 'unchanged';
   oldLine: number | null;
@@ -34,28 +30,24 @@ interface DiffHunk {
 }
 ```
 
-## CSS Custom Properties
+## Events
 
-```css
---diff-add-bg              /* Added line background */
---diff-remove-bg           /* Removed line background */
---diff-add-word-bg         /* Word-level added highlight */
---diff-remove-word-bg      /* Word-level removed highlight */
-```
+- `diff-computed` → `{ hunks: DiffHunk[], additions: number, deletions: number }`
 
-**CSS Parts:**
-- `base` - Outer diff container div
-- `header` - Header with stats and mode toggle buttons
-- `content` - Diff content area containing the diff table(s)
+## CSS Custom Properties
 
-## Behavior
+- `--diff-add-bg` - Added line background
+- `--diff-remove-bg` - Removed line background
+- `--diff-add-word-bg` - Word-level added highlight
+- `--diff-remove-word-bg` - Word-level removed highlight
 
-- LCS-based diff algorithm computes on `oldText`/`newText`/`contextLines` change
-- Unchanged sections beyond context are collapsed; click to expand
-- Header shows +N/-N stats and unified/split toggle buttons
-- Dark mode support via `[data-theme="dark"]` or `prefers-color-scheme: dark`
+## CSS Parts
+
+- `base` - Outer diff container
+- `header` - Header with stats and mode toggle buttons
+- `content` - Diff content area with diff table(s)
 
-## Usage
+## Basic Usage
 
 ```html
 <snice-diff old-text="hello world" new-text="hello there" mode="unified" context-lines="3"></snice-diff>
@@ -68,3 +60,10 @@ diff.addEventListener('diff-computed', e => {
   console.log(`+${e.detail.additions} -${e.detail.deletions}`);
 });
 ```
+
+## Accessibility
+
+- LCS-based diff computed on oldText/newText/contextLines change
+- Unchanged sections beyond context are collapsed; click to expand
+- Header shows +N/-N stats and unified/split toggle
+- Dark mode via `[data-theme="dark"]` or `prefers-color-scheme: dark`

package/docs/ai/components/divider.md

@@ -1,6 +1,6 @@
 # snice-divider
 
-Separator line with optional text.
+Separator line with optional text label.
 
 ## Properties
 
@@ -15,57 +15,27 @@ color: string = '';
 capped: boolean = false;
 ```
 
-## Usage
+## CSS Custom Properties
 
-```html
-<!-- Basic -->
-<snice-divider></snice-divider>
-
-<!-- With text -->
-<snice-divider text="OR"></snice-divider>
-
-<!-- Text alignment -->
-<snice-divider text="Start" align="start"></snice-divider>
-<snice-divider text="Center" align="center"></snice-divider>
-<snice-divider text="End" align="end"></snice-divider>
-
-<!-- Variants -->
-<snice-divider variant="solid"></snice-divider>
-<snice-divider variant="dashed"></snice-divider>
-<snice-divider variant="dotted"></snice-divider>
-
-<!-- Spacing -->
-<snice-divider spacing="none"></snice-divider>
-<snice-divider spacing="small"></snice-divider>
-<snice-divider spacing="medium"></snice-divider>
-<snice-divider spacing="large"></snice-divider>
-
-<!-- Vertical -->
-<div style="display: flex; height: 50px;">
-  <span>Left</span>
-  <snice-divider orientation="vertical"></snice-divider>
-  <span>Right</span>
-</div>
+- `--divider-color` - Line color (default: `var(--snice-color-border)`)
+- `--divider-thickness` - Line thickness (default: `1px`)
+- `--divider-text-bg` - Text label background
+- `--divider-text-padding` - Text label padding (default: `0 1rem`)
+- `--divider-text-gap` - Gap around text label (default: `1rem`)
 
-<!-- Custom color -->
-<snice-divider color="#3b82f6"></snice-divider>
-
-<!-- Capped (rounded ends) -->
-<snice-divider capped></snice-divider>
-```
+## CSS Parts
 
-**CSS Parts:**
 - `base` - Outer divider container
 - `line` - The divider line(s)
 - `text` - Optional text label
 
-## Features
+## Basic Usage
 
-- Horizontal or vertical
-- 3 line styles (solid/dashed/dotted)
-- Optional text label
-- Text alignment (start/center/end)
-- 4 spacing options
-- Custom color
-- Capped ends
-- Custom text background
+```html
+<snice-divider></snice-divider>
+<snice-divider text="OR"></snice-divider>
+<snice-divider text="Start" align="start"></snice-divider>
+<snice-divider variant="dashed" capped></snice-divider>
+<snice-divider orientation="vertical"></snice-divider>
+<snice-divider color="#3b82f6"></snice-divider>
+```

package/docs/ai/components/doc.md

@@ -1,53 +1,23 @@
 # snice-doc
 
-Simple WYSIWYG document editor with toolbar and sidebar.
-
-## Usage
-
-```html
-<snice-doc></snice-doc>
-<snice-doc icons="material"></snice-doc>
-<snice-doc icons="fontawesome"></snice-doc>
-```
+Simple WYSIWYG document editor with formatting toolbar and content insertion.
 
 ## Properties
 
-- `placeholder: string` - Placeholder text (default: `"Start typing..."`)
-- `readonly: boolean` - Readonly mode (default: `false`)
-- `icons: 'default' | 'material' | 'fontawesome'` - Toolbar icon set (default: `"default"`)
+```typescript
+placeholder: string = 'Start typing...';
+readonly: boolean = false;
+icons: 'default'|'material'|'fontawesome' = 'default';
+```
 
 ## Methods
 
-- `getHTML(): string` - Get HTML content
-- `setHTML(html: string): void` - Set HTML content
-- `getText(): string` - Get plain text content
-- `getMarkdown(): string` - Get content as markdown
-- `downloadAs(format: 'html' | 'markdown' | 'text', filename?: string): void` - Download document
-- `clear(): void` - Clear all content
-
-## Toolbar
-
-- **B, I, U, S** - Bold, italic, underline, strikethrough
-- **H1, H2, H3, P** - Heading formats and paragraph
-- **•, 1.** - Bulleted and numbered lists
-- **🔗** - Insert link
-- **🖼** - Insert image
-- **📊** - Insert table
-- **―** - Insert divider
-- **⬇** - Download (HTML, Markdown, or Plain Text)
-
-## Icon Sets
-
-- `default` - Text labels and emoji icons
-- `material` - Material Symbols Outlined (user must load the font in the document)
-- `fontawesome` - Font Awesome 6 solid icons (user must load the font in the document)
-- Fonts cascade from light DOM into shadow DOM — no auto-loading
-
-## Keyboard Shortcuts
-
-- **Ctrl/Cmd+B** - Bold
-- **Ctrl/Cmd+I** - Italic
-- **Ctrl/Cmd+U** - Underline
+- `getHTML()` → `string` - Get HTML content
+- `setHTML(html)` - Set HTML content
+- `getText()` → `string` - Get plain text content
+- `getMarkdown()` → `string` - Get content as Markdown
+- `downloadAs(format, filename?)` - Download as `'html'`|`'markdown'`|`'text'`
+- `clear()` - Clear all content
 
 ## CSS Custom Properties
 
@@ -67,40 +37,45 @@ Simple WYSIWYG document editor with toolbar and sidebar.
 --snice-doc-sidebar-background
 ```
 
-## Example
+## CSS Parts
 
-```typescript
-doc.setHTML(`
-  <h1>Title</h1>
-  <p>Content with <b>bold</b> and <i>italic</i>.</p>
-`);
+- `base` - Outer document wrapper
+- `editor` - Editable content area
+- `toolbar` - Formatting toolbar
+- `icon` - Toolbar icon element
+
+## Basic Usage
+
+```html
+<snice-doc></snice-doc>
+<snice-doc icons="material"></snice-doc>
+<snice-doc icons="fontawesome"></snice-doc>
+<snice-doc readonly></snice-doc>
+```
 
-// Export formats
+```typescript
+doc.setHTML('<h1>Title</h1><p>Content with <b>bold</b>.</p>');
 const html = doc.getHTML();
 const markdown = doc.getMarkdown();
-const text = doc.getText();
-
-// Download
 doc.downloadAs('markdown', 'my-doc.md');
-doc.downloadAs('html');
-doc.downloadAs('text');
 ```
 
-## CSS Parts
+## Icon Sets
 
-- `base` - Outer document wrapper
-- `editor` - Editable content area
-- `toolbar` - Formatting toolbar
-- `icon` - Toolbar icon element
+- `default` - Text labels and emoji
+- `material` - Material Symbols Outlined (load font in document)
+- `fontawesome` - Font Awesome 6 solid (load font in document)
+- Fonts cascade from light DOM into shadow DOM
+
+## Keyboard Navigation
+
+- Ctrl/Cmd+B - Bold
+- Ctrl/Cmd+I - Italic
+- Ctrl/Cmd+U - Underline
 
-## Features
+## Accessibility
 
-- WYSIWYG contentEditable editing
-- Formatting toolbar with configurable icon sets
-- Insert images, tables, dividers, links
-- Download as HTML, Markdown, or Plain Text
+- contentEditable for native text editing
+- Semantic HTML output
+- Dark mode via prefers-color-scheme
 - Paste images from clipboard
-- Keyboard shortcuts
-- Readonly mode
-- Dark mode (prefers-color-scheme)
-- Material Icons and Font Awesome support

package/docs/ai/components/draw.md

@@ -1,6 +1,6 @@
 # snice-draw
 
-Canvas drawing with lazy-brush smoothing.
+Canvas drawing with lazy-brush smoothing, auto-polygon, and auto-circle.
 
 ## Properties
 
@@ -9,30 +9,29 @@ width: number = 800;
 height: number = 600;
 tool: 'pen'|'eraser'|'line'|'rectangle'|'circle'|'text' = 'pen';
 color: string = '#000000';
-strokeWidth: number = 2;           // attribute: stroke-width
+strokeWidth: number = 2;            // attribute: stroke-width
 backgroundColor: string = '#ffffff'; // attribute: background-color
 lazy: boolean = false;
-lazyRadius: number = 60;           // attribute: lazy-radius
+lazyRadius: number = 60;            // attribute: lazy-radius
 friction: number = 0.1;
 smoothing: number = 0.5;
-autoPolygon: boolean = false;      // attribute: auto-polygon
-polygonCurvePoints: number = 10;   // attribute: polygon-curve-points
+autoPolygon: boolean = false;       // attribute: auto-polygon
+polygonCurvePoints: number = 10;    // attribute: polygon-curve-points (2-30)
+autoCircle: boolean = false;        // attribute: auto-circle
+circlePoints: number = 50;          // attribute: circle-points
 disabled: boolean = false;
 ```
 
 ## Methods
 
-```typescript
-clear(): void
-undo(): void
-redo(): void
-toDataURL(type?: 'image/png'|'image/jpeg'|'image/webp', quality?: number): string
-toBlob(type?: 'image/png'|'image/jpeg'|'image/webp', quality?: number): Promise<Blob>
-download(filename?: string): void
-loadImage(url: string): Promise<void>
-getStrokes(): DrawStroke[]
-setStrokes(strokes: DrawStroke[]): void
-```
+- `clear()` - Clear canvas
+- `undo()` / `redo()` - Undo/redo strokes
+- `toDataURL(type?, quality?)` → `string` - Export as data URL
+- `toBlob(type?, quality?)` → `Promise<Blob>` - Export as Blob
+- `download(filename?)` - Download drawing
+- `loadImage(url)` → `Promise<void>` - Load background image
+- `getStrokes()` → `DrawStroke[]` - Get all strokes
+- `setStrokes(strokes)` - Set strokes (load saved drawings)
 
 ## DrawStroke
 
@@ -42,7 +41,7 @@ interface DrawStroke {
   tool: DrawTool;
   color: string;
   width: number;
-  points: Point[];
+  points: Point[];      // {x, y, pressure?}
   timestamp: number;
 }
 ```
@@ -50,95 +49,44 @@ interface DrawStroke {
 ## Events
 
 - `draw-start` - Drawing started
-- `draw-end` - Stroke completed (detail: { stroke })
+- `draw-end` → `{ stroke }` - Stroke completed
 - `draw-clear` - Canvas cleared
 - `draw-undo` - Undo performed
 - `draw-redo` - Redo performed
 
-## Usage
+## CSS Parts
 
-```javascript
-// Change tool
-draw.tool = 'pen';
-draw.color = '#ff0000';
-draw.strokeWidth = 5;
+- `base` - Outer draw container
+- `canvas` - Drawing canvas element
 
-// Lazy brush
-draw.lazy = true;
-draw.lazyRadius = 60;
-draw.friction = 0.1;
-draw.smoothing = 0.5;
+## Basic Usage
 
-// Auto-polygon
-draw.autoPolygon = true;
-draw.polygonCurvePoints = 15; // Smoother curves
+```html
+<snice-draw width="800" height="600" tool="pen" color="#000000" stroke-width="2"></snice-draw>
+<snice-draw lazy lazy-radius="60" auto-polygon polygon-curve-points="15"></snice-draw>
+<snice-draw auto-circle circle-points="50"></snice-draw>
+```
 
-// Actions
+```typescript
+draw.tool = 'pen';
+draw.color = '#ff0000';
 draw.clear();
 draw.undo();
-draw.redo();
-
-// Export
-const dataURL = draw.toDataURL('image/png');
-const blob = await draw.toBlob('image/png');
 draw.download('drawing.png');
 
-// Save/load
 const strokes = draw.getStrokes();
 draw.setStrokes(strokes);
-
-// Load image
 await draw.loadImage('bg.jpg');
 ```
 
-```html
-<snice-draw
-  width="800"
-  height="600"
-  tool="pen"
-  color="#000000"
-  stroke-width="2"
-  lazy
-  lazy-radius="60"
-  friction="0.1"
-  auto-polygon
-  polygon-curve-points="10">
-</snice-draw>
-```
-
-**CSS Parts:**
-- `base` - Outer draw container div
-- `canvas` - Drawing canvas element
-
 ## Lazy Brush
 
-Smooth drawing with cursor lag-following:
-- Brush follows cursor within radius
-- Creates organic, smooth lines
-- Reduces jitter and tremor
-- Configurable radius and smoothing
+Brush follows cursor within radius for smooth lines. Larger radius = smoother. Reduces jitter/tremor.
 
 ## Auto-Polygon
 
-Automatically processes completed strokes into closed shapes:
-- Detects self-intersections and trims excess
-- Auto-closes open shapes with smooth curves
-- `autoPolygon: boolean` - Enable feature (default: false)
-- `polygonCurvePoints: number` - Curve smoothness 2-30 (default: 10)
-
-Processing happens on stroke completion (pointerup):
-1. If stroke crosses itself, trim at first intersection
-2. If start/end points >20px apart, connect with quadratic curve
-3. Higher curve points = smoother closing arc
-
-## Features
-
-- Canvas drawing
-- Lazy brush smoothing
-- Auto-polygon processing
-- Pen/eraser tools
-- Undo/redo
-- Export (PNG/JPEG/WebP)
-- Save/load strokes
-- Touch/stylus support
-- Keyboard shortcuts
+Processes completed strokes into closed shapes. Detects self-intersections and trims. Auto-closes open shapes with smooth curves. `polygonCurvePoints` 2-30 controls curve smoothness.
+
+## Auto-Circle
+
+Detects circular strokes and smooths them. `circlePoints` controls closing curve smoothness.