@reliability-design/web 1.4.9 → 1.4.10

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

@@ -1,206 +1,221 @@
-# rel-date-picker
-
-`<rel-date-picker>` is the single-date form field of the Reliability Design System (Figma "Date Picker"). It is a text field you can type a date into, with a popover calendar whose header pills drill into month and year grids, above Today / Tomorrow / Yesterday shortcut chips. The committed `value` is always an ISO `YYYY-MM-DD` string; the visible text follows `locale`, `display-format` or a `formatDate` callback. Use it wherever a form needs one date. For a from/to range use `<rel-range-picker>`, for an always-visible grid use `<rel-calendar>`, for a time of day use `<rel-time-picker>`.
-
-## Usage
-
-```html
-<!-- Basic labelled field -->
-<rel-date-picker label="Start date"></rel-date-picker>
-
-<!-- Preselected, clearable, required (adds * to the label and aria-required) -->
-<rel-date-picker label="Appointment" value="2026-01-16" clearable required></rel-date-picker>
-
-<!-- Bounded to 2026, Monday-first grid -->
-<rel-date-picker label="Delivery" min-date="2026-01-01" max-date="2026-12-31" week-start="mon"></rel-date-picker>
-
-<!-- Field heights 32 / 40 / 48; fullwidth fills the parent -->
-<rel-date-picker size="small" label="Small"></rel-date-picker>
-<rel-date-picker size="medium" label="Medium" variant="outlined"></rel-date-picker>
-<rel-date-picker size="large" label="Large" fullwidth></rel-date-picker>
-
-<!-- Hide the Today / Tomorrow / Yesterday chip row (on by default) -->
-<rel-date-picker label="Due" show-shortcuts="false"></rel-date-picker>
-
-<!-- Helper and error text below the field -->
-<rel-date-picker label="Due" helper-text="Defaults to the next business day"></rel-date-picker>
-<rel-date-picker label="Due" error error-message="Pick a date after today"></rel-date-picker>
-
-<!-- Fixed display format and locale (value stays ISO) -->
-<rel-date-picker value="2026-07-21" display-format="DD/MM/YYYY"></rel-date-picker>
-<rel-date-picker value="2026-07-21" locale="es-ES"></rel-date-picker>
-
-<!-- Read-only, disabled, and native form submission via a hidden input -->
-<rel-date-picker label="Created" value="2026-01-16" readonly></rel-date-picker>
-<rel-date-picker label="Archived" value="2026-01-16" disabled></rel-date-picker>
-<rel-date-picker name="start" label="Start" placeholder="YYYY-MM-DD"></rel-date-picker>
-```
-
-```js
-const picker = document.querySelector("rel-date-picker");
-
-// Disable individual days on top of min-date/max-date (property only)
-picker.isDateDisabled = (date) => date.getDay() === 0 || date.getDay() === 6;
-
-// Full control of the visible text; wins over display-format
-picker.formatDate = (date) => `Q${Math.floor(date.getMonth() / 3) + 1} ${date.getFullYear()}`;
-
-// Keep the popover open after a pick (a boolean attribute cannot be set to false in markup)
-picker.closeOnSelect = false;
-
-picker.addEventListener("rel-change", (e) => {
-  e.detail.value; // "2026-01-16" or null when cleared
-  e.detail.date;  // Date at local midnight, or null
-});
-picker.addEventListener("rel-open-change", (e) => e.detail.open);
-picker.addEventListener("rel-blur", () => {/* run validation */});
-```
-
-### Typed entry
-
-The field is editable. Typed text is committed on Enter or when focus leaves the component; the parser (`date-parse.ts`) accepts ISO `2026-07-21`, numeric `21/7/2026` / `7/21/26`, month names `21 Jul 2026` / `July 21, 2026`, partial `21/7` (current year) or `21` (current month), and `20260721`. Two-digit years map to `20YY`. When day/month order is ambiguous (`3/4`), the order in `display-format` decides, else the locale's default numeric order. Shortcuts `t` / `today`, `t+7`, `t-3` resolve relative to today. Unparseable text shows "Invalid date", a date outside `min-date`/`max-date`/`isDateDisabled` shows "Date not available" — in both cases the text stays for correction and `value` is untouched; Escape reverts the text. Committing an empty field clears the value like the clear button does.
-
-### Display format
-
-Without `display-format` or `formatDate` the field shows the locale long date (`July 21, 2026`, `21 de julio de 2026` for `es-ES`). `display-format` tokens (`date-format.ts`), matched longest-first with other characters passed through and literal text in `[ ]`: `YYYY` 2026 · `YY` 26 · `MMMM` July · `MMM` Jul · `MM` 07 · `M` 7 · `DD` 21 · `D` 21. Named-month tokens follow `locale`.
-
-### Deprecated aliases
-
-```html
-<!-- min / max → min-date / max-date. Both still work; min-date/max-date win when both are set. No console notice is logged. -->
-<rel-date-picker min="2026-01-01" max="2026-12-31"></rel-date-picker>
-<!-- canonical -->
-<rel-date-picker min-date="2026-01-01" max-date="2026-12-31"></rel-date-picker>
-```
-
-<!-- readme-gen:start -->
-
-<!-- Generated from rel-date-picker.ts — do not edit; run readme-generate.mjs -->
-
-## API
-
-### Attributes / Properties
-
-| Property | Attribute | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| `value` | `value` | `string \| null` | `null` | Selected date as an ISO `YYYY-MM-DD` string, or `null` when empty; setting it also moves the popover to that month. Reflected. |
-| `placeholder` | `placeholder` | `string` | `"Select date"` | Placeholder text shown while the field is empty (visual only; the accessible name comes from `label`, or "Select date" when unset). |
-| `label` | `label` | `string \| null` | `null` | Visible label rendered above the field and wired to the input via `aria-labelledby`; `null` renders no label. |
-| `disabled` | `disabled` | `boolean` | `false` | Disables the field, the icons and the popover; the host dims to 40% opacity. Reflected. |
-| `required` | `required` | `boolean` | `false` | Appends a `*` to the label and sets `aria-required`; no validation is performed. |
-| `readonly` | `readonly` | `boolean` | `false` | Makes the input read-only and stops the field, icon, Enter and ArrowDown from opening the popover. Reflected. |
-| `minDate` | `min-date` | `string \| null` | `null` | Earliest selectable date (ISO `YYYY-MM-DD`); earlier days are disabled and typed dates before it are rejected. Wins over the deprecated `min`. |
-| `maxDate` | `max-date` | `string \| null` | `null` | Latest selectable date (ISO `YYYY-MM-DD`); later days are disabled and typed dates after it are rejected. Wins over the deprecated `max`. |
-| `weekStart` | `week-start` | `"sun" \| "mon"` | `"sun"` | First column of the calendar grid: `"sun"` (default) or `"mon"`. |
-| `locale` | `locale` | `string` | `"en-US"` | BCP 47 locale for weekday/month names, the default long-date display, and day/month order when parsing ambiguous typed input. |
-| `displayFormat` | `display-format` | `string \| null` | `null` | Token pattern for the displayed value (`YYYY`, `YY`, `MMMM`, `MMM`, `MM`, `M`, `DD`, `D`; literal text in `[ ]`), e.g. `DD/MM/YYYY`. Unset → the locale long date. Affects only the visible text, never `value`. |
-| `formatDate` | — | `(date: Date) => string` | `undefined` | Callback with full control over the displayed value; wins over `displayFormat`. Assign it from JavaScript; it stays reactive so setting it after render re-renders the field. The Date it receives is at local midnight. Property only. |
-| `open` | `open` | `boolean` | `false` | Whether the calendar popover is open; set it directly to open/close programmatically (focus then moves into the grid). Reflected. |
-| `closeOnSelect` | `close-on-select` | `boolean` | `true` | Closes the popover after a day is picked in the grid (default `true`). |
-| `clearable` | `clearable` | `boolean` | `false` | Shows a clear (×) icon while a value is set; clearing fires `rel-change` with `value: null`. |
-| `showShortcuts` | `show-shortcuts` | `boolean` | `true` | Figma ".Date Picker Calendar" Show Shortcuts: renders the Today / Tomorrow / Yesterday chip row and its divider at the top of the popover. On by default — write `show-shortcuts="false"` to hide both (a plain boolean attribute could not express a default of `true`). The typed `T` / `T±N` shortcuts and the in-panel `T` key keep working either way. |
-| `error` | `error` | `boolean` | `false` | Forces the error style (danger border, `aria-invalid`) and shows `errorMessage` below the field. Typed-entry parse errors set the same style on their own. |
-| `errorMessage` | `error-message` | `string` | `undefined` | Text shown below the field while `error` is set (or a typed date failed to parse); falls back to `helperText`. |
-| `helperText` | `helper-text` | `string` | `undefined` | Supporting text shown below the field when there is no error. |
-| `name` | `name` | `string` | `undefined` | When set, renders a hidden `<input name>` carrying the ISO value so the picker submits with a native form. |
-| `size` | `size` | `"small" \| "medium" \| "large"` | `"medium"` | Field height scale shared with rel-textfield / rel-select: `small` 32px, `medium` 40px (default), `large` 48px. |
-| `variant` | `variant` | `"outlined"` | `"outlined"` | Visual style of the field; `outlined` is the only variant today. Reflected. |
-| `fullWidth` | `fullwidth` | `boolean` | `false` | Stretches the host to fill its parent's width (attribute `fullwidth`); off by default so the field keeps its intrinsic inline width. Reflected. |
-
-#### Deprecated (still supported — removal targeted for 3.0)
-
-| Property | Attribute | Type | Use instead |
-| --- | --- | --- | --- |
-| `min` | `min` | `string \| null` | use minDate |
-| `max` | `max` | `string \| null` | use maxDate |
-
-### Public fields / accessors
-
-| Name | Type | Description |
-| --- | --- | --- |
-| `isDateDisabled` | `(date: Date) => boolean` | Custom predicate that disables individual days (return `true` to disable); applied on top of `minDate`/`maxDate` and also rejects typed input. Property only — assign it from JavaScript. |
-
-## 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` | `{ value: newValue, date: new Date(date), } / { value: null, date: null, } / { value: null, date: null }` | bubbles / composed | Fired when the value changes — grid pick, typed entry, shortcut, or clear. Detail: `{ value: string \| null, date: Date \| null }` (ISO `YYYY-MM-DD` and a local-midnight Date; both `null` when cleared). |
-| `rel-open-change` | `{ open: this.open } / { open: false }` | bubbles / composed | Fired when the calendar popover opens or closes. Detail: `{ open: boolean }`. |
-
-## Slots
-
-| Slot | Description |
-| --- | --- |
-| — | This element has no slots. |
-
-## CSS Parts
-
-| Part | Description |
-| --- | --- |
-| `base` | Outer wrapper carrying the size class (`small` / `medium` / `large`) |
-| `label` | The visible field label (rendered only when `label` is set) |
-| `trigger` | The field box that wraps the text input and the clear/calendar icons |
-| `value` | The editable text input inside the trigger |
-| `shortcuts` | The Today / Tomorrow / Yesterday chip row at the top of the popover |
-
-<!-- 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
-
-- The text input is a `role="combobox"` with `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls` pointing at the panel, `aria-required` from `required`, `aria-invalid` when `error` is set or typed text failed to parse, and `aria-describedby` pointing at the helper/error line. Its name is the `label` (via `aria-labelledby`) or the fixed string "Select date" when no label is set; the required `*` is `aria-hidden`.
-- The icons are real buttons: "Clear date" (only while `clearable` and a value is set) and "Open calendar" (carries `aria-expanded`).
-- The popover is a `role="dialog"` named "Choose date". While it is open, Tab and Shift+Tab are trapped inside it (`trapTabKey`), and Escape closes it from anywhere in the document.
-- The month and year pills are buttons carrying `aria-expanded`; pressing one swaps the panel body for a `role="grid"` of `role="gridcell"` cells ("Select month" / "Select year") with `aria-selected` on the current value. Every view is 252 px tall, so the panel never resizes as the user drills in.
-- The day grid is `role="grid"` named "<Month> <Year>"; weeks are `role="row"`; each day is a `<button role="gridcell">` with the full long date as `aria-label`, `aria-selected`, `aria-current="date"` on today and native `disabled` for unavailable days. Only one cell is a Tab stop (last arrowed date → selected → today → first enabled).
-- Focus: opening from the calendar icon, Enter, ArrowDown or by setting `open` moves focus into the grid (onto that Tab-stop cell) after 100 ms; opening by clicking into the text keeps focus in the input so typing keeps working. Closing via Escape, a pick or a shortcut returns focus to the input; an outside click closes without refocusing.
-- Screen readers hear "<Month> <Year>" through the shared `announce()` region (`utils/announce.ts`) on every month/year change (chevrons, a month or year cell, PageUp/PageDown, arrowing across a month boundary), and the first and last year of the page (e.g. "2020 to 2031") when the years page changes. The helper/error line is a persistent `aria-live="polite"` region, so parse errors are read as they appear.
-
-| Key (in the field) | Action |
-| --- | --- |
-| Enter | Nothing typed: open the popover. Text typed: commit it |
-| ArrowDown | Open the popover; if already open, move focus into the grid |
-| Escape | Revert uncommitted text and close the popover |
-| Tab (popover open) | Cycle through the popover's controls |
-
-| 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 cell of the row |
-| PageUp / PageDown | Previous / next month |
-| Shift + PageUp / Shift + PageDown | Previous / next year |
-| Enter / Space | Select the day; closes the popover unless `closeOnSelect` is false |
-| T (anywhere in the popover, no modifier) | Select today |
-| Escape | Close and return focus to the input |
-
-| Key (month / year grid) | Action |
-| --- | --- |
-| Enter / Space on a pill | Open that grid; press the same pill again to return to the days |
-| ArrowLeft / ArrowRight | Previous / next cell |
-| ArrowUp / ArrowDown | Same column, one row up / down |
-| Home / End | First / last cell of the grid |
-| Enter / Space | Choose the cell — a year drills into the months, a month returns to the days |
-| Escape | Back to the days grid, keeping the popover open |
-
-## Notes / Edge Cases
-
-- `value` is always ISO `YYYY-MM-DD`; `display-format` and `formatDate` change only the visible text. The `Date` given to `formatDate`, `isDateDisabled` and `rel-change` is at local midnight — read it with `getFullYear()`/`getMonth()`/`getDate()`, never `toISOString()` (which can shift the day by the UTC offset). For a plain ISO display use `display-format="YYYY-MM-DD"`.
-- `min`/`max` are deprecated aliases of `min-date`/`max-date`; when both spellings are present the canonical one wins. No runtime notice is logged.
-- Leading and trailing cells of adjacent months are rendered but never selectable (unlike `rel-calendar`).
-- The years grid shows one 12-year page at a time, anchored so the year in view sits in the seventh cell; the chevrons page by 12. In the months grid the chevrons step a year, and in the days grid a month. A month or year cell is disabled only when *every* day it covers falls outside `min-date`/`max-date`.
-- The panel always reopens on the days grid, whichever view was showing when it closed.
-- The field is Figma's TextField instance: `border-radius: xs` (4 px), 12 px inline padding at `medium`, a 4 px label gap and an 18 px suffix icon — the same geometry `rel-textfield` uses, so the two line up in a shared form row. Icon and inline padding step with `size` (16/18/20 px and 8/12/16 px).
-- The panel is promoted to the browser top layer (`popover="manual"`), so it renders above `rel-modal` / `rel-drawer` and transformed or `overflow: hidden` ancestors. It repositions on resize, and **closes on an outside scroll** (changed in 1.4.9 — it used to track the trigger, which left the panel floating over sticky page furniture once the trigger had scrolled out of view). Scrolling inside the panel does not close it. It flips above the trigger when there is no room below, stays 8 px inside the viewport, is capped at 600 px tall (scrolls) and never wider than the viewport.
-- Below-field text resolves as `errorMessage ?? typed-entry error ?? helperText` while in error, else `helperText`. A typed-entry error styles the field like `error` without setting the property.
-- `readonly` and `disabled` both stop the popover from opening (field click, icon, Enter, ArrowDown); `disabled` also blocks all pointer events.
-- `closeOnSelect` is a boolean attribute: it can only be turned off from JavaScript (`picker.closeOnSelect = false`). It affects grid picks only — typed entry and shortcuts always close the popover.
-- The `name` hidden input submits an empty string while `value` is null.
-- `size` is applied as a class on part `base` (not reflected); `variant` currently has the single value `outlined`.
-- The host is `inline-block` with an intrinsic width (min 200 px) by default; `fullwidth` switches it to a block that fills the parent.
+# rel-date-picker
+
+`<rel-date-picker>` is the single-date form field of the Reliability Design System (Figma "Date Picker"). It is a text field you can type a date into, with a popover calendar whose header pills drill into month and year grids, above Today / Tomorrow / Yesterday shortcut chips. The committed `value` is always an ISO `YYYY-MM-DD` string; the visible text follows `locale`, `display-format` or a `formatDate` callback. Use it wherever a form needs one date. For a from/to range use `<rel-range-picker>`, for an always-visible grid use `<rel-calendar>`, for a time of day use `<rel-time-picker>`.
+
+## Usage
+
+```html
+<!-- Basic labelled field -->
+<rel-date-picker label="Start date"></rel-date-picker>
+
+<!-- Preselected, clearable, required (adds * to the label and aria-required) -->
+<rel-date-picker label="Appointment" value="2026-01-16" clearable required></rel-date-picker>
+
+<!-- Bounded to 2026, Monday-first grid -->
+<rel-date-picker label="Delivery" min-date="2026-01-01" max-date="2026-12-31" week-start="mon"></rel-date-picker>
+
+<!-- Field heights 32 / 40 / 48; full-width fills the parent -->
+<rel-date-picker size="small" label="Small"></rel-date-picker>
+<rel-date-picker size="medium" label="Medium" variant="outlined"></rel-date-picker>
+<rel-date-picker size="large" label="Large" full-width></rel-date-picker>
+
+<!-- Hide the Today / Tomorrow / Yesterday chip row (on by default) -->
+<rel-date-picker label="Due" show-shortcuts="false"></rel-date-picker>
+
+<!-- Helper and error text below the field -->
+<rel-date-picker label="Due" helper-text="Defaults to the next business day"></rel-date-picker>
+<rel-date-picker label="Due" error error-message="Pick a date after today"></rel-date-picker>
+
+<!-- Fixed display format and locale (value stays ISO) -->
+<rel-date-picker value="2026-07-21" display-format="DD/MM/YYYY"></rel-date-picker>
+<rel-date-picker value="2026-07-21" locale="es-ES"></rel-date-picker>
+
+<!-- Read-only, disabled, and native form submission via a hidden input -->
+<rel-date-picker label="Created" value="2026-01-16" readonly></rel-date-picker>
+<rel-date-picker label="Archived" value="2026-01-16" disabled></rel-date-picker>
+<rel-date-picker name="start" label="Start" placeholder="YYYY-MM-DD"></rel-date-picker>
+```
+
+```js
+const picker = document.querySelector("rel-date-picker");
+
+// Disable individual days on top of min-date/max-date (property only)
+picker.isDateDisabled = (date) => date.getDay() === 0 || date.getDay() === 6;
+
+// Full control of the visible text; wins over display-format
+picker.formatDate = (date) => `Q${Math.floor(date.getMonth() / 3) + 1} ${date.getFullYear()}`;
+
+// Keep the popover open after a pick (same as close-on-select="false" in markup)
+picker.closeOnSelect = false;
+
+picker.addEventListener("rel-change", (e) => {
+  e.detail.value; // "2026-01-16" or null when cleared
+  e.detail.date;  // Date at local midnight, or null
+});
+picker.addEventListener("rel-open-change", (e) => e.detail.open);
+picker.addEventListener("rel-blur", () => {/* run validation */});
+```
+
+### Typed entry
+
+The field is editable. Typed text is committed on Enter or when focus leaves the component; the parser (`date-parse.ts`) accepts ISO `2026-07-21`, numeric `21/7/2026` / `7/21/26`, month names `21 Jul 2026` / `July 21, 2026`, partial `21/7` (current year) or `21` (current month), and `20260721`. Two-digit years map to `20YY`. When day/month order is ambiguous (`3/4`), the order in `display-format` decides, else the locale's default numeric order. Shortcuts `t` / `today`, `t+7`, `t-3` resolve relative to today. Unparseable text shows "Invalid date", a date outside `min-date`/`max-date`/`isDateDisabled` shows "Date not available" — in both cases the text stays for correction and `value` is untouched; Escape reverts the text. Committing an empty field clears the value like the clear button does.
+
+### Display format
+
+Without `display-format` or `formatDate` the field shows the locale long date (`July 21, 2026`, `21 de julio de 2026` for `es-ES`). `display-format` tokens (`date-format.ts`), matched longest-first with other characters passed through and literal text in `[ ]`: `YYYY` 2026 · `YY` 26 · `MMMM` July · `MMM` Jul · `MM` 07 · `M` 7 · `DD` 21 · `D` 21. Named-month tokens follow `locale`.
+
+### Deprecated aliases
+
+```html
+<!-- min / max → min-date / max-date. Both still work; min-date/max-date win when both are set. No console notice is logged. -->
+<rel-date-picker min="2026-01-01" max="2026-12-31"></rel-date-picker>
+<!-- canonical -->
+<rel-date-picker min-date="2026-01-01" max-date="2026-12-31"></rel-date-picker>
+
+<!-- fullwidth → full-width (since 1.5.0; still works, logs a one-time console notice, removed in 3.0) -->
+<rel-date-picker label="Old spelling" fullwidth></rel-date-picker>
+<rel-date-picker label="Canonical" full-width></rel-date-picker>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-date-picker.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `value` | `string \| null` | `null` | Selected date as an ISO `YYYY-MM-DD` string, or `null` when empty; setting it also moves the popover to that month. Reflected. |
+| `placeholder` | `placeholder` | `string` | `"Select date"` | Placeholder text shown while the field is empty (visual only; the accessible name comes from `label`, or "Select date" when unset). |
+| `label` | `label` | `string \| null` | `null` | Visible label rendered above the field and wired to the input via `aria-labelledby`; `null` renders no label. |
+| `disabled` | `disabled` | `boolean` | `false` | Disables the field, the icons and the popover. The field looks exactly like a disabled `rel-textfield`: the whole field at 0.65 opacity, an elevated-2 box with the accent border, the label in `--rel-text-label` and the value and placeholder in `--rel-text-caption` (changed in 1.5.0: they were `--rel-text-disabled` under the 0.65, which left them barely readable). Reflected. |
+| `required` | `required` | `boolean` | `false` | Appends a `*` to the label and sets `aria-required`; no validation is performed. |
+| `readonly` | `readonly` | `boolean` | `false` | Makes the input read-only and stops the field, icon, Enter and ArrowDown from opening the popover. Reflected. |
+| `minDate` | `min-date` | `string \| null` | `null` | Earliest selectable date (ISO `YYYY-MM-DD`); earlier days are disabled and typed dates before it are rejected. Wins over the deprecated `min`. |
+| `maxDate` | `max-date` | `string \| null` | `null` | Latest selectable date (ISO `YYYY-MM-DD`); later days are disabled and typed dates after it are rejected. Wins over the deprecated `max`. |
+| `weekStart` | `week-start` | `"sun" \| "mon"` | `"sun"` | First column of the calendar grid: `"sun"` (default) or `"mon"`. |
+| `locale` | `locale` | `string` | `"en-US"` | BCP 47 locale for weekday/month names, the default long-date display, and day/month order when parsing ambiguous typed input. |
+| `displayFormat` | `display-format` | `string \| null` | `null` | Token pattern for the displayed value (`YYYY`, `YY`, `MMMM`, `MMM`, `MM`, `M`, `DD`, `D`; literal text in `[ ]`), e.g. `DD/MM/YYYY`. Unset → the locale long date. Affects only the visible text, never `value`. |
+| `formatDate` | — | `(date: Date) => string` | `undefined` | Callback with full control over the displayed value; wins over `displayFormat`. Assign it from JavaScript; it stays reactive so setting it after render re-renders the field. The Date it receives is at local midnight. Property only. |
+| `open` | `open` | `boolean` | `false` | Whether the calendar popover is open; set it directly to open/close programmatically (focus then moves into the grid). Reflected. |
+| `closeOnSelect` | `close-on-select` | `boolean` | `true` | Closes the popover after a day is picked in the grid (default `true`). |
+| `clearable` | `clearable` | `boolean` | `false` | Shows a clear (×) icon while a value is set; clearing fires `rel-change` with `value: null`. |
+| `showShortcuts` | `show-shortcuts` | `boolean` | `true` | Figma ".Date Picker Calendar" Show Shortcuts: renders the Today / Tomorrow / Yesterday chip row and its divider at the top of the popover. On by default — write `show-shortcuts="false"` to hide both (a plain boolean attribute could not express a default of `true`). The typed `T` / `T±N` shortcuts and the in-panel `T` key keep working either way. |
+| `error` | `error` | `boolean` | `false` | Forces the error style (danger border, `aria-invalid`) and shows `errorMessage` below the field. Typed-entry parse errors set the same style on their own. |
+| `errorMessage` | `error-message` | `string` | `undefined` | Text shown below the field while `error` is set (or a typed date failed to parse); falls back to `helperText`. |
+| `helperText` | `helper-text` | `string` | `undefined` | Supporting text shown below the field when there is no error. |
+| `name` | `name` | `string` | `undefined` | When set, renders a hidden `<input name>` carrying the ISO value so the picker submits with a native form. |
+| `size` | `size` | `"small" \| "medium" \| "large"` | `"medium"` | Field height scale shared with rel-textfield / rel-select: `small` 32px, `medium` 40px (default), `large` 48px. |
+| `variant` | `variant` | `"outlined"` | `"outlined"` | Visual style of the field; `outlined` is the only variant today. Reflected. |
+| `fullWidth` | `full-width` | `boolean` | `false` | Stretches the host to fill its parent's width (attribute `full-width`); off by default so the field keeps its intrinsic inline width. Reflected (as `fullwidth` in 1.x). The `fullwidth` attribute spelling is deprecated (still works; removal targeted for 3.0). |
+
+#### Deprecated (still supported — removal targeted for 3.0)
+
+| Property | Attribute | Type | Use instead |
+| --- | --- | --- | --- |
+| `min` | `min` | `string \| null` | use minDate |
+| `max` | `max` | `string \| null` | use maxDate |
+
+### Public fields / accessors
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `isDateDisabled` | `(date: Date) => boolean` | Custom predicate that disables individual days (return `true` to disable); applied on top of `minDate`/`maxDate` and also rejects typed input. Property only — assign it from JavaScript. |
+
+## 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` | `{ value: newValue, date: new Date(date), } / { value: null, date: null, } / { value: null, date: null }` | bubbles / composed | Fired when the value changes — grid pick, typed entry, shortcut, or clear. Detail: `{ value: string \| null, date: Date \| null }` (ISO `YYYY-MM-DD` and a local-midnight Date; both `null` when cleared). |
+| `rel-open-change` | `{ open: this.open } / { open: false }` | bubbles / composed | Fired when the calendar popover opens or closes. Detail: `{ open: boolean }`. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `unavailable` | Day cells that cannot be picked (outside `min-date` / `max-date`, or blocked by `isDateDisabled`). They are `aria-disabled` and stay focusable, so `:disabled` does not match them; style them with `::part(unavailable)` |
+| `base` | Outer wrapper carrying the size class (`small` / `medium` / `large`) |
+| `label` | The visible field label (rendered only when `label` is set) |
+| `trigger` | The field box that wraps the text input and the clear/calendar icons |
+| `value` | The editable text input inside the trigger |
+| `shortcuts` | The Today / Tomorrow / Yesterday chip row at the top of the popover |
+
+## 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
+
+- The text input is a `role="combobox"` with `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls` pointing at the panel, `aria-required` from `required`, `aria-invalid` when `error` is set or typed text failed to parse, and `aria-describedby` pointing at the helper/error line. Its name is the `label` (via `aria-labelledby`) or the fixed string "Select date" when no label is set; the required `*` is `aria-hidden`.
+- The icons are real buttons: "Clear date" (only while `clearable` and a value is set) and "Open calendar" (carries `aria-expanded`).
+- The popover is a `role="dialog"` named "Choose date". While it is open, Tab and Shift+Tab are trapped inside it (`trapTabKey`), and Escape closes it from anywhere in the document.
+- The month and year pills are buttons carrying `aria-expanded`; pressing one swaps the panel body for a `role="grid"` of `role="gridcell"` cells ("Select month" / "Select year") with `aria-selected` on the current value. Every view is 252 px tall, so the panel never resizes as the user drills in.
+- The day grid is `role="grid"` named "<Month> <Year>"; weeks are `role="row"`; each day is a `<button role="gridcell">` with the full long date as `aria-label`, `aria-selected`, `aria-current="date"` on today and `aria-disabled="true"` for unavailable days (changed, unreleased — they used to be native `disabled`, which could not take focus). Exactly one cell is a Tab stop: the day last interacted with (arrowed to, clicked or tabbed onto), else the selected day, else today, else the first enabled day — so Shift+Tab then Tab returns to the day you left. The arrow keys move by date, not by grid position, so they stay on the right day when the view flips month (unreleased fix: Sep 27 + ArrowDown used to land on Nov 1 instead of Oct 4). The key map is shared with `rel-range-picker`.
+- Focus: opening from the calendar icon, Enter, ArrowDown or by setting `open` moves focus into the grid (onto that Tab-stop cell) after 100 ms; opening by clicking into the text keeps focus in the input so typing keeps working. Closing via Escape, a pick or a shortcut returns focus to the input; an outside click closes without refocusing.
+- Screen readers hear "<Month> <Year>" through the shared `announce()` region (`utils/announce.ts`) on every month/year change (chevrons, a month or year cell, PageUp/PageDown, arrowing across a month boundary), and the first and last year of the page (e.g. "2020 to 2031") when the years page changes. The helper/error line is a persistent `aria-live="polite"` region, so parse errors are read as they appear.
+
+| Key (in the field) | Action |
+| --- | --- |
+| Enter | Nothing typed: open the popover. Text typed: commit it |
+| ArrowDown | Open the popover; if already open, move focus into the grid |
+| Escape | Revert uncommitted text and close the popover |
+| Tab (popover open) | Cycle through the popover's controls |
+
+| 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 week, honouring `week-start` (switches month if that day is in the adjacent month) |
+| PageUp / PageDown | Same day previous / next month (clamped to the month's last day, e.g. 31 Jan → 28 Feb) |
+| Shift + PageUp / Shift + PageDown | Same day previous / next year |
+| Enter / Space | Select the day; closes the popover unless `closeOnSelect` is false. Does nothing on an unavailable day — the arrows land on those days rather than skipping them |
+| T (anywhere in the popover, no modifier) | Select today |
+| Escape | Close and return focus to the input |
+
+| Key (month / year grid) | Action |
+| --- | --- |
+| Enter / Space on a pill | Open that grid; press the same pill again to return to the days |
+| ArrowLeft / ArrowRight | Previous / next cell |
+| ArrowUp / ArrowDown | Same column, one row up / down |
+| Home / End | First / last cell of the grid |
+| Enter / Space | Choose the cell — a year drills into the months, a month returns to the days |
+| Escape | Back to the days grid, keeping the popover open |
+
+## Notes / Edge Cases
+
+- `value` is always ISO `YYYY-MM-DD`; `display-format` and `formatDate` change only the visible text. The `Date` given to `formatDate`, `isDateDisabled` and `rel-change` is at local midnight — read it with `getFullYear()`/`getMonth()`/`getDate()`, never `toISOString()` (which can shift the day by the UTC offset). For a plain ISO display use `display-format="YYYY-MM-DD"`.
+- `min`/`max` are deprecated aliases of `min-date`/`max-date`; when both spellings are present the canonical one wins. No runtime notice is logged.
+- Leading and trailing cells of adjacent months are interactive, as in `rel-calendar` (changed, unreleased — they used to be disabled): they hover, focus and select like any other day, and `min-date` / `max-date` / `isDateDisabled` disable them exactly as they would an in-month day. Their label, like a weekend's, uses the caption colour (`--rel-text-caption`) unless selected (1.5.0; it used to fade to 40%, weekends to 70%). Picking one with `closeOnSelect = false` moves the view to that day's month and focus to the new selection.
+- The years grid shows one 12-year page at a time, anchored so the year in view sits in the seventh cell; the chevrons page by 12. In the months grid the chevrons step a year, and in the days grid a month. A month or year cell is disabled only when *every* day it covers falls outside `min-date`/`max-date`.
+- The panel always reopens on the days grid, whichever view was showing when it closed.
+- The field is Figma's TextField instance: `border-radius: xs` (4 px), 12 px inline padding at `medium`, a 4 px label gap and an 18 px suffix icon — the same geometry `rel-textfield` uses, so the two line up in a shared form row. Icon and inline padding step with `size` (16/18/20 px and 8/12/16 px).
+- The panel is promoted to the browser top layer (`popover="manual"`), so it renders above `rel-modal` / `rel-drawer` and transformed or `overflow: hidden` ancestors. It 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`). It flips above the trigger when there is no room below, stays 8 px inside the viewport, is capped at 600 px tall (scrolls) and never wider than the viewport.
+- Below-field text resolves as `errorMessage ?? typed-entry error ?? helperText` while in error, else `helperText`. A typed-entry error styles the field like `error` without setting the property.
+- `readonly` and `disabled` both stop the popover from opening (field click, icon, Enter, ArrowDown); `disabled` also blocks all pointer events.
+- `closeOnSelect` defaults to true; turn it off with `close-on-select="false"` (since 1.5.0) or `picker.closeOnSelect = false`. It affects grid picks only — typed entry and shortcuts always close the popover.
+- The `name` hidden input submits an empty string while `value` is null.
+- `size` is applied as a class on part `base` (not reflected); `variant` currently has the single value `outlined`.
+- The host is `inline-block` with an intrinsic width (min 200 px) by default; `full-width` switches it to a block that fills the parent.

package/dist/components/rel-drawer/README.md

@@ -11,7 +11,7 @@
 <rel-drawer id="filters" title="Filters" description="Narrow down the results.">
   <p>Filter controls go here.</p>
   <rel-button slot="footer" variant="secondary" id="reset">Reset</rel-button>
-  <rel-button slot="footer" variant="primary" id="apply">Apply</rel-button>
+  <rel-button slot="footer" variant="primary" tone="brand" id="apply">Apply</rel-button>
 </rel-drawer>
 
 <script>
@@ -56,7 +56,7 @@
 <!-- Standalone actions row using the same layout as the drawer footer -->
 <rel-drawer-footer>
   <rel-button variant="secondary">Cancel</rel-button>
-  <rel-button variant="primary">Save</rel-button>
+  <rel-button variant="primary" tone="brand">Save</rel-button>
 </rel-drawer-footer>
 ```
 
@@ -104,7 +104,7 @@
 | Slot | Description |
 | --- | --- |
 | (default) | Body content of the drawer |
-| `footer` | Actions row; rendered inside a `<rel-drawer-footer>` (right-aligned, 8px gap) |
+| `footer` | Actions row; rendered inside a `<rel-drawer-footer>` (right-aligned, 8px gap). The footer only renders when this slot has content; its top divider shows only while the body scrolls |
 
 ### CSS Parts
 
@@ -183,5 +183,5 @@ Set these on the host (or an ancestor) to customise the element without touching
 - `width` is written to the panel as an inline `--rel-drawer-width`, so it wins over a `--rel-drawer-width` set on the host. Leave it empty to use the per-side defaults.
 - `max-height` is written to the panel as `--drawer-max-height` but no rule reads it yet; size bottom drawers with `--rel-drawer-height` instead.
 - After a left/right drawer finishes sliding in, its `transform` is dropped so `position: fixed` descendants (select menus, popovers, tooltips, date pickers) are no longer clipped to the panel. Bottom drawers keep their transform because it centres them.
-- The footer wrapper (padding + top border) is always rendered, even when the `footer` slot is empty.
+- The header always has a bottom border. The footer wrapper only renders when the `footer` slot has content (the host gains a `has-footer` attribute while it does), so a drawer without actions has no empty footer band. Its top divider shows only while the body scrolls (the host gains `body-scrolls`); short content has no footer divider. Scrolling is re-measured when the body or any slotted child resizes, so content added after opening, children growing in place, images loading and window resizes all update it.
 - Legacy hook aliases still honoured: `--drawer-width`, `--drawer-height`, `--drawer-transition-duration` and `--drawer-transition-timing` are read as fallbacks of the `--rel-drawer-*` hooks. `--rel-drawer-scrim-opacity` has no legacy alias.