snice 4.28.0 → 4.30.0

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

@@ -1,22 +1,18 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/date-time-picker.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/date-time-picker.md -->
 
 # Date Time Picker
 `<snice-date-time-picker>`
 
-Combined date and time picker with calendar and scrollable time selectors.
+Combined date and time picker with calendar and scrollable time selectors. Form-associated custom element.
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/date-time-picker/snice-date-time-picker';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-date-time-picker.min.js"></script>
-```
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
 
 ## Properties
 
@@ -92,6 +88,12 @@ import 'snice/components/date-time-picker/snice-date-time-picker';
 <snice-date-time-picker label="Appointment"></snice-date-time-picker>
 ```
 
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-date-time-picker.min.js"></script>
+```
+
 ## Examples
 
 ### With Initial Value
@@ -192,6 +194,8 @@ Use `helper-text` and `error-text` for guidance or validation.
 
 ### Disabled and Readonly
 
+Use `disabled` or `readonly` to prevent user interaction.
+
 ```html
 <snice-date-time-picker disabled value="2024-12-25T14:30" label="Disabled"></snice-date-time-picker>
 <snice-date-time-picker readonly value="2024-12-25T14:30" label="Readonly"></snice-date-time-picker>
@@ -211,10 +215,6 @@ Use `name` and `required` for native form participation.
 
 Listen for changes using the `datetime-change` event.
 
-```html
-<snice-date-time-picker id="dtp" label="Pick date & time"></snice-date-time-picker>
-```
-
 ```typescript
 dtp.addEventListener('datetime-change', (e) => {
   console.log('ISO:', e.detail.iso);
@@ -225,20 +225,17 @@ dtp.addEventListener('datetime-change', (e) => {
 
 ### Form Validation
 
-The component supports the Constraint Validation API. Use `checkValidity()`, `reportValidity()`, and `setCustomValidity()` for custom form validation.
-
-```html
-<form>
-  <snice-date-time-picker name="appointment" required label="Appointment"></snice-date-time-picker>
-  <button type="submit">Submit</button>
-</form>
-```
+The component supports the Constraint Validation API.
 
 ```typescript
 picker.setCustomValidity('Please select a future date and time');
 picker.reportValidity();
 ```
 
-## Responsive Behavior
+## Accessibility
 
-On screens smaller than 480px, the panel stacks the calendar and time selectors vertically instead of side-by-side.
+- Form-associated custom element with `ElementInternals`
+- Calendar popup uses `popover="manual"` for proper layering
+- Supports `aria-invalid` when in invalid state
+- Required fields show visual indicator on the label
+- On screens smaller than 480px, the panel stacks vertically

package/docs/components/diff.md

@@ -1,8 +1,9 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/diff.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/diff.md -->
 
 # Diff Component
+`<snice-diff>`
 
-The diff component displays a text diff between two strings with unified or side-by-side (split) views, line numbers, word-level highlighting, collapsible unchanged sections, and addition/deletion statistics.
+Text diff viewer with unified and split (side-by-side) modes, line numbers, word-level highlighting, collapsible unchanged sections, and addition/deletion statistics.
 
 ## Table of Contents
 - [Properties](#properties)
@@ -58,13 +59,11 @@ interface DiffHunk {
 
 ## CSS Parts
 
-Style internal elements from outside the shadow DOM using `::part()`.
-
-| Part | Element | Description |
-|------|---------|-------------|
-| `base` | `<div>` | Outer diff container |
-| `header` | `<div>` | Header with addition/deletion stats and mode toggle buttons |
-| `content` | `<div>` | Diff content area containing the diff table(s) |
+| Part | Description |
+|------|-------------|
+| `base` | Outer diff container |
+| `header` | Header with addition/deletion stats and mode toggle buttons |
+| `content` | Diff content area containing the diff table(s) |
 
 ```css
 snice-diff::part(base) {
@@ -81,12 +80,18 @@ snice-diff::part(header) {
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/diff/snice-diff';
+```
+
 ```html
 <snice-diff old-text="hello world" new-text="hello there"></snice-diff>
 ```
 
-```typescript
-import 'snice/components/diff/snice-diff';
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-diff.min.js"></script>
 ```
 
 ## Examples
@@ -193,9 +198,9 @@ When comparing large files, unchanged sections beyond the `context-lines` thresh
 
 ## Accessibility
 
-- **Dark mode support**: Automatically adapts colors for `[data-theme="dark"]` and `prefers-color-scheme: dark`
-- **Line numbers**: Provide clear reference points for discussing specific changes
-- **Color coding**: Added lines are highlighted with a green background, removed lines with red, providing clear visual distinction
-- **Word-level diffs**: Within changed lines, the specific words that differ are highlighted for precision
-- **Collapsible sections**: Large unchanged regions are collapsed to reduce noise and can be expanded on demand
-- **Stats header**: The +N/-N summary provides an immediate overview of the change scope
+- Dark mode support via `[data-theme="dark"]` and `prefers-color-scheme: dark`
+- Line numbers provide clear reference points for discussing specific changes
+- Color coding: added lines highlighted green, removed lines red
+- Word-level diffs highlight the specific words that differ within changed lines
+- Collapsible sections reduce noise; click to expand
+- Stats header provides an immediate +N/-N overview of change scope

package/docs/components/divider.md

@@ -1,22 +1,16 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/divider.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/divider.md -->
 
 # Divider
 `<snice-divider>`
 
 Separator line with optional text label.
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/divider/snice-divider';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-divider.min.js"></script>
-```
+## Table of Contents
+- [Properties](#properties)
+- [CSS Custom Properties](#css-custom-properties)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
 
 ## Properties
 
@@ -43,13 +37,11 @@ import 'snice/components/divider/snice-divider';
 
 ## CSS Parts
 
-Style internal elements from outside the shadow DOM using `::part()`.
-
-| Part | Element | Description |
-|------|---------|-------------|
-| `base` | `<div>` | Outer divider container |
-| `line` | `<div>` | The divider line(s) |
-| `text` | `<span>` | Optional text label |
+| Part | Description |
+|------|-------------|
+| `base` | Outer divider container |
+| `line` | The divider line(s) |
+| `text` | Optional text label |
 
 ```css
 snice-divider::part(line) {
@@ -72,6 +64,12 @@ import 'snice/components/divider/snice-divider';
 <snice-divider></snice-divider>
 ```
 
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-divider.min.js"></script>
+```
+
 ## Examples
 
 ### Variants

package/docs/components/doc.md

@@ -1,82 +1,65 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/doc.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/doc.md -->
 
-# snice-doc
+# Doc
+`<snice-doc>`
 
 A simple WYSIWYG document editor component with formatting toolbar and content insertion capabilities.
 
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [CSS Custom Properties](#css-custom-properties)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Keyboard Navigation](#keyboard-navigation)
+- [Accessibility](#accessibility)
+
 ## Properties
 
-| Property          | Attribute          | Type      | Default              | Description                                      |
-| ----------------- | ------------------ | --------- | -------------------- | ------------------------------------------------ |
-| `placeholder`     | `placeholder`      | `string`  | `"Start typing..."`  | Placeholder text when empty                      |
-| `readonly`        | `readonly`         | `boolean` | `false`              | Whether the editor is readonly                   |
-| `icons`           | `icons`            | `string`  | `"default"`          | Icon set: `"default"`, `"material"`, `"fontawesome"` |
+| Property | Attribute | Type | Default | Description |
+|----------|-----------|------|---------|-------------|
+| `placeholder` | `placeholder` | `string` | `"Start typing..."` | Placeholder text when empty |
+| `readonly` | `readonly` | `boolean` | `false` | Whether the editor is readonly |
+| `icons` | `icons` | `'default' \| 'material' \| 'fontawesome'` | `'default'` | Toolbar icon set |
 
 ## Methods
 
-### `getHTML(): string`
-
-Get the current HTML content of the editor.
-
-```javascript
-const html = editor.getHTML();
-```
-
-### `setHTML(html: string): void`
-
-Set the HTML content of the editor.
-
-```javascript
-editor.setHTML(`
-  <h1>Welcome!</h1>
-  <p>This is a <b>simple</b> document editor.</p>
-`);
-```
-
-### `getText(): string`
-
-Get the document content as plain text.
-
-```javascript
-const text = editor.getText();
-```
-
-### `getMarkdown(): string`
-
-Get the document content converted to Markdown. Supports headings, bold, italic, strikethrough, links, images, lists, tables, horizontal rules, and inline code.
-
-```javascript
-const md = editor.getMarkdown();
-```
-
-### `downloadAs(format: 'html' | 'markdown' | 'text', filename?: string): void`
-
-Download the document in the specified format. If no filename is provided, defaults to `document.html`, `document.md`, or `document.txt`.
-
-```javascript
-editor.downloadAs('markdown', 'my-document.md');
-editor.downloadAs('html');
-editor.downloadAs('text', 'notes.txt');
-```
-
-### `clear(): void`
-
-Clear all content and reset to an empty paragraph.
-
-```javascript
-editor.clear();
-```
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `getHTML()` | -- | Returns the current HTML content |
+| `setHTML()` | `html: string` | Sets the HTML content |
+| `getText()` | -- | Returns the content as plain text |
+| `getMarkdown()` | -- | Returns the content converted to Markdown |
+| `downloadAs()` | `format: 'html' \| 'markdown' \| 'text', filename?: string` | Downloads the document in the specified format |
+| `clear()` | -- | Clears all content and resets to empty paragraph |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--snice-doc-font-family` | Editor font family |
+| `--snice-doc-font-size` | Editor font size |
+| `--snice-doc-text-color` | Text color |
+| `--snice-doc-background` | Editor background |
+| `--snice-doc-muted-color` | Muted text color |
+| `--snice-doc-placeholder-color` | Placeholder text color |
+| `--snice-doc-primary-color` | Primary accent color |
+| `--snice-doc-link-color` | Link color |
+| `--snice-doc-inline-code-background` | Inline code background |
+| `--snice-doc-toolbar-background` | Toolbar background |
+| `--snice-doc-border` | Border color |
+| `--snice-doc-hover-background` | Hover state background |
+| `--snice-doc-sidebar-background` | Sidebar background |
 
 ## CSS Parts
 
-Style internal elements from outside the shadow DOM using `::part()`.
-
-| Part | Element | Description |
-|------|---------|-------------|
-| `base` | `<div>` | The outer document wrapper |
-| `editor` | `<div>` | The editable content area |
-| `toolbar` | `<div>` | The formatting toolbar |
-| `icon` | `<span>` | Toolbar icon element |
+| Part | Description |
+|------|-------------|
+| `base` | The outer document wrapper |
+| `editor` | The editable content area |
+| `toolbar` | The formatting toolbar |
+| `icon` | Toolbar icon element |
 
 ```css
 snice-doc::part(base) {
@@ -97,22 +80,28 @@ snice-doc::part(editor) {
 
 ## Basic Usage
 
-```html
-<snice-doc id="editor"></snice-doc>
+```typescript
+import 'snice/components/doc/snice-doc';
 ```
 
-```typescript
-import 'snice';
+```html
+<snice-doc id="editor"></snice-doc>
 
-// Set initial content
-editor.setHTML('<h1>Welcome</h1><p>Start editing...</p>');
+<script>
+  editor.setHTML('<h1>Welcome</h1><p>Start editing...</p>');
+  const html = editor.getHTML();
+</script>
+```
 
-// Get content
-const html = editor.getHTML();
-console.log(html);
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-doc.min.js"></script>
 ```
 
-## Toolbar Features
+## Examples
+
+### Toolbar Features
 
 The toolbar includes:
 
@@ -121,17 +110,17 @@ The toolbar includes:
 - **U** - Underline text (Ctrl/Cmd+U)
 - **S** - Strikethrough text
 - **H1, H2, H3, P** - Heading formats and paragraph
-- **• / 1.** - Bulleted and numbered lists
-- **🔗** - Insert link
-- **🖼** - Insert image
-- **📊** - Insert table
-- **―** - Insert divider
-- **⬇** - Download menu (HTML, Markdown, Plain Text)
-
-## Examples
+- **Bullet / Number** - Bulleted and numbered lists
+- **Link** - Insert link
+- **Image** - Insert image
+- **Table** - Insert table
+- **Divider** - Insert horizontal rule
+- **Download** - Download menu (HTML, Markdown, Plain Text)
 
 ### Export and Download
 
+Use `downloadAs()` to save the document in different formats.
+
 ```html
 <snice-doc id="editor"></snice-doc>
 <button id="save-md">Save as Markdown</button>
@@ -148,14 +137,33 @@ saveHtml.addEventListener('click', () => {
 });
 ```
 
-### Material Icons
+### Icon Sets
+
+Use the `icons` attribute to switch toolbar icon sets.
+
+**Default (text/emoji)**
+```html
+<snice-doc></snice-doc>
+```
 
+**Material Symbols** - requires loading the font in your document:
 ```html
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined">
 <snice-doc icons="material"></snice-doc>
 ```
 
+**Font Awesome** - requires loading the Font Awesome stylesheet:
+```html
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.7.2/css/all.min.css">
+<snice-doc icons="fontawesome"></snice-doc>
+```
+
+Fonts cascade from light DOM into the shadow DOM automatically.
+
 ### Readonly Document Viewer
 
+Set `readonly` to display documents without editing capabilities.
+
 ```html
 <snice-doc readonly></snice-doc>
 ```
@@ -169,127 +177,27 @@ viewer.setHTML(`
 
 ### Save and Load Content
 
-```html
-<snice-doc id="editor"></snice-doc>
-<button id="save">Save</button>
-<button id="load">Load</button>
-```
+Use `getHTML()` and `setHTML()` to persist content.
 
 ```typescript
-save.addEventListener('click', () => {
-  localStorage.setItem('document', editor.getHTML());
-});
-
-load.addEventListener('click', () => {
-  const html = localStorage.getItem('document');
-  if (html) editor.setHTML(html);
-});
-```
-
-## Features
-
-- **WYSIWYG editing** - Direct HTML content editing
-- **Formatting toolbar** - Bold, italic, underline, strikethrough, headings, lists
-- **Content insertion** - Links, images, tables, dividers
-- **Download/Export** - Save as HTML, Markdown, or Plain Text
-- **Icon sets** - Default text labels, Material Icons, or Font Awesome
-- **Paste image support** - Paste images directly from clipboard
-- **Keyboard shortcuts** - Ctrl/Cmd+B for bold, Ctrl/Cmd+I for italic, Ctrl/Cmd+U for underline
-- **Readonly mode** - Display documents without editing capabilities
-- **Dark mode** - Automatic dark mode via prefers-color-scheme
-- **Customizable styling** - CSS custom properties for theming
-
-## Icon Sets
-
-The `icons` property controls which icon set the toolbar uses:
-
-### Default (text/emoji)
-
-```html
-<snice-doc></snice-doc>
-```
-
-Uses text labels (B, I, U, H1, etc.) and emoji for action buttons.
-
-### Material Symbols
-
-```html
-<!-- Load the font in your document -->
-<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined">
+// Save
+localStorage.setItem('document', editor.getHTML());
 
-<snice-doc icons="material"></snice-doc>
-```
-
-Uses [Material Symbols Outlined](https://fonts.google.com/icons). You must load the font stylesheet in your document — the font cascades from light DOM into the shadow DOM automatically.
-
-### Font Awesome
-
-```html
-<!-- Load the font in your document -->
-<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.7.2/css/all.min.css">
-
-<snice-doc icons="fontawesome"></snice-doc>
+// Load
+const html = localStorage.getItem('document');
+if (html) editor.setHTML(html);
 ```
 
-Uses [Font Awesome 6](https://fontawesome.com/icons) solid icons. You must load the Font Awesome stylesheet in your document.
-
-## Keyboard Shortcuts
+## Keyboard Navigation
 
 - **Ctrl/Cmd+B** - Toggle bold
 - **Ctrl/Cmd+I** - Toggle italic
 - **Ctrl/Cmd+U** - Toggle underline
 
-## Styling
-
-The component can be styled using CSS custom properties:
-
-```css
-snice-doc {
-  /* Colors */
-  --snice-doc-text-color: #333;
-  --snice-doc-background: #fff;
-  --snice-doc-muted-color: #999;
-  --snice-doc-placeholder-color: #999;
-  --snice-doc-primary-color: #0969da;
-  --snice-doc-link-color: #0969da;
-
-  /* Code */
-  --snice-doc-inline-code-background: rgba(175, 184, 193, 0.2);
-
-  /* Toolbar */
-  --snice-doc-toolbar-background: #f6f8fa;
-
-  /* Borders */
-  --snice-doc-border: #e1e4e8;
-  --snice-doc-hover-background: #e8eaed;
-
-  /* Sidebar */
-  --snice-doc-sidebar-background: #f6f8fa;
-}
-```
-
-Dark mode is supported automatically via `prefers-color-scheme: dark`.
-
 ## Accessibility
 
-- Supports keyboard navigation
-- Uses contentEditable for native text editing
+- Uses `contentEditable` for native text editing behavior
 - Semantic HTML output
-
-## Browser Support
-
-Works in all modern browsers that support:
-- Custom Elements v1
-- Shadow DOM
-- contentEditable
-- ES2020+
-
-## TypeScript
-
-Full TypeScript support:
-
-```typescript
-const html = editor.getHTML();
-const markdown = editor.getMarkdown();
-editor.downloadAs('markdown', 'export.md');
-```
+- Keyboard shortcuts for formatting
+- Dark mode support via `prefers-color-scheme: dark`
+- Paste images directly from clipboard