@reliability-design/web 1.4.5 → 1.4.7

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

@@ -1,289 +1,200 @@
-# rel-date-picker
-
-A fully accessible date picker component built with Lit for the Reliability Design System. Features a trigger button with calendar popover including month/year dropdowns.
-
-## Features
-
-- Trigger button with calendar popover
-- Month and year dropdowns for easy navigation
-- Single date selection
-- Optional clear button
-- Min/max date constraints
-- Custom disabled date predicate
-- Keyboard navigation
-- Full ARIA support
-- Token-driven styling
-
-## Usage
-
-### Basic
-
-```html
-<rel-date-picker></rel-date-picker>
-```
-
-### With Value
-
-```html
-<rel-date-picker value="2026-01-16"></rel-date-picker>
-```
-
-### With Label
-
-```html
-<rel-date-picker label="Select appointment date"></rel-date-picker>
-```
-
-### With Min/Max
-
-```html
-<rel-date-picker
-  min="2026-01-01"
-  max="2026-12-31"
-  placeholder="Select a date in 2026"
-></rel-date-picker>
-```
-
-### Clearable
-
-```html
-<rel-date-picker value="2026-01-16" clearable></rel-date-picker>
-```
-
-### Disabled
-
-```html
-<rel-date-picker value="2026-01-16" disabled></rel-date-picker>
-```
-
-### Programmatic Control (JavaScript)
-
-```javascript
-const picker = document.querySelector('rel-date-picker');
-
-// Set value
-picker.value = '2026-01-16';
-
-// Open programmatically
-picker.open = true;
-
-// Custom disabled dates (e.g., disable weekends)
-picker.isDateDisabled = (date) => {
-  const day = date.getDay();
-  return day === 0 || day === 6; // Sunday or Saturday
-};
-
-// Listen to changes
-picker.addEventListener('rel-change', (e) => {
-  console.log('Selected date:', e.detail.value); // "2026-01-16"
-  console.log('Date object:', e.detail.date); // Date object
-});
-
-// Listen to popover open/close
-picker.addEventListener('rel-open-change', (e) => {
-  console.log('Popover open:', e.detail.open); // boolean
-});
-```
-
-## Attributes
-
-| Attribute | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `value` | `string \| null` | `null` | Selected date in ISO format (YYYY-MM-DD) |
-| `placeholder` | `string` | `"Select date"` | Placeholder text when no date selected |
-| `label` | `string \| null` | `null` | Accessible label for the date picker |
-| `disabled` | `boolean` | `false` | Disables all interaction |
-| `required` | `boolean` | `false` | Sets aria-required (no validation logic) |
-| `min` | `string \| null` | `null` | Minimum selectable date (ISO format) |
-| `max` | `string \| null` | `null` | Maximum selectable date (ISO format) |
-| `week-start` | `"sun" \| "mon"` | `"sun"` | First day of the week |
-| `locale` | `string` | `"en-US"` | Locale for weekday labels and named-month display tokens (uses Intl.DateTimeFormat) |
-| `display-format` | `string \| null` | `null` | Token pattern for the selected value (see [Display format](#display-format)). Unset → locale long date |
-| `open` | `boolean` | `false` | Controls popover open state |
-| `close-on-select` | `boolean` | `true` | Close popover after selecting a date |
-| `clearable` | `boolean` | `false` | Show clear button when date is selected |
-
-## Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `isDateDisabled` | `(date: Date) => boolean` | Custom function to disable specific dates |
-| `formatDate` | `(date: Date) => string` | Full control of the selected-value display; takes precedence over `display-format`. Set via property (not an attribute) |
-
-## Display format
-
-By default the selected date is shown using the locale's long date (e.g. `July 21, 2026`). To render a fixed format instead, set `display-format` to a token pattern, or set the `formatDate` property to a callback for full control. Both affect **only the visible trigger text** — the underlying `value` stays ISO (`YYYY-MM-DD`), and parsing, the calendar, and accessibility are unchanged.
-
-```html
-<rel-date-picker value="2026-07-21" display-format="YYYY-MM-DD"></rel-date-picker> <!-- 2026-07-21 -->
-<rel-date-picker value="2026-07-21" display-format="MM/DD/YYYY"></rel-date-picker> <!-- 07/21/2026 -->
-<rel-date-picker value="2026-07-21" display-format="DD/MM/YYYY"></rel-date-picker> <!-- 21/07/2026 -->
-<rel-date-picker value="2026-07-21" display-format="DD MMM YYYY"></rel-date-picker> <!-- 21 Jul 2026 -->
-```
-
-```js
-// Full control via callback (wins over display-format). Use it for logic a
-// pattern can't express — e.g. relative labels or fiscal periods.
-picker.formatDate = (date) => `Q${Math.floor(date.getMonth() / 3) + 1} ${date.getFullYear()}`;
-```
-
-> **Timezone note:** the `date` passed to `formatDate` is at **local midnight**. Read it with local getters (`getFullYear` / `getMonth` / `getDate`) — as the built-in tokens do. Avoid `toISOString()` / `getUTC*`, which shift the day by the local UTC offset (e.g. `2026-07-21` → `2026-07-20`). For a plain ISO string, prefer `display-format="YYYY-MM-DD"`.
-
-**Tokens** (matched longest-first; other characters pass through; wrap literal text containing token letters in `[ ]`):
-
-| Token | Meaning | Example (2026-07-21) |
-|-------|---------|----------------------|
-| `YYYY` | 4-digit year | `2026` |
-| `YY` | 2-digit year | `26` |
-| `MMMM` | Full month (locale) | `July` |
-| `MMM` | Short month (locale) | `Jul` |
-| `MM` | 2-digit month | `07` |
-| `M` | Month number | `7` |
-| `DD` | 2-digit day | `21` |
-| `D` | Day number | `21` |
-
-Named-month tokens (`MMMM`/`MMM`) respect `locale`; numeric formats are locale-independent. Existing consumers that set neither property are unaffected.
-
-## Events
-
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `rel-change` | `{ value: string \| null, date: Date \| null }` | Fired when selected date changes |
-| `rel-open-change` | `{ open: boolean }` | Fired when popover opens/closes |
-
-## Keyboard Navigation
-
-### Trigger Button
-- **Enter/Space**: Opens the popover
-- **Arrow Down**: Opens the popover
-
-### Inside Calendar
-- **Arrow keys**: Navigate days (left/right) and weeks (up/down)
-- **Home/End**: Jump to week start/end
-- **PageUp/PageDown**: Change month
-- **Shift + PageUp/PageDown**: Change year
-- **Enter/Space**: Select focused day
-- **Escape**: Close popover
-
-### Month/Year Dropdowns
-- **Tab**: Navigate between dropdowns
-- **Click**: Select month or year
-
-## Calendar Features
-
-### Month Dropdown
-- Lists all 12 months localized to the specified locale
-- Scroll through months quickly
-- Current month is highlighted
-
-### Year Dropdown
-- Scrollable list of years
-- Range automatically calculated:
-  - With min/max: Uses constrained range with buffer
-  - Without: Defaults to [currentYear - 100, currentYear + 10]
-- Current year is highlighted
-
-## Custom Disabled Dates
-
-Use the `isDateDisabled` property to implement custom logic:
-
-```javascript
-const picker = document.querySelector('rel-date-picker');
-
-// Disable weekends
-picker.isDateDisabled = (date) => {
-  const day = date.getDay();
-  return day === 0 || day === 6;
-};
-
-// Disable specific dates
-const blackoutDates = ['2026-01-15', '2026-01-20', '2026-01-25'];
-picker.isDateDisabled = (date) => {
-  const iso = date.toISOString().split('T')[0];
-  return blackoutDates.includes(iso);
-};
-
-// Disable dates before today
-picker.isDateDisabled = (date) => {
-  const today = new Date();
-  today.setHours(0, 0, 0, 0);
-  return date < today;
-};
-```
-
-## Complete Example
-
-```html
-<rel-date-picker
-  id="appointment-picker"
-  label="Appointment Date"
-  placeholder="Choose a date"
-  min="2026-01-01"
-  max="2026-12-31"
-  clearable
-  required
-></rel-date-picker>
-
-<script>
-  const picker = document.getElementById('appointment-picker');
-
-  // Disable weekends
-  picker.isDateDisabled = (date) => {
-    const day = date.getDay();
-    return day === 0 || day === 6;
-  };
-
-  // Handle selection
-  picker.addEventListener('rel-change', (e) => {
-    if (e.detail.value) {
-      console.log('Appointment scheduled for:', e.detail.value);
-    } else {
-      console.log('Appointment cleared');
-    }
-  });
-
-  // Handle popover state
-  picker.addEventListener('rel-open-change', (e) => {
-    console.log('Calendar', e.detail.open ? 'opened' : 'closed');
-  });
-</script>
-```
-
-## Accessibility
-
-- Trigger button has proper `aria-haspopup`, `aria-expanded`, and `aria-label`
-- Calendar popover uses `role="dialog"`
-- Day buttons use `role="gridcell"` with proper `aria-label` and `aria-selected`
-- All interactive elements are keyboard accessible
-- Focus management:
-  - Opening popover focuses first day
-  - Closing popover returns focus to trigger
-- Visible focus rings on all interactive elements
-- Respects user's locale for month names and date formatting
-
-## Styling
-
-The component uses design tokens from the Reliability Design System. All colors, spacing, and typography are inherited from CSS variables.
-
-Key tokens used:
-- `--rel-bg-*` / `--rel-text-*` / `--rel-border-*` semantic colors
-- `--rel-spacing-*` for spacing
-- `--rel-body-*` composite typography roles
-- `--rel-border-*` / `--rel-border-radius-*` tokens
-- `--rel-shadows-*` for popover shadow
-- Selected date: `--rel-bg-brand`
-- Today indicator: `--rel-bg-info`
-- Focus rings: `--rel-bg-info`
-
-## Date Format
-
-- **Input/Output**: ISO 8601 format (YYYY-MM-DD)
-- **Display**: Localized format based on `locale` attribute
-- **Example**:
-  - Value: `"2026-01-16"`
-  - Display (en-US): `"January 16, 2026"`
-  - Display (es-ES): `"16 de enero de 2026"`
-
-## Browser Support
-
-Works in all modern browsers with ES2020 support and native Web Components.
+# 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 60% 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 -->
+
+## 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, and it repositions on scroll/resize. 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.