snice 4.9.0 → 4.10.0

package/docs/components/date-picker.md

@@ -0,0 +1,201 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/date-picker.md instead)
+
+# Date Picker
+`<snice-date-picker>`
+
+Calendar-based date input with format options and validation.
+
+## Basic Usage
+
+```typescript
+import 'snice/components/date-picker/snice-date-picker';
+```
+
+```html
+<snice-date-picker label="Select date"></snice-date-picker>
+```
+
+## Importing
+
+**ESM (bundler)**
+```typescript
+import 'snice/components/date-picker/snice-date-picker';
+```
+
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-date-picker.min.js"></script>
+```
+
+## Examples
+
+### Variants
+
+Use the `variant` attribute to change the input style.
+
+```html
+<snice-date-picker variant="outlined" label="Outlined"></snice-date-picker>
+<snice-date-picker variant="filled" label="Filled"></snice-date-picker>
+<snice-date-picker variant="underlined" label="Underlined"></snice-date-picker>
+```
+
+### Sizes
+
+Use the `size` attribute to change the picker size.
+
+```html
+<snice-date-picker size="small" label="Small"></snice-date-picker>
+<snice-date-picker size="medium" label="Medium"></snice-date-picker>
+<snice-date-picker size="large" label="Large"></snice-date-picker>
+```
+
+### Date Formats
+
+Use the `format` attribute to control how dates are displayed and parsed.
+
+```html
+<snice-date-picker format="mm/dd/yyyy" label="US Format"></snice-date-picker>
+<snice-date-picker format="dd/mm/yyyy" label="EU Format"></snice-date-picker>
+<snice-date-picker format="yyyy-mm-dd" label="ISO Format"></snice-date-picker>
+<snice-date-picker format="mmmm dd, yyyy" label="Long Format"></snice-date-picker>
+```
+
+### Min and Max Dates
+
+Use the `min` and `max` attributes to restrict the selectable date range.
+
+```html
+<snice-date-picker min="2024-01-01" max="2024-12-31" label="Year 2024 only"></snice-date-picker>
+```
+
+### Clearable
+
+Set the `clearable` attribute to show a clear button when a date is selected.
+
+```html
+<snice-date-picker value="2024-03-15" clearable label="Clearable"></snice-date-picker>
+```
+
+### Helper and Error Text
+
+Use the `helper-text` and `error-text` attributes to provide guidance or validation messages.
+
+```html
+<snice-date-picker label="Start Date" helper-text="Choose a date in the future"></snice-date-picker>
+<snice-date-picker label="End Date" invalid error-text="End date must be after start date"></snice-date-picker>
+```
+
+### Loading
+
+Set the `loading` attribute to show a spinner and disable interaction.
+
+```html
+<snice-date-picker loading label="Loading dates"></snice-date-picker>
+```
+
+### Disabled and Readonly
+
+Use `disabled` or `readonly` to prevent user interaction.
+
+```html
+<snice-date-picker disabled value="2024-06-15" label="Disabled"></snice-date-picker>
+<snice-date-picker readonly value="2024-06-15" label="Readonly"></snice-date-picker>
+```
+
+### First Day of Week
+
+Use the `first-day-of-week` attribute to set which day starts the week (0 = Sunday, 1 = Monday).
+
+```html
+<snice-date-picker first-day-of-week="1" label="Week starts Monday"></snice-date-picker>
+```
+
+### Form Integration
+
+Use `name` and `required` for native form participation.
+
+```html
+<form>
+  <snice-date-picker name="birthdate" required label="Date of Birth"></snice-date-picker>
+</form>
+```
+
+### Event Handling
+
+Listen for date changes using the `datepicker-change` event.
+
+```html
+<snice-date-picker id="dp" label="Pick a date"></snice-date-picker>
+<script>
+document.querySelector('#dp').addEventListener('datepicker-change', (e) => {
+  console.log('Date:', e.detail.formatted);
+  console.log('ISO:', e.detail.iso);
+});
+</script>
+```
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+|----------|-----------|------|---------|-------------|
+| `value` | `value` | `string` | `''` | Current date value |
+| `format` | `format` | `'yyyy-mm-dd' \| 'mm/dd/yyyy' \| 'dd/mm/yyyy' \| 'yyyy/mm/dd' \| 'dd-mm-yyyy' \| 'mm-dd-yyyy' \| 'mmmm dd, yyyy'` | `'mm/dd/yyyy'` | Display and parse format |
+| `variant` | `variant` | `'outlined' \| 'filled' \| 'underlined'` | `'outlined'` | Input visual style |
+| `size` | `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Component size |
+| `placeholder` | `placeholder` | `string` | `''` | Input placeholder text |
+| `label` | `label` | `string` | `''` | Label text |
+| `helperText` | `helper-text` | `string` | `''` | Helper text below input |
+| `errorText` | `error-text` | `string` | `''` | Error text below input |
+| `disabled` | `disabled` | `boolean` | `false` | Disables the picker |
+| `readonly` | `readonly` | `boolean` | `false` | Makes the input read-only |
+| `loading` | `loading` | `boolean` | `false` | Shows loading spinner |
+| `required` | `required` | `boolean` | `false` | Marks as required |
+| `invalid` | `invalid` | `boolean` | `false` | Shows invalid styling |
+| `clearable` | `clearable` | `boolean` | `false` | Shows clear button |
+| `min` | `min` | `string` | `''` | Minimum selectable date |
+| `max` | `max` | `string` | `''` | Maximum selectable date |
+| `name` | `name` | `string` | `''` | Form field name |
+| `showCalendar` | `show-calendar` | `boolean` | `false` | Calendar visibility |
+| `firstDayOfWeek` | `first-day-of-week` | `number` | `0` | First day of week (0=Sun) |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `datepicker-input` | `{ value, datePicker }` | Fired on text input |
+| `datepicker-change` | `{ value, date, formatted, iso, datePicker }` | Fired when date changes |
+| `datepicker-focus` | `{ datePicker }` | Fired on input focus |
+| `datepicker-blur` | `{ datePicker }` | Fired on input blur |
+| `datepicker-open` | `{ datePicker }` | Fired when calendar opens |
+| `datepicker-close` | `{ datePicker }` | Fired when calendar closes |
+| `datepicker-clear` | `{ datePicker }` | Fired when value is cleared |
+| `datepicker-select` | `{ date, formatted, iso, datePicker }` | Fired when a date is selected |
+
+## Methods
+
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `focus()` | — | Focuses the input |
+| `blur()` | — | Removes focus |
+| `clear()` | — | Clears the selected date |
+| `open()` | — | Opens the calendar popup |
+| `close()` | — | Closes the calendar popup |
+| `selectDate()` | `date: Date` | Programmatically selects a date |
+| `goToMonth()` | `year: number, month: number` | Navigates calendar to a month |
+| `goToToday()` | — | Selects today's date |
+| `checkValidity()` | — | Returns input validity |
+| `reportValidity()` | — | Reports input validity |
+| `setCustomValidity()` | `message: string` | Sets custom validation message |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `input` | The text input element |
+| `calendar-toggle` | The calendar icon button |
+| `clear` | The clear button |
+| `spinner` | The loading spinner |
+| `calendar` | The calendar popup container |
+| `helper-text` | The helper text element |
+| `error-text` | The error text element |

package/docs/components/diff.md

@@ -0,0 +1,177 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/diff.md instead)
+
+# Diff Component
+
+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.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [Events](#events)
+- [CSS Custom Properties](#css-custom-properties)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+
+## Basic Usage
+
+```html
+<snice-diff old-text="hello world" new-text="hello there"></snice-diff>
+```
+
+```typescript
+import 'snice/components/diff/snice-diff';
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `oldText` (attr: `old-text`) | `string` | `''` | The original text |
+| `newText` (attr: `new-text`) | `string` | `''` | The modified text |
+| `language` | `string` | `''` | Language hint for future syntax highlighting support |
+| `mode` | `'unified' \| 'split'` | `'unified'` | Display mode: unified inline view or side-by-side split view |
+| `lineNumbers` (attr: `line-numbers`) | `boolean` | `true` | Show line number gutters |
+| `contextLines` (attr: `context-lines`) | `number` | `3` | Number of unchanged lines shown around each change |
+| `markers` | `boolean` | `true` | Show the +/- markers column |
+
+### Types
+
+```typescript
+interface DiffLine {
+  type: 'added' | 'removed' | 'unchanged';
+  oldLine: number | null;
+  newLine: number | null;
+  content: string;
+}
+
+interface DiffHunk {
+  lines: DiffLine[];
+  collapsed: boolean;
+}
+```
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `diff-computed` | `{ hunks: DiffHunk[], additions: number, deletions: number }` | Fired after the diff is calculated, with hunk data and stats |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--snice-diff-added-bg` | Background color for added lines |
+| `--snice-diff-removed-bg` | Background color for removed lines |
+| `--snice-diff-added-word-bg` | Word-level highlight color for added text |
+| `--snice-diff-removed-word-bg` | Word-level highlight color for removed text |
+
+## Examples
+
+### Unified Diff View
+
+The default unified mode shows all changes inline with +/- markers.
+
+```html
+<snice-diff
+  old-text="function greet(name) {
+  return 'Hello, ' + name;
+}"
+  new-text="function greet(name) {
+  return `Hello, ${name}!`;
+}"
+  mode="unified"
+  context-lines="3">
+</snice-diff>
+```
+
+### Side-by-Side Split View
+
+Use `mode="split"` to display old and new text in separate columns.
+
+```html
+<snice-diff
+  id="split-diff"
+  mode="split"
+  line-numbers
+  context-lines="3">
+</snice-diff>
+
+<script type="module">
+  import 'snice/components/diff/snice-diff';
+
+  const diff = document.getElementById('split-diff');
+  diff.oldText = `const x = 1;
+const y = 2;
+const z = x + y;
+console.log(z);`;
+
+  diff.newText = `const x = 10;
+const y = 2;
+const sum = x + y;
+console.log(sum);
+console.log('done');`;
+</script>
+```
+
+### Without Line Numbers or Markers
+
+Set `line-numbers="false"` and `markers="false"` for a minimal view.
+
+```html
+<snice-diff
+  old-text="The quick brown fox"
+  new-text="The slow red fox"
+  line-numbers="false"
+  markers="false">
+</snice-diff>
+```
+
+### Listening to Diff Stats
+
+Use the `diff-computed` event to access addition and deletion counts.
+
+```html
+<snice-diff id="stats-diff" old-text="Line A" new-text="Line B"></snice-diff>
+<p id="diff-stats"></p>
+
+<script type="module">
+  const diff = document.getElementById('stats-diff');
+  diff.addEventListener('diff-computed', (e) => {
+    const { additions, deletions } = e.detail;
+    document.getElementById('diff-stats').textContent =
+      `+${additions} additions, -${deletions} deletions`;
+  });
+</script>
+```
+
+### Comparing Large Texts with Collapsed Sections
+
+When comparing large files, unchanged sections beyond the `context-lines` threshold are collapsed. Click the collapsed section indicator to expand it.
+
+```html
+<snice-diff
+  id="large-diff"
+  mode="unified"
+  context-lines="2">
+</snice-diff>
+
+<script type="module">
+  const diff = document.getElementById('large-diff');
+
+  diff.oldText = Array.from({ length: 50 }, (_, i) => `Line ${i + 1}: original content`).join('\n');
+  diff.newText = Array.from({ length: 50 }, (_, i) => {
+    if (i === 10) return `Line ${i + 1}: MODIFIED content`;
+    if (i === 40) return `Line ${i + 1}: ALSO changed`;
+    return `Line ${i + 1}: original content`;
+  }).join('\n');
+</script>
+```
+
+## 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

package/docs/components/divider.md

@@ -0,0 +1,132 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/divider.md instead)
+
+# Divider
+`<snice-divider>`
+
+Separator line with optional text label.
+
+## Basic Usage
+
+```typescript
+import 'snice/components/divider/snice-divider';
+```
+
+```html
+<snice-divider></snice-divider>
+```
+
+## 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>
+```
+
+## Examples
+
+### Variants
+
+Use the `variant` attribute to change the line style.
+
+```html
+<snice-divider variant="solid"></snice-divider>
+<snice-divider variant="dashed"></snice-divider>
+<snice-divider variant="dotted"></snice-divider>
+```
+
+### With Text
+
+Use the `text` attribute to add a label to the divider.
+
+```html
+<snice-divider text="OR"></snice-divider>
+<snice-divider text="Section Title"></snice-divider>
+```
+
+### Text Alignment
+
+Use the `align` attribute to position the text label.
+
+```html
+<snice-divider text="Start" align="start"></snice-divider>
+<snice-divider text="Center" align="center"></snice-divider>
+<snice-divider text="End" align="end"></snice-divider>
+```
+
+### Text Background
+
+Use the `text-background` attribute to set the background behind the text label, useful when placed over colored backgrounds.
+
+```html
+<snice-divider text="Section" text-background="#ffffff"></snice-divider>
+```
+
+### Spacing
+
+Use the `spacing` attribute to control vertical margin around the divider.
+
+```html
+<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 Orientation
+
+Set `orientation` to `vertical` for use in horizontal layouts.
+
+```html
+<div style="display: flex; align-items: center; height: 50px; gap: 1rem;">
+  <span>Left</span>
+  <snice-divider orientation="vertical"></snice-divider>
+  <span>Right</span>
+</div>
+```
+
+### Custom Color
+
+Use the `color` attribute to change the divider color.
+
+```html
+<snice-divider color="#3b82f6"></snice-divider>
+<snice-divider color="rgb(22 163 74)"></snice-divider>
+```
+
+### Capped Ends
+
+Set the `capped` attribute for rounded line ends.
+
+```html
+<snice-divider capped></snice-divider>
+<snice-divider capped variant="dashed"></snice-divider>
+```
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+|----------|-----------|------|---------|-------------|
+| `orientation` | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Divider direction |
+| `variant` | `variant` | `'solid' \| 'dashed' \| 'dotted'` | `'solid'` | Line style |
+| `spacing` | `spacing` | `'none' \| 'small' \| 'medium' \| 'large'` | `'medium'` | Vertical margin |
+| `align` | `align` | `'start' \| 'center' \| 'end'` | `'center'` | Text position |
+| `text` | `text` | `string` | `''` | Text label content |
+| `textBackground` | `text-background` | `string` | `''` | Text label background color |
+| `color` | `color` | `string` | `''` | Custom divider color |
+| `capped` | `capped` | `boolean` | `false` | Rounded line ends |
+
+## CSS Custom Properties
+
+| Property | Description | Default |
+|----------|-------------|---------|
+| `--divider-color` | Line color | `var(--snice-color-border)` |
+| `--divider-thickness` | Line thickness | `1px` |
+| `--divider-text-bg` | Text label background | `transparent` |
+| `--divider-text-padding` | Text label padding | `0 1rem` |
+| `--divider-text-gap` | Gap around text label | `1rem` |

package/docs/components/doc.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/doc.md instead)
+
 # snice-doc
 
 A simple WYSIWYG document editor component with formatting toolbar and content insertion capabilities.

package/docs/components/draw.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/draw.md instead)
+
 # Draw Component
 
 Canvas drawing with smooth lazy-brush technology.

package/docs/components/drawer.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/drawer.md instead)
+
 # Drawer Component
 
 The `<snice-drawer>` component provides a slide-out panel that appears from any side of the viewport. It's commonly used for navigation menus, filters, settings panels, or additional content that shouldn't occupy permanent screen space.

package/docs/components/empty-state.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/empty-state.md instead)
+
 # Empty State Component
 
 The `<snice-empty-state>` component provides a consistent way to display empty or no-data states.

package/docs/components/file-gallery.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/file-gallery.md instead)
+
 # File Gallery Component
 
 The `<snice-file-gallery>` component provides a file upload gallery with drag-and-drop support, image previews, pausable/resumable uploads, and progress tracking.

package/docs/components/file-upload.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/file-upload.md instead)
+
 # File Upload Component
 
 The `<snice-file-upload>` component provides a file upload interface with drag-and-drop support, file previews, and validation.