snice 4.27.0 → 4.29.0

package/docs/components/countdown.md

@@ -1,8 +1,8 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/countdown.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/countdown.md -->
 
 # Countdown Component
 
-The countdown component displays a countdown timer to a target date with live-updating segments for days, hours, minutes, and seconds. It supports three visual variants (simple, flip, circular) and configurable display formats.
+A countdown timer to a target date with live-updating segments for days, hours, minutes, and seconds. Supports three visual variants (simple, flip, circular) and configurable display formats.
 
 ## Table of Contents
 - [Properties](#properties)
@@ -30,8 +30,6 @@ The countdown component displays a countdown timer to a target date with live-up
 
 ## CSS Custom Properties
 
-The countdown component uses standard Snice design tokens:
-
 | Property | Description |
 |----------|-------------|
 | `--snice-font-family` | Font family |
@@ -47,15 +45,13 @@ The countdown component uses standard Snice design tokens:
 
 ## CSS Parts
 
-Style internal elements from outside the shadow DOM using `::part()`.
-
-| Part | Element | Description |
-|------|---------|-------------|
-| `base` | `<div>` | Outer countdown container |
-| `segment` | `<div>` | Individual time segment (days, hours, etc.) |
-| `value` | `<span>` | Digit value within a segment |
-| `label` | `<span>` | Text label within a segment (e.g. "Days") |
-| `separator` | `<span>` | Colon separator between segments |
+| Part | Description |
+|------|-------------|
+| `base` | Outer countdown container |
+| `segment` | Individual time segment (days, hours, etc.) |
+| `value` | Digit value within a segment |
+| `label` | Text label within a segment (e.g. "Days") |
+| `separator` | Colon separator between segments |
 
 ```css
 snice-countdown::part(value) {
@@ -109,9 +105,9 @@ Use `variant="circular"` to display each segment inside a circular progress ring
 <snice-countdown target="2026-06-15T18:00:00Z" variant="circular" format="hms"></snice-countdown>
 ```
 
-### Short Format (Minutes and Seconds)
+### Short Format
 
-Use `format="ms"` for a short countdown that only shows minutes and seconds.
+Use `format="ms"` for a countdown that only shows minutes and seconds.
 
 ```html
 <snice-countdown target="2026-02-22T12:30:00Z" format="ms" variant="simple"></snice-countdown>
@@ -135,7 +131,6 @@ Listen for completion and tick events to trigger actions.
 
   countdown.addEventListener('countdown-tick', (e) => {
     if (e.detail.total <= 60) {
-      // Last minute — add urgency styling
       countdown.style.color = 'red';
     }
   });
@@ -144,7 +139,7 @@ Listen for completion and tick events to trigger actions.
 
 ## Accessibility
 
-- **Live updates**: The countdown updates every second with current values
-- **Completion state**: A `.complete` CSS class is added to the host element when the countdown finishes, allowing for visual feedback
-- **Labels**: Each time segment (days, hours, minutes, seconds) has a descriptive label below the digits
-- **Screen readers**: Segment labels provide context for the displayed numbers
+- Live updates every second with current values
+- A `.complete` CSS class is added to the host element when the countdown finishes
+- Each time segment has a descriptive label below the digits
+- Segment labels provide context for screen readers

package/docs/components/cropper.md

@@ -1,8 +1,8 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/cropper.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/cropper.md -->
 
 # Cropper Component
 
-The cropper component provides an image cropping tool with a draggable and resizable crop area, rotation, zoom controls, optional aspect ratio locking, and a rule-of-thirds grid overlay. It outputs cropped images as Blob objects in PNG, JPEG, or WebP format.
+An image cropping tool with a draggable and resizable crop area, rotation, zoom controls, optional aspect ratio locking, and a rule-of-thirds grid overlay. Outputs cropped images as Blob objects in PNG, JPEG, or WebP format.
 
 ## Table of Contents
 - [Properties](#properties)
@@ -31,7 +31,7 @@ The cropper component provides an image cropping tool with a draggable and resiz
 | `crop()` | -- | `Promise<Blob \| null>` | Produce a cropped image Blob from the current crop area |
 | `rotate()` | `degrees: number` | `void` | Rotate the image by the given degrees (cumulative) |
 | `zoom()` | `level: number` | `void` | Set the zoom level (range: 0.1 to 10) |
-| `reset()` | -- | `void` | Reset rotation, zoom, and crop area to their defaults |
+| `reset()` | -- | `void` | Reset rotation, zoom, and crop area to defaults |
 
 ## Events
 
@@ -55,13 +55,11 @@ The cropper component provides an image cropping tool with a draggable and resiz
 
 ## CSS Parts
 
-Style internal elements from outside the shadow DOM using `::part()`.
-
-| Part | Element | Description |
-|------|---------|-------------|
-| `base` | `<div>` | Outer cropper container |
-| `image-container` | `<div>` | Image display area |
-| `crop-area` | `<div>` | Draggable/resizable crop region with handles |
+| Part | Description |
+|------|-------------|
+| `base` | Outer cropper container |
+| `image-container` | Image display area |
+| `crop-area` | Draggable/resizable crop region with handles |
 
 ```css
 snice-cropper::part(base) {
@@ -103,7 +101,7 @@ Load an image and let the user crop it freely.
     const blob = await cropper.crop();
     if (blob) {
       const url = URL.createObjectURL(blob);
-      window.open(url); // Preview the cropped image
+      window.open(url);
     }
   }
   window.handleCrop = handleCrop;
@@ -141,7 +139,7 @@ Lock to a widescreen aspect ratio for video thumbnails or banner images.
 Use the `rotate()` and `zoom()` methods for image adjustment.
 
 ```html
-<snice-cropper id="editor" src="/photos/vacation.jpg" aspect-ratio="0"></snice-cropper>
+<snice-cropper id="editor" src="/photos/vacation.jpg"></snice-cropper>
 
 <div style="display: flex; gap: 0.5rem; margin-top: 1rem;">
   <button onclick="document.getElementById('editor').rotate(-90)">Rotate Left</button>
@@ -173,7 +171,7 @@ Track the crop area position and dimensions in real time.
 
 ## Accessibility
 
-- **Drag interaction**: The crop area can be repositioned by dragging, and resized via 8 corner and edge handles
-- **Rule-of-thirds grid**: An overlay grid helps with composition alignment
-- **Visual feedback**: A dark mask outside the crop area clearly indicates the cropped region
-- **Aspect ratio enforcement**: When `aspectRatio` is set, resize handles maintain the locked ratio automatically
+- Drag interaction: The crop area can be repositioned by dragging, and resized via 8 corner and edge handles
+- Rule-of-thirds grid overlay helps with composition alignment
+- Dark mask outside the crop area clearly indicates the cropped region
+- When `aspectRatio` is set, resize handles maintain the locked ratio automatically

package/docs/components/data-card.md

@@ -1,4 +1,4 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/data-card.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/data-card.md -->
 
 # Data Card
 `<snice-data-card>`
@@ -13,25 +13,13 @@ A key-value detail panel for displaying structured data with grouped sections, m
 - [CSS Parts](#css-parts)
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
-
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/data-card/snice-data-card';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-data-card.min.js"></script>
-```
+- [Accessibility](#accessibility)
 
 ## Properties
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `fields` | `DataCardField[]` | `[]` | Array of field objects |
+| `fields` | `DataCardField[]` | `[]` | Array of field objects (JS only, no attribute) |
 | `editable` | `boolean` | `false` | Enable global edit mode |
 | `variant` | `'default' \| 'horizontal' \| 'compact'` | `'default'` | Layout variant |
 
@@ -107,6 +95,12 @@ import 'snice/components/data-card/snice-data-card';
 </script>
 ```
 
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-data-card.min.js"></script>
+```
+
 ## Examples
 
 ### Value Types
@@ -203,3 +197,10 @@ Use `getValues()` and `setValues()` for programmatic data access.
   card.setValues({ Name: 'Jane', Age: 25 });
 </script>
 ```
+
+## Accessibility
+
+- Edit mode inputs support Enter to save and Escape to cancel
+- Edit toggle button is hidden when no fields are editable
+- Links open in new tabs with `rel="noopener"` for security
+- Use `slot="title"` to provide a descriptive heading for the card

package/docs/components/date-picker.md

@@ -1,22 +1,19 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/date-picker.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/date-picker.md -->
 
 # Date Picker
 `<snice-date-picker>`
 
-Calendar-based date input with format options and validation.
+Calendar-based date input with format options and validation. Form-associated custom element.
 
-## 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>
-```
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Keyboard Navigation](#keyboard-navigation)
+- [Accessibility](#accessibility)
 
 ## Properties
 
@@ -36,26 +33,26 @@ import 'snice/components/date-picker/snice-date-picker';
 | `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 |
+| `min` | `min` | `string` | `''` | Minimum selectable date (ISO format) |
+| `max` | `max` | `string` | `''` | Maximum selectable date (ISO format) |
 | `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) |
+| `firstDayOfWeek` | `first-day-of-week` | `number` | `0` | First day of week (0=Sun, 1=Mon) |
 
 ## 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 |
+| `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 |
+| `goToToday()` | -- | Selects today's date |
+| `checkValidity()` | -- | Returns input validity |
+| `reportValidity()` | -- | Reports input validity |
 | `setCustomValidity()` | `message: string` | Sets custom validation message |
 
 ## Events
@@ -93,6 +90,12 @@ import 'snice/components/date-picker/snice-date-picker';
 <snice-date-picker label="Select date"></snice-date-picker>
 ```
 
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-date-picker.min.js"></script>
+```
+
 ## Examples
 
 ### Variants
@@ -204,3 +207,20 @@ dp.addEventListener('datepicker-change', (e) => {
   console.log('ISO:', e.detail.iso);
 });
 ```
+
+## Keyboard Navigation
+
+- **Enter / Space** on input opens the calendar
+- **Escape** closes the calendar and returns focus to input
+- **Tab** navigates between focusable elements in the calendar
+- Calendar days are focusable buttons with aria-labels
+
+## Accessibility
+
+- Form-associated custom element with `ElementInternals`
+- Calendar popup uses `popover="manual"` for proper layering
+- Day buttons include `aria-label` with formatted date
+- Input supports `aria-invalid` when in invalid state
+- Required fields show visual indicator on the label
+- Calendar toggle button has `aria-label="Open calendar"`
+- Clear button has `aria-label="Clear"`

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

@@ -1,39 +1,130 @@
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/date-range-picker.md -->
+
 # Date Range Picker
+`<snice-date-range-picker>`
+
+Date range selection with an interactive calendar dropdown, optional presets sidebar, year picker, and support for multiple date formats. Form-associated custom element.
+
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+|----------|-----------|------|---------|-------------|
+| `start` | `start` | `string` | `''` | Start date (formatted string or ISO) |
+| `end` | `end` | `string` | `''` | End date (formatted string or ISO) |
+| `size` | `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Input size |
+| `variant` | `variant` | `'outlined' \| 'filled' \| 'underlined'` | `'outlined'` | Input style variant |
+| `format` | `format` | `DateRangeFormat` | `'mm/dd/yyyy'` | Date display format |
+| `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 component |
+| `readonly` | `readonly` | `boolean` | `false` | Makes the component read-only |
+| `loading` | `loading` | `boolean` | `false` | Shows loading spinner |
+| `required` | `required` | `boolean` | `false` | Marks as required |
+| `invalid` | `invalid` | `boolean` | `false` | Shows error styling |
+| `clearable` | `clearable` | `boolean` | `false` | Shows clear button |
+| `min` | `min` | `string` | `''` | Minimum selectable date (ISO format) |
+| `max` | `max` | `string` | `''` | Maximum selectable date (ISO format) |
+| `name` | `name` | `string` | `''` | Form field name |
+| `columns` | `columns` | `number` | `1` | Calendar columns (1 or 2) |
+| `firstDayOfWeek` | `first-day-of-week` | `number` | `0` | First day of week (0=Sun) |
+| `presets` | N/A | `DateRangePreset[]` | `[]` | Preset ranges (JS only) |
+| `showCalendar` | `show-calendar` | `boolean` | `false` | Calendar visibility |
+
+### DateRangePreset Object
 
-The `<snice-date-range-picker>` component provides date range selection with an interactive calendar dropdown, optional presets sidebar, year picker, and support for multiple date formats.
+```typescript
+interface DateRangePreset {
+  label: string;
+  start: Date;
+  end: Date;
+}
+```
+
+### Supported Formats
+
+`'mm/dd/yyyy'` | `'dd/mm/yyyy'` | `'yyyy-mm-dd'` | `'yyyy/mm/dd'` | `'dd-mm-yyyy'` | `'mm-dd-yyyy'` | `'mmmm dd, yyyy'`
+
+## Methods
+
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `open()` | -- | Open the calendar dropdown |
+| `close()` | -- | Close the calendar dropdown |
+| `clear()` | -- | Clear both dates |
+| `focus()` | -- | Focus the input |
+| `blur()` | -- | Blur the input |
+| `selectRange()` | `start: Date, end: Date` | Programmatically select a date range |
+| `checkValidity()` | -- | Check form validity |
+| `reportValidity()` | -- | Report form validity |
+| `setCustomValidity()` | `message: string` | Set custom validation message |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `daterange-change` | `{ start, end, startDate, endDate, startIso, endIso }` | Range selected or cleared |
+| `daterange-open` | `{ dateRangePicker }` | Calendar opened |
+| `daterange-close` | `{ dateRangePicker }` | Calendar closed |
+| `daterange-clear` | `{ dateRangePicker }` | Range cleared |
+| `daterange-preset` | `{ label, start, end, dateRangePicker }` | Preset selected |
+| `daterange-focus` | `{ dateRangePicker }` | Input focused |
+| `daterange-blur` | `{ dateRangePicker }` | Input blurred |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `input` | The text input element |
+| `calendar-toggle` | Calendar icon button |
+| `clear` | Clear button |
+| `spinner` | Loading spinner |
+| `calendar` | Calendar dropdown container |
+| `helper-text` | Helper text element |
+| `error-text` | Error text element |
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/date-range-picker/snice-date-range-picker';
+```
+
 ```html
-<snice-date-range-picker
-  label="Select Date Range"
-  clearable
-></snice-date-range-picker>
+<snice-date-range-picker label="Select Date Range" clearable></snice-date-range-picker>
 ```
 
-## Dual Column Calendar
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-date-range-picker.min.js"></script>
+```
+
+## Examples
+
+### Dual Column Calendar
 
-Show two months side-by-side for easier range selection:
+Use the `columns` attribute to show two months side-by-side for easier range selection.
 
 ```html
-<snice-date-range-picker
-  label="Booking Dates"
-  columns="2"
-  clearable
-></snice-date-range-picker>
+<snice-date-range-picker label="Booking Dates" columns="2" clearable></snice-date-range-picker>
 ```
 
-## Presets
+### Presets
 
-Add quick-select preset buttons to the calendar sidebar. Presets are set via JavaScript since they contain Date objects:
+Set the `presets` property via JavaScript to add quick-select preset buttons to the calendar sidebar.
 
 ```html
-<snice-date-range-picker
-  id="my-picker"
-  label="Report Period"
-  columns="2"
-  clearable
-></snice-date-range-picker>
+<snice-date-range-picker id="my-picker" label="Report Period" columns="2" clearable></snice-date-range-picker>
 ```
 
 ```typescript
@@ -48,32 +139,36 @@ picker.presets = [
 
 Hovering over a preset shows a dashed preview of the range on the calendar. Clicking a preset selects both dates and closes the calendar.
 
-## Date Formats
+### Date Formats
+
+Use the `format` attribute to control how dates are displayed.
 
 ```html
-<snice-date-range-picker format="mm/dd/yyyy"></snice-date-range-picker>   <!-- 03/06/2026 -->
-<snice-date-range-picker format="dd/mm/yyyy"></snice-date-range-picker>   <!-- 06/03/2026 -->
-<snice-date-range-picker format="yyyy-mm-dd"></snice-date-range-picker>   <!-- 2026-03-06 -->
-<snice-date-range-picker format="mmmm dd, yyyy"></snice-date-range-picker> <!-- March 06, 2026 -->
+<snice-date-range-picker format="mm/dd/yyyy"></snice-date-range-picker>
+<snice-date-range-picker format="dd/mm/yyyy"></snice-date-range-picker>
+<snice-date-range-picker format="yyyy-mm-dd"></snice-date-range-picker>
+<snice-date-range-picker format="mmmm dd, yyyy"></snice-date-range-picker>
 ```
 
 The `start` and `end` attributes accept ISO format (`yyyy-mm-dd`) regardless of the display format.
 
-## Sizes and Variants
+### Sizes and Variants
+
+Use the `size` and `variant` attributes to control the input appearance.
 
 ```html
-<!-- Sizes -->
 <snice-date-range-picker size="small"></snice-date-range-picker>
 <snice-date-range-picker size="medium"></snice-date-range-picker>
 <snice-date-range-picker size="large"></snice-date-range-picker>
 
-<!-- Variants -->
 <snice-date-range-picker variant="outlined"></snice-date-range-picker>
 <snice-date-range-picker variant="filled"></snice-date-range-picker>
 <snice-date-range-picker variant="underlined"></snice-date-range-picker>
 ```
 
-## States
+### States
+
+Use `required`, `invalid`, `disabled`, `readonly`, and `loading` for different interaction states.
 
 ```html
 <snice-date-range-picker required helper-text="Required field"></snice-date-range-picker>
@@ -83,11 +178,11 @@ The `start` and `end` attributes accept ISO format (`yyyy-mm-dd`) regardless of
 <snice-date-range-picker loading></snice-date-range-picker>
 ```
 
-## Year Picker
+### Year Picker
 
 Click the year in the calendar header to open a 12-year grid. Navigate between year ranges with the arrow buttons, then click a year to return to the day view.
 
-## Form Integration
+### Form Integration
 
 The component is form-associated. When used inside a `<form>` with a `name` attribute, it submits two values: `{name}-start` and `{name}-end`.
 
@@ -98,63 +193,21 @@ The component is form-associated. When used inside a `<form>` with a `name` attr
 </form>
 ```
 
-## Properties
-
-| Property | Attribute | Type | Default | Description |
-|----------|-----------|------|---------|-------------|
-| `start` | `start` | `string` | `''` | Start date (formatted string or ISO) |
-| `end` | `end` | `string` | `''` | End date (formatted string or ISO) |
-| `size` | `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Input size |
-| `variant` | `variant` | `'outlined' \| 'filled' \| 'underlined'` | `'outlined'` | Input style variant |
-| `format` | `format` | `DateRangeFormat` | `'mm/dd/yyyy'` | Date display format |
-| `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 component |
-| `readonly` | `readonly` | `boolean` | `false` | Makes the component read-only |
-| `loading` | `loading` | `boolean` | `false` | Shows loading spinner |
-| `required` | `required` | `boolean` | `false` | Marks as required |
-| `invalid` | `invalid` | `boolean` | `false` | Shows error 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 |
-| `columns` | `columns` | `number` | `1` | Calendar columns (1 or 2) |
-| `firstDayOfWeek` | `first-day-of-week` | `number` | `0` | First day of week (0=Sun) |
-| `presets` | N/A | `DateRangePreset[]` | `[]` | Preset ranges (JS only) |
-
-## Events
+### Event Handling
 
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `daterange-change` | `{ start, end, startDate, endDate, startIso, endIso }` | Range selected or cleared |
-| `daterange-open` | `{ dateRangePicker }` | Calendar opened |
-| `daterange-close` | `{ dateRangePicker }` | Calendar closed |
-| `daterange-clear` | `{ dateRangePicker }` | Range cleared |
-| `daterange-preset` | `{ label, start, end }` | Preset selected |
+Listen for range changes using the `daterange-change` event.
 
-## Methods
-
-| Method | Description |
-|--------|-------------|
-| `open()` | Open the calendar dropdown |
-| `close()` | Close the calendar dropdown |
-| `clear()` | Clear both dates |
-| `focus()` | Focus the input |
-| `blur()` | Blur the input |
-| `selectRange(start, end)` | Programmatically select a date range |
-| `checkValidity()` | Check form validity |
-| `reportValidity()` | Report form validity |
-| `setCustomValidity(msg)` | Set custom validation message |
+```typescript
+picker.addEventListener('daterange-change', (e) => {
+  console.log('Start:', e.detail.startIso, 'End:', e.detail.endIso);
+});
+```
 
-## CSS Parts
+## Accessibility
 
-| Part | Description |
-|------|-------------|
-| `input` | The text input element |
-| `calendar-toggle` | Calendar icon button |
-| `clear` | Clear button |
-| `spinner` | Loading spinner |
-| `calendar` | Calendar dropdown container |
-| `error-text` | Error text element |
-| `helper-text` | Helper text element |
+- Form-associated custom element with `ElementInternals`
+- Calendar popup uses `popover="manual"` for proper layering
+- Navigation buttons have `aria-label` attributes
+- Required fields show visual indicator on the label
+- Calendar toggle button has `aria-label="Toggle calendar"`
+- Clear button has `aria-label="Clear"`