@reliability-design/web 1.4.9 → 1.4.10

package/dist/components/rel-range-picker/README.md

@@ -1,171 +1,194 @@
-# rel-range-picker
-
-`<rel-range-picker>` is the date-range form field of the Reliability Design System (Figma "Date Range Picker"). It is a text field you can type a "from → to" range into, backed by a two-pane panel: quick-select presets with single-key shortcuts and From / To readouts on the left, a month grid with live range preview on the right, and a Reset / Cancel / Apply footer. The grid and presets edit a draft; only Apply (or typed entry / clear) commits `from`/`to` as ISO `YYYY-MM-DD` strings. Use it for filters and reports that need a start and an end. For a single date use `<rel-date-picker>`, for an always-visible grid use `<rel-calendar>`.
-
-## Usage
-
-```html
-<!-- Basic -->
-<rel-range-picker placeholder="Select date range"></rel-range-picker>
-
-<!-- Preselected range with a clear icon -->
-<rel-range-picker from="2026-01-05" to="2026-01-09" clearable></rel-range-picker>
-
-<!-- Bounded, Monday-first grid -->
-<rel-range-picker min-date="2026-01-01" max-date="2026-12-31" week-start="mon"></rel-range-picker>
-
-<!-- Centred popup with a dimmed backdrop instead of an anchored popover -->
-<rel-range-picker mode="popup"></rel-range-picker>
-
-<!-- Icon-only trigger (no typed entry, no clear icon) -->
-<rel-range-picker trigger-variant="icon" placeholder="Filter by date"></rel-range-picker>
-
-<!-- Sizing the host: explicit width, or fill the parent -->
-<rel-range-picker width="320px" min-width="240px"></rel-range-picker>
-<rel-range-picker fullwidth></rel-range-picker>
-
-<!-- Disabled -->
-<rel-range-picker from="2026-01-05" to="2026-01-09" disabled></rel-range-picker>
-```
-
-```js
-const picker = document.querySelector("rel-range-picker");
-
-picker.addEventListener("rel-change", (e) => {
-  e.detail.from;  // "2026-01-05" ("" when cleared)
-  e.detail.to;    // "2026-01-09"
-  e.detail.label; // "01/05/2026 → 01/09/2026"
-});
-picker.addEventListener("rel-open-change", (e) => e.detail.open);
-picker.addEventListener("rel-blur", () => {/* run validation */});
-
-picker.displayLabel; // same formatted label for the committed range
-```
-
-### Typed entry
-
-With the default trigger the field is editable and commits on Enter or when focus leaves the component. Two dates are separated by `→`, `..`, a spaced `-`, or the word `to` (`2026-01-05 to 2026-01-09`, `21/7 .. 28/7`, `t - t+7`); a single date gives a one-day range and a reversed pair is normalised so `from` ≤ `to`. Each side accepts everything `rel-date-picker` parses — ISO, numeric, month names, partial `21/7` / `21`, and the `t` / `today` / `t±N` shortcuts — with ambiguous `a/b` always read as month/day, matching the `MM/DD/YYYY` display. Unparseable text shows "Invalid date range" and a date outside `min-date`/`max-date` shows "Date not available"; the text stays for correction and the committed range is untouched. Escape reverts the text; committing an empty field clears the range like the clear icon.
-
-### Presets and shortcuts
-
-The left pane lists Today (`T`), Tomorrow (`M`), Yesterday (`Y`), This Week (`W`), Next Week (`N`), Next 7 Days (`7`) and Next 30 Days (`3`), one per row. Weeks in the presets always run Sunday–Saturday regardless of `week-start`. While the panel is open, pressing the key (no modifier, focus not in an editable field) selects that preset; a preset only fills the draft — Apply still commits it. Following Figma's ".Suggested Range" row, the key is not printed on the row: each preset carries it as `aria-keyshortcuts` and a `title` tooltip instead.
-
-> **Changed in this release.** The `Before Today` preset (`B`, `1970-01-01` → yesterday) has been replaced by `Yesterday` (`Y`, yesterday → yesterday) to match Figma. The `B` key no longer selects anything; use typed entry (for example `1970-01-01 to t-1`) if you need the old open-ended range.
-
-<!-- readme-gen:start -->
-
-<!-- Generated from rel-range-picker.ts — do not edit; run readme-generate.mjs -->
-
-## API
-
-### Attributes / Properties
-
-| Property | Attribute | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| `from` | `from` | `string` | `""` | Committed range start as an ISO `YYYY-MM-DD` string; empty string when no range is set. |
-| `to` | `to` | `string` | `""` | Committed range end as an ISO `YYYY-MM-DD` string; empty string when no range is set. Always ≥ `from`. |
-| `locale` | `locale` | `string` | `"en-US"` | Locale used to match month names in typed input; the visible trigger text and calendar labels are always `en-US` (`MM/DD/YYYY`). |
-| `weekStart` | `week-start` | `"mon" \| "sun"` | `"sun"` | First column of the calendar grid: `"sun"` (default) or `"mon"`. Presets always compute weeks Sunday–Saturday. |
-| `minDate` | `min-date` | `string` | `""` | Earliest selectable date (ISO `YYYY-MM-DD`); earlier days are disabled and typed ranges starting before it are rejected. |
-| `maxDate` | `max-date` | `string` | `""` | Latest selectable date (ISO `YYYY-MM-DD`); later days are disabled and typed ranges ending after it are rejected. |
-| `disabled` | `disabled` | `boolean` | `false` | Disables the trigger, the icons and the panel controls; the host dims to 60% opacity. Reflected. |
-| `open` | `open` | `boolean` | `false` | Whether the panel is open. Setting it directly shows/hides the panel but does not seed the draft from `from`/`to` or fire `rel-open-change` — user interaction does both. Reflected. |
-| `mode` | `mode` | `"popover" \| "popup"` | `"popover"` | `popover` anchors the panel below the trigger; `popup` centres it in the viewport behind a dimmed backdrop (part `overlay`). |
-| `width` | `width` | `string` | `""` | CSS width applied to the host (any CSS length, e.g. `320px`); empty leaves the intrinsic width. |
-| `minWidth` | `min-width` | `string` | `""` | CSS `min-width` applied to the host. |
-| `maxWidth` | `max-width` | `string` | `""` | CSS `max-width` applied to the host. |
-| `height` | `height` | `string` | `""` | CSS height applied to the host. |
-| `minHeight` | `min-height` | `string` | `""` | CSS `min-height` applied to the host. |
-| `maxHeight` | `max-height` | `string` | `""` | CSS `max-height` applied to the host. |
-| `placeholder` | `placeholder` | `string` | `"Select date range"` | Placeholder shown in the empty field; also the accessible name of the input (and of the icon trigger while no range is set). |
-| `triggerVariant` | `trigger-variant` | `"default" \| "icon"` | `"default"` | `default` renders the text field; `icon` renders a single calendar icon button instead (no typed entry, no clear button, parts `trigger`/`value` absent). |
-| `clearable` | `clearable` | `boolean` | `false` | Shows a clear (×) icon while a range is set; clearing fires `rel-change` with empty `from`/`to`. Only with the default trigger. |
-| `fullWidth` | `fullwidth` | `boolean` | `false` | Stretches the host to fill its parent's width (attribute `fullwidth`), mirroring rel-time-picker / rel-date-picker. Off by default so the existing intrinsic-width (`inline-block`) rendering is unchanged. Reflected. |
-| `size` | `size` | `"small" \| "medium" \| "large" \| "sm" \| "md" \| "lg"` | `"medium"` | Trigger height on the shared field scale — `small` 32 / `medium` 40 / `large` 48px border-box — matching rel-textfield, rel-date-picker and rel-time-picker so the four align in a form row. Also ramps the trigger's text and inline padding. The panel is unaffected: Figma specifies one panel size. `sm` / `md` / `lg` are alternative spellings and stay supported — normalised to the full words, not deprecated. Reflected. |
-
-### Public fields / accessors
-
-| Name | Type | Description |
-| --- | --- | --- |
-| `displayLabel` | `string` | Formatted "MM/DD/YYYY → MM/DD/YYYY" (or single date / "") for the current committed `from`/`to`. |
-
-## Events
-
-| Event | Detail | Bubbles / composed | Description |
-| --- | --- | --- | --- |
-| `rel-blur` | — | bubbles / composed | Fired when the text input loses focus (before any typed text is committed). No detail. |
-| `rel-change` | `{ from: this.from, to: this.to, label: this.displayLabel } / { from: "", to: "", label: "" }` | bubbles / composed | Fired when the committed range changes — Apply, typed entry, or clear. Detail: `{ from: string, to: string, label: string }` (ISO dates and the formatted `MM/DD/YYYY → MM/DD/YYYY` label; all empty strings when cleared). |
-| `rel-open-change` | `{ open: true } / { open: false }` | bubbles / composed | Fired when the panel opens or closes (open, Cancel, Escape, outside click, Apply). Detail: `{ open: boolean }`. |
-
-## Slots
-
-| Slot | Description |
-| --- | --- |
-| — | This element has no slots. |
-
-## CSS Parts
-
-| Part | Description |
-| --- | --- |
-| `trigger` | The field box that wraps the text input and the clear/calendar icons (default trigger variant only) |
-| `value` | The editable text input inside the trigger |
-| `overlay` | The full-screen backdrop rendered in `mode="popup"` while open |
-| `panel` | The floating panel (`role="dialog"`) holding presets and calendar |
-| `list` | The preset column and the day grid |
-| `option` | Each quick-select preset button |
-| `action` | The header's previous and next buttons; they step a month, a year or a 12-year page depending on which view the panel is showing |
-| `footer` | The Reset / Cancel / Apply button row |
-
-<!-- readme-gen:end -->
-
-
-## CSS Custom Properties
-
-| Custom property | Default | Description |
-| --- | --- | --- |
-| `--rel-overlay-fallback-z` | `1001` | z-index of the panel on the **no-Popover-API fallback path only**. Wherever the browser top layer is available the panel is promoted into it and this value is inert, because top-layer elements are not in the page stacking order at all. Shared with the other overlays (select, autocomplete, the three pickers) so the whole family can be moved from one place. |
-## Accessibility
-
-- Default trigger: the input is a `role="combobox"` with `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls` pointing at the panel, `aria-label` = `placeholder`, `aria-invalid` while typed text is in error and `aria-describedby` pointing at the error line. The icon buttons are labelled "Clear date range" and "Open date range panel" (with `aria-expanded`).
-- Icon trigger (`trigger-variant="icon"`): a `<rel-button>` with `aria-haspopup="dialog"`, `aria-expanded`, and an `aria-label` of the current range label or the `placeholder`.
-- The panel is a `role="dialog"` named "Select date range". Presets sit in a `role="group"` named "Quick date selections"; each preset button carries `aria-pressed` plus an `aria-keyshortcuts` naming its single-key shortcut. The From / To readouts are groups named "From date" / "To date". Focus is not trapped inside the panel.
-- The calendar is a `role="grid"` named "Select date range" with `role="columnheader"` weekday names, `role="row"` weeks and `role="gridcell"` days whose `aria-label` is the full long date plus ", range start" / ", range end" for the endpoints; `aria-selected` is true for the endpoints and every day between them, `aria-disabled` marks unavailable days. Exactly one cell is a Tab stop (last arrowed date → draft start → today → first enabled day).
-- Focus: opening the panel does not move focus; Escape closes it and returns focus to the input. Keyboard navigation in the grid previews the range exactly like mouse hover does.
-- Screen readers hear "<Month> <Year>" after every month change and "From date MM/DD/YYYY" / "To date MM/DD/YYYY" when an endpoint is chosen, through the shared `announce()` region (`utils/announce.ts`).
-
-| Key (in the field) | Action |
-| --- | --- |
-| Enter | Nothing typed: open the panel. Text typed: commit it |
-| ArrowDown | Open the panel |
-| Escape | Revert uncommitted text; close the panel and refocus the input |
-
-| Key (panel open, focus outside an editable field) | Action |
-| --- | --- |
-| T / M / Y / W / N / 7 / 3 | Select the matching preset into the draft |
-| Escape | Cancel: discard the draft, close, refocus the input |
-
-| Key (in the grid) | Action |
-| --- | --- |
-| ArrowLeft / ArrowRight | Previous / next day (switches month at the edge) |
-| ArrowUp / ArrowDown | Same weekday one week earlier / later |
-| Home / End | First / last day of the row, honouring `week-start` |
-| PageUp / PageDown | Same day previous / next month |
-| Shift + PageUp / Shift + PageDown | Same day previous / next year |
-| Enter / Space | Pick the day as range start, then as range end |
-
-## Notes / Edge Cases
-
-- **The header month and year are buttons.** Clicking the month opens a 12-month grid; clicking the year opens a 12-year page that pages back indefinitely with the chevrons, so a date years in the past is a few clicks rather than a few dozen. Picking a year drills to Months, picking a month returns to the day grid. The chevrons step whatever the current view shows — a month, a year or a whole page — and the panel always reopens on the day grid.
-- **Navigating does not select.** The switcher moves the VIEW only: it writes to the month and year on display and never to the draft or the committed range, so Reset, Cancel and Apply behave exactly as they did, and reopening still seeds the view from the committed start date.
-- Draft vs committed: grid picks and presets only change the draft shown in the From / To readouts. Apply commits it (fires `rel-change`, closes); Cancel, Escape, an outside click, or the popup backdrop discard it; Reset empties the draft. Reset followed by Apply clears the committed range (`rel-change` with empty strings) — Apply is disabled only when both the draft and the committed range are empty.
-- Second-click ordering: picking a day before the current draft start makes it the new start and the old start the end.
-- Setting `open = true` from code shows the panel but neither seeds the draft from `from`/`to` nor fires `rel-open-change`; only user interaction does both.
-- The trigger text, From / To readouts, month names and day labels are always rendered in `en-US` (`MM/DD/YYYY`); `locale` only affects month-name matching in typed input.
-- Leading and trailing cells of adjacent months are visible but never selectable, and render at 40% label opacity (Figma "Day of a week = Other Month"). Today gets a 1 px brand ring; weekend cells render at 70% opacity (Figma "Day of a week = Weekend") unless they are range endpoints.
-- Range styling follows Figma ".Date Range Days": the selected run is an `elevated-1` band across the full cell, rounded at the two ends (a one-day range is a single rounded pill), and the two endpoints are `inverse-2` discs with inverse semibold labels. Days between the endpoints keep their normal label on the band.
-- The panel (and the popup backdrop) is promoted to the browser top layer (`popover="manual"`), so it works inside `rel-modal` / `rel-drawer` and above transformed or `overflow: hidden` ancestors. In `popover` mode it anchors below the host, flips above when there is no room, stays 8 px inside the viewport, repositions on resize and **closes on an outside scroll** (changed in 1.4.9 — it used to track the trigger, leaving the panel over sticky page furniture once the trigger had scrolled away); scrolling inside the panel does not close it. In `popup` mode it is fixed-centred behind a 40% black backdrop (part `overlay`) whose click cancels. It never exceeds the viewport and scrolls internally.
-- `width`, `min-width`, `max-width`, `height`, `min-height` and `max-height` are copied to the host's inline style on every update, so they override stylesheet rules on the host.
-- The icon trigger has no typed entry, no clear icon and no error line; parts `trigger` and `value` are not rendered in that variant.
-- There is no helper-text or external error API; the only text below the field is the typed-entry error.
-- The footer buttons are `<rel-button>` instances — `ghost` for Reset, `secondary` for Cancel and `primary tone="brand"` for Apply — and the icon trigger uses `<rel-button>` with `<rel-icon name="calendar-range">`, so `@reliability-design/icons` is loaded by this component.
-- The host is `inline-block` with an intrinsic width by default; `fullwidth` switches it to a block that fills the parent.
+# rel-range-picker
+
+`<rel-range-picker>` is the date-range form field of the Reliability Design System (Figma "Date Range Picker"). It is a text field you can type a "from → to" range into, backed by a two-pane panel: quick-select presets with single-key shortcuts and editable From / To inputs on the left, a month grid with live range preview on the right, and a Reset / Cancel / Apply footer. The grid and presets edit a draft; only Apply (or typed entry / clear) commits `from`/`to` as ISO `YYYY-MM-DD` strings. Use it for filters and reports that need a start and an end. For a single date use `<rel-date-picker>`, for an always-visible grid use `<rel-calendar>`.
+
+## Usage
+
+```html
+<!-- Basic -->
+<rel-range-picker placeholder="Select date range"></rel-range-picker>
+
+<!-- Preselected range with a clear icon -->
+<rel-range-picker from="2026-01-05" to="2026-01-09" clearable></rel-range-picker>
+
+<!-- Bounded, Monday-first grid -->
+<rel-range-picker min-date="2026-01-01" max-date="2026-12-31" week-start="mon"></rel-range-picker>
+
+<!-- Centred popup with a dimmed backdrop instead of an anchored popover -->
+<rel-range-picker mode="popup"></rel-range-picker>
+
+<!-- Icon-only trigger (no typed entry, no clear icon) -->
+<rel-range-picker trigger-variant="icon" placeholder="Filter by date"></rel-range-picker>
+
+<!-- Sizing the host: explicit width, or fill the parent -->
+<rel-range-picker width="320px" min-width="240px"></rel-range-picker>
+<rel-range-picker full-width></rel-range-picker>
+
+<!-- Disabled -->
+<rel-range-picker from="2026-01-05" to="2026-01-09" disabled></rel-range-picker>
+```
+
+```js
+const picker = document.querySelector("rel-range-picker");
+
+picker.addEventListener("rel-change", (e) => {
+  e.detail.from;  // "2026-01-05" ("" when cleared)
+  e.detail.to;    // "2026-01-09"
+  e.detail.label; // "01/05/2026 → 01/09/2026"
+});
+picker.addEventListener("rel-open-change", (e) => e.detail.open);
+picker.addEventListener("rel-blur", () => {/* run validation */});
+
+picker.displayLabel; // same formatted label for the committed range
+```
+
+### Typed entry
+
+With the default trigger the field is editable and commits on Enter or when focus leaves the component. Two dates are separated by `→`, `..`, a spaced `-`, or the word `to` (`2026-01-05 to 2026-01-09`, `21/7 .. 28/7`, `t - t+7`); a single date gives a one-day range and a reversed pair is normalised so `from` ≤ `to`. Each side accepts everything `rel-date-picker` parses — ISO, numeric, month names, partial `21/7` / `21`, and the `t` / `today` / `t±N` shortcuts — with ambiguous `a/b` always read as month/day, matching the `MM/DD/YYYY` display. Unparseable text shows "Invalid date range" and a date outside `min-date`/`max-date` shows "Date not available"; the text stays for correction and the committed range is untouched. Escape reverts the text; committing an empty field clears the range like the clear icon.
+
+### Presets and shortcuts
+
+The left pane lists Today (`T`), Tomorrow (`M`), Yesterday (`Y`), This Week (`W`), Next Week (`N`), Next 7 Days (`7`) and Next 30 Days (`3`), one per row. Weeks in the presets always run Sunday–Saturday regardless of `week-start`. While the panel is open, pressing the key (no modifier, focus not in an editable field) selects that preset; a preset only fills the draft — Apply still commits it. Following Figma's ".Suggested Range" row, the key is not printed on the row: each preset carries it as `aria-keyshortcuts` and a `title` tooltip instead.
+
+<!-- @unreleased-begin 1.5.0 -->
+New in 1.5.0: a preset whose range equals the picked days shows as selected (picking next Sunday to Saturday selects Next Week). Apply stays disabled while only a start day is picked. After a mouse click on the start day, the To box draws its hover border to show it is next; keyboard focus stays on the day in the grid.
+<!-- @unreleased-end -->
+
+> **Changed in this release.** The `Before Today` preset (`B`, `1970-01-01` → yesterday) has been replaced by `Yesterday` (`Y`, yesterday → yesterday) to match Figma. The `B` key no longer selects anything; use typed entry (for example `1970-01-01 to t-1`) if you need the old open-ended range.
+
+### Deprecated aliases
+
+```html
+<!-- fullwidth → full-width (since 1.5.0; still works, logs a one-time console notice, removed in 3.0) -->
+<rel-range-picker fullwidth></rel-range-picker>
+<rel-range-picker full-width></rel-range-picker>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-range-picker.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `from` | `from` | `string` | `""` | Committed range start as an ISO `YYYY-MM-DD` string; empty string when no range is set. |
+| `to` | `to` | `string` | `""` | Committed range end as an ISO `YYYY-MM-DD` string; empty string when no range is set. Always ≥ `from`. |
+| `locale` | `locale` | `string` | `"en-US"` | Locale used to match month names in typed input; the visible trigger text and calendar labels are always `en-US` (`MM/DD/YYYY`). |
+| `weekStart` | `week-start` | `"mon" \| "sun"` | `"sun"` | First column of the calendar grid: `"sun"` (default) or `"mon"`. Presets always compute weeks Sunday–Saturday. |
+| `minDate` | `min-date` | `string` | `""` | Earliest selectable date (ISO `YYYY-MM-DD`); earlier days are disabled and typed ranges starting before it are rejected. |
+| `maxDate` | `max-date` | `string` | `""` | Latest selectable date (ISO `YYYY-MM-DD`); later days are disabled and typed ranges ending after it are rejected. |
+| `disabled` | `disabled` | `boolean` | `false` | Disables the trigger, the icons and the panel controls. The field looks like a disabled `rel-textfield`: the whole field at 0.65 opacity, an elevated-2 box with the accent border, and the value and placeholder in `--rel-text-caption` (changed in 1.5.0: it was the enabled look at 60% opacity). Reflected. |
+| `open` | `open` | `boolean` | `false` | Whether the panel is open. Setting it directly shows/hides the panel but does not seed the draft from `from`/`to` or fire `rel-open-change` — user interaction does both. Reflected. |
+| `mode` | `mode` | `"popover" \| "popup"` | `"popover"` | `popover` anchors the panel below the trigger; `popup` centres it in the viewport behind a dimmed backdrop (part `overlay`). |
+| `width` | `width` | `string` | `""` | CSS width applied to the host (any CSS length, e.g. `320px`); empty leaves the intrinsic width. |
+| `minWidth` | `min-width` | `string` | `""` | CSS `min-width` applied to the host. |
+| `maxWidth` | `max-width` | `string` | `""` | CSS `max-width` applied to the host. |
+| `height` | `height` | `string` | `""` | CSS height applied to the host. |
+| `minHeight` | `min-height` | `string` | `""` | CSS `min-height` applied to the host. |
+| `maxHeight` | `max-height` | `string` | `""` | CSS `max-height` applied to the host. |
+| `placeholder` | `placeholder` | `string` | `"Select date range"` | Placeholder shown in the empty field; also the accessible name of the input (and of the icon trigger while no range is set). |
+| `triggerVariant` | `trigger-variant` | `"default" \| "icon"` | `"default"` | `default` renders the text field; `icon` renders a single calendar icon button instead (no typed entry, no clear button, parts `trigger`/`value` absent). |
+| `clearable` | `clearable` | `boolean` | `false` | Shows a clear (×) icon while a range is set; clearing fires `rel-change` with empty `from`/`to`. Only with the default trigger. |
+| `fullWidth` | `full-width` | `boolean` | `false` | Stretches the host to fill its parent's width (attribute `full-width`), mirroring rel-time-picker / rel-date-picker. Off by default so the existing intrinsic-width (`inline-block`) rendering is unchanged. Reflected (as `fullwidth` in 1.x). The `fullwidth` attribute spelling is deprecated (still works; removal targeted for 3.0). |
+| `size` | `size` | `"small" \| "medium" \| "large" \| "sm" \| "md" \| "lg"` | `"medium"` | Trigger height on the shared field scale — `small` 32 / `medium` 40 / `large` 48px border-box — matching rel-textfield, rel-date-picker and rel-time-picker so the four align in a form row. Also ramps the trigger's text and inline padding. The panel is unaffected: Figma specifies one panel size. `sm` / `md` / `lg` are alternative spellings and stay supported — normalised to the full words, not deprecated. Reflected. |
+
+### Public fields / accessors
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `displayLabel` | `string` | Formatted "MM/DD/YYYY → MM/DD/YYYY" (or single date / "") for the current committed `from`/`to`. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `rel-blur` | — | bubbles / composed | Fired when the text input loses focus (before any typed text is committed). No detail. |
+| `rel-change` | `{ from: this.from, to: this.to, label: this.displayLabel } / { from: "", to: "", label: "" }` | bubbles / composed | Fired when the committed range changes — Apply, typed entry, or clear. Detail: `{ from: string, to: string, label: string }` (ISO dates and the formatted `MM/DD/YYYY → MM/DD/YYYY` label; all empty strings when cleared). |
+| `rel-open-change` | `{ open: true } / { open: false }` | bubbles / composed | Fired when the panel opens or closes (open, Cancel, Escape, outside click, Apply). Detail: `{ open: boolean }`. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `trigger` | The field box that wraps the text input and the clear/calendar icons (default trigger variant only) |
+| `value` | The editable text input inside the trigger |
+| `overlay` | The full-screen backdrop rendered in `mode="popup"` while open |
+| `panel` | The floating panel (`role="dialog"`) holding presets and calendar |
+| `list` | The preset column and the day grid |
+| `option` | Each quick-select preset button |
+| `action` | The header's previous and next buttons; they step a month, a year or a 12-year page depending on which view the panel is showing |
+| `unavailable` | Day cells that cannot be picked (outside `min-date` / `max-date`). They are `aria-disabled` and stay focusable, so `:disabled` does not match them; style them with `::part(unavailable)` |
+| `footer` | The Reset / Cancel / Apply button row |
+
+## Tokens / CSS Variables
+
+### Component hooks
+
+Set these on the host (or an ancestor) to customise the element without touching design tokens.
+
+| Custom property | Default | Description |
+| --- | --- | --- |
+| `--rel-overlay-fallback-z` | `1001` | z-index of the panel on the **no-Popover-API fallback path only**. Wherever the browser top layer is available the panel is promoted into it and this value is inert, because top-layer elements are not in the page stacking order at all. Shared with the other overlays (select, autocomplete, the three pickers) so the whole family can be moved from one place. |
+
+<!-- readme-gen:end -->
+
+
+## CSS Custom Properties
+
+| Custom property | Default | Description |
+| --- | --- | --- |
+| `--rel-overlay-fallback-z` | `1001` | z-index of the panel on the **no-Popover-API fallback path only**. Wherever the browser top layer is available the panel is promoted into it and this value is inert, because top-layer elements are not in the page stacking order at all. Shared with the other overlays (select, autocomplete, the three pickers) so the whole family can be moved from one place. |
+## Accessibility
+
+- Default trigger: the input is a `role="combobox"` with `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls` pointing at the panel, `aria-label` = `placeholder`, `aria-invalid` while typed text is in error and `aria-describedby` pointing at the error line. The icon buttons are labelled "Clear date range" and "Open date range panel" (with `aria-expanded`).
+- Icon trigger (`trigger-variant="icon"`): a `<rel-button>` with `aria-haspopup="dialog"`, `aria-expanded`, and an `aria-label` of the current range label or the `placeholder`.
+- The panel is a `role="dialog"` named "Select date range". Presets sit in a `role="group"` named "Quick date selections"; each preset button carries `aria-pressed` plus an `aria-keyshortcuts` naming its single-key shortcut. The From / To boxes are text inputs labelled "From" / "To" (`<label for>`); a box in error carries `aria-invalid="true"` and `aria-describedby` pointing at its error line ("Invalid date" / "Date not available"). Focus is not trapped inside the panel.
+- The calendar is a `role="grid"` named "Select date range" with `role="columnheader"` weekday names, `role="row"` weeks and `role="gridcell"` days whose `aria-label` is the full long date plus ", range start" / ", range end" for the endpoints; `aria-selected` is true for the endpoints and every day between them, `aria-disabled` marks unavailable days. Exactly one cell is a Tab stop: the day last interacted with (arrowed to, clicked or tabbed onto — changed, unreleased: clicks and Tab used to be ignored), else the draft start, else today, else the first enabled day — so Shift+Tab then Tab returns to the day you left. A clicked leading/trailing day keeps the Tab stop itself, since picking one does not move the view. The key map is shared with `rel-date-picker`.
+- Focus: opening the panel does not move focus; Escape closes it and returns focus to the input. Keyboard navigation in the grid previews the range exactly like mouse hover does.
+- Screen readers hear "<Month> <Year>" after every month change and "From date MM/DD/YYYY" / "To date MM/DD/YYYY" when an endpoint is chosen, through the shared `announce()` region (`utils/announce.ts`).
+
+| Key (in the field) | Action |
+| --- | --- |
+| Enter | Nothing typed: open the panel. Text typed: commit it |
+| ArrowDown | Open the panel |
+| Escape | Revert uncommitted text; close the panel and refocus the input |
+
+| Key (panel open, focus outside an editable field) | Action |
+| --- | --- |
+| T / M / Y / W / N / 7 / 3 | Select the matching preset into the draft |
+| Escape | Cancel: discard the draft, close, refocus the input |
+
+| Key (in the grid) | Action |
+| --- | --- |
+| ArrowLeft / ArrowRight | Previous / next day (switches month at the edge) |
+| ArrowUp / ArrowDown | Same weekday one week earlier / later |
+| Home / End | First / last day of the row, honouring `week-start` |
+| PageUp / PageDown | Same day previous / next month (clamped to the month's last day, e.g. 31 Jan → 28 Feb; unreleased fix — it used to overflow to early March) |
+| Shift + PageUp / Shift + PageDown | Same day previous / next year |
+| Enter / Space | Pick the day as range start, then as range end. Does nothing on an unavailable day — the arrows land on those days rather than skipping them |
+
+## Notes / Edge Cases
+
+- **The header month and year are buttons.** Clicking the month opens a 12-month grid; clicking the year opens a 12-year page that pages back indefinitely with the chevrons, so a date years in the past is a few clicks rather than a few dozen. Picking a year drills to Months, picking a month returns to the day grid. The chevrons step whatever the current view shows — a month, a year or a whole page — and the panel always reopens on the day grid.
+- **Navigating does not select.** The switcher moves the VIEW only: it writes to the month and year on display and never to the draft or the committed range, so Reset, Cancel and Apply behave exactly as they did, and reopening still seeds the view from the committed start date.
+- Draft vs committed: grid picks, presets and the panel's From / To inputs only change the draft. Typing in a From / To input commits to the DRAFT on Enter or blur, through the same parser as the trigger (`MM/DD/YYYY`, month names, `t` / `t±N`); the calendar moves to the typed month, a From after the To swaps the two, an empty box clears that side, and an invalid or unavailable date keeps its text with an error. The first Escape in a box with pending text reverts it; the next closes the panel. Apply refuses to commit while a box shows an error (it focuses that box). Apply commits it (fires `rel-change`, closes); Cancel, Escape, an outside click, or the popup backdrop discard it; Reset empties the draft. Reset followed by Apply clears the committed range (`rel-change` with empty strings) — Apply is disabled only when both the draft and the committed range are empty.
+- Second-click ordering: picking a day before the current draft start makes it the new start and the old start the end.
+- Setting `open = true` from code shows the panel but neither seeds the draft from `from`/`to` nor fires `rel-open-change`; only user interaction does both.
+- The trigger text, From / To inputs, month names and day labels are always rendered in `en-US` (`MM/DD/YYYY`); `locale` only affects month-name matching in typed input.
+- Leading and trailing cells of adjacent months are interactive, as in `rel-calendar` (changed, unreleased — they used to be inert): they hover, press, focus and can be picked as the range start or end, and the band and hover preview run across the month boundary. `min-date` / `max-date` disable them exactly as they would an in-month day. Picking one keeps the current month in view, so a range that crosses the boundary can be finished without paging (the date picker and `rel-calendar` do move the view). Out-of-month and weekend labels use the caption colour (`--rel-text-caption`; 1.5.0, they used to fade to 40% / 70%), except on a range endpoint, inside the selected band (where they are part of the selection and show at full strength) and on today. Today gets a 1 px brand ring.
+- Range styling follows Figma ".Date Range Days": the selected run is an `elevated-1` band across the full cell, rounded at the two ends (a one-day range, and a start picked before its end, is a single rounded pill), and the two endpoints are `inverse-2` discs with inverse semibold labels. Days between the endpoints keep their normal label on the band.
+- The panel (and the popup backdrop) is promoted to the browser top layer (`popover="manual"`), so it works inside `rel-modal` / `rel-drawer` and above transformed or `overflow: hidden` ancestors. In `popover` mode it anchors below the host, flips above when there is no room, stays 8 px inside the viewport, repositions on resize. On an outside scroll (since 1.5.0) it **stays open and moves with the field while the field is still visible**, and closes once the field scrolls out of the viewport or its scroll container, or under a sticky header — so the top-layer panel never paints over page furniture (the reason 1.4.9 closed it on every scroll). Only the window and the field's own scroll containers count, including ones inside shadow roots such as `rel-modal`'s body; scrolls of unrelated elements and of the panel itself are ignored, and a wheel or swipe over the panel never scrolls the page (`overscroll-behavior: contain`) (popover mode only). In `popup` mode it is fixed-centred behind a 40% black backdrop (part `overlay`) whose click cancels. It never exceeds the viewport and scrolls internally.
+- `width`, `min-width`, `max-width`, `height`, `min-height` and `max-height` are copied to the host's inline style on every update, so they override stylesheet rules on the host.
+- The icon trigger has no typed entry, no clear icon and no error line; parts `trigger` and `value` are not rendered in that variant.
+- There is no helper-text or external error API; the only text below the field is the typed-entry error.
+- The footer buttons are `<rel-button>` instances — `ghost` for Reset, `secondary` for Cancel and `primary tone="brand"` for Apply — and the icon trigger uses `<rel-button>` with `<rel-icon name="calendar-range">`, so `@reliability-design/icons` is loaded by this component.
+- The host is `inline-block` with an intrinsic width by default; `full-width` switches it to a block that fills the parent.