@lekoala/date-picker 0.1.0

package/docs/ARCHITECTURE.md

@@ -0,0 +1,183 @@
+# Architecture
+
+## Goal
+
+The package should remain much smaller than a scheduling calendar while covering the cases where a normal date field stops being enough.
+
+The key architectural rule is that **the calendar is the primitive and the picker is a composition**.
+
+```text
+civil date helpers
+       ↓
+CalendarModel
+       ↓
+<date-calendar> ── source / date state / day decoration
+       ↓
+<date-picker> ─── input / parse+format / Popover / floating
+       ↓
+linkDateRange() or application navigation
+```
+
+## 1. Civil dates are the canonical model
+
+Public values are `YYYY-MM-DD` strings. Public months are `YYYY-MM` strings.
+
+A selected date is not an instant. The core therefore does not expose a JavaScript `Date`, epoch milliseconds, UTC conversion, timezone or `Temporal` object as the canonical API.
+
+`Date` is used internally only as a browser primitive for safe UTC calendar arithmetic and `Intl.DateTimeFormat` presentation.
+
+This keeps form values predictable and avoids accidental midnight/timezone conversions.
+
+## 2. Four distinct concepts
+
+The component must never collapse these concepts:
+
+```text
+display   = month currently rendered
+focus     = current keyboard target
+activate  = date explicitly actioned by click / Enter / Space
+value     = selected date
+```
+
+Examples:
+
+- changing the month select changes `display`, not `value`;
+- pressing ArrowRight changes `focus`, not `value`;
+- pressing Enter emits `dateactivate`;
+- in `selection="single"`, accepted activation also updates `value`;
+- in `selection="none"`, activation is left entirely to the consumer.
+
+This is what lets the same `<date-calendar>` power both a date picker and the mini-calendar beside `@lekoala/calendar`.
+
+`highlightedRange` is a separate, strictly explanatory concept: it paints a band over rendered cells (`data-range-start` / `data-in-range` / `data-range-end`) without touching `display`, `focusedDate`, activation or `value`. The picker, an inline calendar or an app-owned controller can attach a range for display; the band is validated by `normalizeRange()` (ordered, never reordered) so the presentation never represents a range the model would contest. The business range (which may be temporarily inverted or in progress) stays in whichever controller owns it and is only forwarded to `highlightedRange` when it is displayable.
+
+## 3. True month math vs presentation
+
+`dates.getMonthWeeks()` returns the true civil weeks that cover a month: 4, 5 or 6 full rows.
+
+It does not know whether the UI wants a stable height.
+
+`<date-calendar fixed-weeks>` pads the rendered grid to six rows. That choice belongs to presentation, not date math.
+
+This mirrors the existing `@lekoala/calendar` direction: surrounding UI can consume the same true month primitive and decide how to display it.
+
+## 4. DOM ownership
+
+`<date-calendar>` owns the grid structure, focus semantics and interactive cells. A consumer cannot replace the day `td`.
+
+Two extension seams are intentionally narrow:
+
+### `dateState(date, sourceState)`
+
+Returns state/metadata for one day. The core reads only generic fields such as:
+
+- `disabled`;
+- `description`.
+
+Everything else remains application metadata.
+
+### `renderDay(date, state)`
+
+Returns a `Node`, `DocumentFragment`, string or nothing. The result is appended inside a component-owned, non-interactive, `aria-hidden` container. That container name is an implementation detail: consumers style the nodes they return and keep their own class names.
+
+Accessible meaning belongs in `state.description`, not in purely visual dots/badges.
+
+This prevents rich decorations from breaking grid semantics or keyboard behavior.
+
+## 5. Constraints have one resolution path
+
+`calendar.getDateState(date)` composes:
+
+1. remote/source state;
+2. `dateState()` application state;
+3. `min` / `max`;
+4. `isDateDisabled()`.
+
+`enabled: true` is the explicit exception seam: it can reopen a date disabled by generic/source rules, but never bypasses hard `min`/`max` bounds.
+
+Both click activation and typed picker validation use this resolved state.
+
+There should not be one "disabled" implementation for the grid and another for manual text input.
+
+## 6. Async source contract
+
+A source is either a function or an object with `load()`:
+
+```js
+load({ start, end }, { signal })
+```
+
+The range is inclusive and covers the cells actually rendered for that month. With `fixed-weeks`, this can extend beyond the month itself.
+
+Navigation cancels superseded loads using `AbortController`. Results are normalized to a map keyed by date.
+
+A load reports three outcomes: `loaded`, `cancelled` and `failed`. A cancelled or failed load never authorizes a date: `ensureDate()` returns `false` and both cell activation and typed picker validation refuse the date until a later load confirms it. `dateloaderror` keeps observing the failure; the loader error is never swallowed silently on the validation path.
+
+Supported response shapes:
+
+```js
+{ dates: { "2026-09-10": {...} } }
+{ "2026-09-10": {...} }
+[{ date: "2026-09-10", ...state }]
+```
+
+No server URL, query parameter names or backend schema are hard-coded into the core. `createFetchSource()` is only a convenience adapter.
+
+## 7. Picker composition
+
+`<date-picker>` enhances a direct child text input.
+
+The visible input owns:
+
+- label association;
+- focus;
+- typing;
+- required state;
+- validation UI;
+- the localized display string.
+
+A hidden input receives the original `name` and owns canonical form submission. This avoids Flatpickr's "pretty format means no editable input" tradeoff while preserving ordinary form submission.
+
+The picker creates a `<date-calendar selection="none">` in a native manual popover. On `dateactivate`, it commits the canonical value, formats the visible input and closes the popup.
+
+## 8. Popup responsibilities
+
+Native Popover owns the top layer. `@lekoala/floating` owns coordinates and geometry updates.
+
+The picker does not implement:
+
+- custom portals;
+- dropdown parent options;
+- manual clipping calculations;
+- z-index escalation APIs.
+
+The popup remains in authored DOM, preserving inherited locale/theme/density context.
+
+## 9. Range relationships
+
+Two product shapes cover the range cases, and both keep range rules outside the classes:
+
+`<date-picker range>` shares **one** calendar surface between two editable fields. Each input is owned by a `DateFieldController` (parsing, hidden ISO, commit/stale protection); the pair is driven by `DateRangeController` in `date-range.js`, which owns the active-endpoint transitions and the start/end state. `DatePickerElement` remains a shell: it coordinates DOM/popup/focus only. `value` is unavailable in range mode and `range` is the atomic pair API; inverted or incomplete business ranges are never forwarded to `highlightedRange`, which stays presentation-only.
+
+`linkDateRange(start, end)` keeps the external relationship for two visually separate pickers:
+
+```text
+end.min = max(authorMin, start.value)
+start.max = min(authorMax, end.value)
+```
+
+It does not auto-correct values. If a new start date makes the current end invalid, the end input becomes invalid and the user decides what value replaces it.
+
+## 10. Keep the class small
+
+If `DateCalendarElement` or `DatePickerElement` starts absorbing pure rules, move them out.
+
+Expected homes:
+
+- date arithmetic → `date.js`;
+- locale parsing/formatting → `intl.js`;
+- state transitions → `calendar-model.js`;
+- payload normalization/fetch adapter → `source.js`;
+- start/end relationship → `date-range.js`.
+
+Do not add a plugin system to solve a one-off rendering need.

package/docs/AT-CHECKLIST.md

@@ -0,0 +1,63 @@
+# Manual accessibility test pass
+
+Automated Playwright covers interaction invariants; this checklist now distinguishes what the repo can re-check from what only a human with a real screen reader, keyboard or visual review can confirm.
+
+Release decision (0.1.0): the human reader/OS pairings below are **deferred past 0.1** — the automated portion is the 0.1 gate, and the [Recommended manual test matrix](ACCESSIBILITY.md#recommended-manual-test-matrix) plus the Record table stay open until the passes are actually run and logged.
+
+## Legend
+
+- `[auto]`: can be verified in-repo with Playwright and DOM assertions.
+- `[manual]`: requires a human AT or visual pass.
+- `[split]`: behavior can be checked automatically here, but announcement or perception still needs a human pass. Leave these unchecked until the manual portion is done.
+
+## Setup
+
+- Engines: Chrome/Narrator (Windows), Firefox/NVDA, macOS/VoiceOver at least once.
+- Contrast: run `color-contrast` review in DevTools on the demo plus a forced-colors spot check.
+- Page under test: `demo/index.html` (uses `fr-BE` labels) and `test/fixtures/form-state.html`.
+
+## Keyboard only
+
+- [x] [auto] Tab reaches the input, the popup button and the month/year selects as native controls.
+- [x] [auto] Inside an open popup, Tab enters the grid on exactly one `tabindex="0"` cell.
+- [x] [auto] Arrow keys move by day, ArrowUp/ArrowDown by week; no date is selected while moving.
+- [x] [auto] Home/End move to the first/last cell of the week.
+- [x] [auto] PageUp/PageDown move month; Shift+PageUp/PageDown move year; focus follows across a month boundary.
+- [x] [auto] Enter/Space activates and, in `selection="single"`, selects.
+- [ ] [split] Disabled days stay focusable via arrow keys but never select; reason is announced (behavior covered automatically; announcement still manual).
+- [x] [auto] Escape in the picker closes the popup and restores focus to the input; in a `<dialog>`, the second Escape closes the dialog.
+- [x] [split] Month/year selects and prev/next buttons work without a pointer (control behavior covered automatically; manual keyboard/AT pass still open).
+- [x] [manual] Links/callback-seam cases (U8): all demo cards operate without a pointing device.
+
+## Screen reader
+
+- [ ] [manual] The grid is announced as a table with full weekday names (`abbr` expands).
+- [ ] [split] `aria-current="date"` marks today; `aria-selected` marks the selection (attributes present in DOM; announcement still manual).
+- [ ] [split] Each cell's accessible name includes the full date and, when present, the `description` (ARIA label content is present in DOM; announcement still manual).
+- [ ] [manual] Disabled cells announce "unavailable" distinctly.
+- [ ] [split] The picker input announces its role (combobox), the popup trigger, and the format hint (attributes wired in DOM; announcement still manual).
+- [ ] [split] The popup announces as a dialog with a label, and `aria-modal` stays absent (role/label/absence are wired in DOM; announcement still manual).
+- [ ] [manual] The mini calendar + `calendar-view` demo announces both parts; activating a day announces the agenda navigation.
+- [ ] [manual] Month/year navigation and source loading announcements are not clipped or repeated twice.
+
+## Form & lifecycle
+
+- [x] [auto] Typing a valid localized date updates the field validation state (no stale invalid message).
+- [x] [split] Typing an impossible date produces an announced invalid message (native invalid state/message covered automatically; announcement still manual).
+- [x] [manual] Forced-colors mode keeps selected/today/disabled distinguishable — including a selected day when `Highlight` resolves near-white (no white-on-white from `--dp-accent`; spot-checked with the forced-colors screenshot bundle).
+
+## Automated pass
+
+- Date: 2026-09-06.
+- Engines: Chromium, Firefox, WebKit.
+- Browser command run: `bun run test:browser:accessibility`.
+- Result: 124 browser tests passed and 2 were skipped across the configured desktop projects; the forced-colors style assertion is Chromium-only.
+- Forced-colors spot check: `bun run shot:forced-colors:important` reviewed manually after the selected-day forced-colors fix.
+
+## Record
+
+Run once per supported screen reader pairing, then add the date, the pair (OS + reader + browser), and any failures as issues. Still open for 0.1.0.
+
+| Date | OS / reader / browser | Result | Regression issues |
+| --- | --- | --- | --- |
+|  |  | ✅ / ❌ |  |

package/docs/CALENDAR-INTEGRATION.md

@@ -0,0 +1,70 @@
+# Integration with @lekoala/calendar
+
+The mini calendar is intentionally a consumer of the date-picker package, not a feature duplicated inside the scheduling engine.
+
+The live integration lives in `demo/index.html` (card 6): a real `<calendar-view view="month">` is wired to the mini calendar. `@lekoala/calendar` (and its `temporal-polyfill` peer) are dev dependencies used by the demo only.
+
+`@lekoala/calendar` already exposes the right navigation seam:
+
+```js
+calendar.gotoDate("2026-09-10");
+```
+
+A minimal sidebar navigator therefore looks like this:
+
+```html
+<date-calendar id="mini"
+               selection="none"
+               fixed-weeks
+               show-week-numbers></date-calendar>
+
+<calendar-view id="agenda"></calendar-view>
+```
+
+```js
+const mini = document.querySelector("#mini");
+const agenda = document.querySelector("#agenda");
+
+mini.display = agenda.date.toString().slice(0, 7);
+mini.focusedDate = agenda.date.toString();
+
+mini.addEventListener("dateactivate", (event) => {
+  agenda.gotoDate(event.detail.date);
+});
+
+agenda.addEventListener("calendar:datechange", (event) => {
+  const date = event.detail.date.toString();
+  mini.display = date.slice(0, 7);
+  mini.focusedDate = date;
+});
+```
+
+Notice what is missing: the mini calendar does not need a selected value. The agenda anchor is application/calendar state, not form selection state.
+
+## Active week / availability decoration
+
+Application state can decorate the mini calendar without changing its navigation semantics:
+
+```js
+mini.dateState = (date, sourceState) => ({
+  ...sourceState,
+  description: isBookable(date)
+    ? "Bookable; activate to navigate"
+    : "Closed; activate to navigate"
+});
+
+mini.renderDay = (date, state) => state.available ? "•" : "";
+```
+
+A closed day can still navigate an administrative agenda. Do not set `disabled` merely because booking is unavailable unless activation itself is forbidden for this particular calendar.
+
+That distinction mirrors the showcase rule: navigation policy and booking policy are different concerns.
+
+## Shared month math
+
+Both packages expose month-week derivation. They stay **deliberately duplicated**, each owning its own contract:
+
+- `@lekoala/calendar` owns Temporal-based math (`Temporal.PlainDate`).
+- `@lekoala/date-picker` owns civil string math (`dates.getMonthWeeks()`, `YYYY-MM-DD`).
+
+This keeps the two packages dependency-free from each other: a circular dependency between a picker and a scheduler would cost more than a few duplicated lines. `dates.getMonthWeeks()` keeps the scheduler's important contract (full civil weeks, configurable first day, 4–6 rows, no forced padding) so both stay interchangeable for the mini-calendar seam. A future shared `@lekoala/date-math` package is possible, but only as a separate proposal; it must not introduce a circular dependency.

package/docs/DECISIONS.md

@@ -0,0 +1,40 @@
+# Decisions
+
+Frozen contracts for the `0.1.0` surface. A change to a decision below is a breaking change and needs a proposal, not an opportunistic edit.
+
+## D1 — Calendar events are flat, verb-named
+
+Never merged with the `value` concept (`dateactivate` is activation, not `value`).
+
+- `date-calendar`: `dateactivate`, `datechange`, `dateinvalid`, `displaychange`, `dateloadstart`, `dateloadend`, `dateloaderror`.
+- `date-picker`: `valuechange`, `open`, `close`.
+
+No `dp:` namespace prefix on element events, even though `@lekoala/combobox` namespaces its events (`combobox:*`).
+
+Rationale: the flat names describe a distinct concept (`dateactivate`), never collide with native input events, and are already wired through the docs, demos and tests. A namespace is not worth the churn for this package.
+
+## D2 — `selection="none"` is the final spelling
+
+The navigation-only calendar keeps `selection="none"`.
+
+`selection` remains a value attribute (`single` | `none`); it is how the mini calendar speaks the navigation contract: accepted activation dispatches `dateactivate`, `value` is untouched.
+
+## D3 — CSS: `--dp-*` is public, `.dp-*` is not
+
+> `--dp-*` is the public styling namespace. `.dp-*` identifies component-owned DOM but is not a public styling API unless explicitly documented.
+
+- The namespace prefix is `dp`, final. There are no `--lko-dp-*` or `.lko-dp-*` classes. A shared `--lko-*` token space is reserved for tokens actually shared between LeKoala packages, not as a per-component prefix.
+- The `--dp-*` custom properties (background, foreground, accent, border, radius, day-size, gap, …) are the **public customization surface**. They are listed in `custom-elements.json` and are stable.
+- Every `.dp-*` class is **internal DOM** and may change, move or disappear without a semver bump. This includes `.dp-day`, `.dp-grid`, `.dp-picker-panel` and the day-extra container.
+- `renderDay()` is a public extension seam, but the name of the container its output is placed into is **not** promised. Consumers style their own returned nodes and assign their own class names.
+- Demos, tests and internal code may reference `.dp-*` classes; their use there does not turn those classes into public API.
+
+Context: DOM-backed styling hooks become API the moment they are documented — every internal rename then breaks consumers. We prefer to expose hooks (`--dp-*`, `renderDay()`, events) and keep the rendered anatomy free to evolve.
+
+## D4 — `<date-picker>` opens on focus; `open` is read-only
+
+- The picker opens its popover when the input receives focus (`open-on-focus`, default `true`; set `open-on-focus="false"` to opt out).
+- Opening on focus **never steals keyboard focus**: the user can start typing immediately. The grid takes focus only on ArrowDown, on the calendar trigger, or after the user moves the pointer into the popup.
+- `show()` / `hide()` are the control surface. `open` is a **read-only getter** reflecting the popover. There is no `open` attribute: the popover element is the single machine of truth and a second state machine would only drift.
+- `readonly` mirrors native semantics: the field is non-editable, the value is still submitted, and the picker cannot change it — the calendar trigger is disabled. `disabled` additionally unsubmits the field. `readonly` is never used to mean "no typing, but calendar selection allowed".
+- Clearing the editable input clears the canonical value (the component renders no internal clear button). Form resets follow the native `defaultValue` contract. This matches the Open UI datepicker `clear` concept: clearing is a text-editing action, not a component-owned affordance.

package/docs/MIGRATION-FLATPICKR.md

@@ -0,0 +1,92 @@
+# Flatpickr / Formidable migration map
+
+This prototype was scoped against the existing `FlatpickrInput` wrapper rather than against Flatpickr's full feature list.
+
+## Directly covered
+
+| Existing need             | New direction                                              |
+|---------------------------|------------------------------------------------------------|
+| canonical `Y-m-d` value   | `date-picker.value` / hidden form value `YYYY-MM-DD`       |
+| localized pretty display  | `Intl` numeric adapter while staying editable              |
+| `minDate` / `maxDate`     | `min` / `max`                                              |
+| disable callback          | `isDateDisabled(date)`                                     |
+| dynamic enable/disable    | source state + `dateState()`                               |
+| `configUrl` on navigation | abortable `source.load({start,end}, {signal})`             |
+| bars/events on dates      | source metadata + `renderDay()` + accessible `description` |
+| inline calendar           | `<date-calendar>`                                          |
+| previous/next month       | calendar methods/buttons                                   |
+| direct month/year choice  | native month/year selects                                  |
+| start/end relation        | `linkDateRange(start, end)`                                |
+| locale                    | `Intl` locale + small control-message dictionaries         |
+| value-changed hook        | `valuechange` / native input+change events                 |
+
+## The display-format change is intentional
+
+The old wrapper has to choose between a rich localized display and manual editing because Flatpickr cannot reliably parse arbitrary long localized output.
+
+The new default is deliberately less decorative and more useful:
+
+```text
+fr-BE: 06/09/2026
+ en-US: 09/06/2026
+```
+
+The pattern is generated with `Intl.DateTimeFormat(...).formatToParts()`, so the same adapter can format and parse it.
+
+Long dates such as `6 septembre 2026` remain presentation content, not the editing format of the field.
+
+## Dynamic source payload
+
+Legacy payload:
+
+```json
+{
+  "enable": ["2025-06-07"],
+  "events": [
+    "2025-06-07",
+    { "date": "2025-06-09", "class": "bg-danger" }
+  ]
+}
+```
+
+Suggested new payload:
+
+```json
+{
+  "dates": {
+    "2025-06-07": {
+      "disabled": false,
+      "description": "Available"
+    },
+    "2025-06-09": {
+      "description": "Limited availability",
+      "status": "danger"
+    }
+  }
+}
+```
+
+The backend returns meaning, not CSS class names. The consumer decides how `status` is rendered.
+
+## Explicit enable-overrides-disable
+
+If an application currently relies on a remote `enable` list overriding a generic disabled rule (for example: weekends disabled except one exceptional Saturday), implement that policy in one `dateState` resolver:
+
+```js
+calendar.isDateDisabled = (date) => isWeekend(date);
+// Source state { enabled: true } is an explicit exception to the generic
+// weekend rule. Hard min/max bounds still win.
+```
+
+The prototype promotes this legacy behavior into a documented generic field: `enabled: true` reopens a date disabled by `isDateDisabled()` or ordinary source state, but never bypasses hard `min`/`max` bounds.
+
+## Not migrated into this component
+
+The existing wrapper also exposes Flatpickr features that should not be carried into the date picker core:
+
+- `enableTime`;
+- `noCalendar` / time-only;
+- confirm-date plugin;
+- month-as-value selection plugin.
+
+Those are separate controls/use cases. Adding them here would immediately mix civil-date selection with time and alternate value models.

package/docs/ROADMAP.md

@@ -0,0 +1,105 @@
+# Roadmap
+
+## P0 — prove the contracts
+
+- [x] canonical civil-date helpers;
+- [x] true month weeks;
+- [x] `value / display / focused` split;
+- [x] inline `<date-calendar>`;
+- [x] navigation-only selection mode;
+- [x] month/year controls;
+- [x] APG-style grid keyboard interaction;
+- [x] localized editable adapter;
+- [x] `<date-picker>` Popover + floating composition;
+- [x] source contract with AbortController;
+- [x] day state + safe decoration seam;
+- [x] start/end linking primitive;
+- [x] unit/browser test skeleton;
+- [x] demos and architecture docs.
+
+## P1 — hardened before 0.1 (shipped in 0.1.0)
+
+- [x] run TypeScript 7/Biome/Bun checks in the actual repo;
+- [x] run Playwright on all engines;
+- [x] manual AT checklist and record ([docs/AT-CHECKLIST.md](AT-CHECKLIST.md)); the automated portion is the 0.1 gate, the human reader/OS rows track as a post-0.1 recommendation;
+- [x] add a real `@lekoala/calendar` mini-calendar integration demo;
+- [x] validate Popover behavior inside `<dialog>` and nested app surfaces;
+- [x] test form reset, disabled toggles and dynamic name/form ownership;
+- [x] decide exact event naming — flat `dateactivate` etc. ([DECISIONS.md](DECISIONS.md), D1);
+- [x] decide whether `selection="none"` is the final public spelling — yes (D2);
+- [x] decide public styling tokens/class names — `--dp-*` public, `.dp-*` internal (D3);
+- [x] decide the shared-range picker shape — `<date-picker range>` + `linkDateRange` (U9/U5);
+- [x] decide the popup modality on touch surfaces — stays non-modal in 0.1 ([ACCESSIBILITY.md](ACCESSIBILITY.md));
+- [x] add custom-elements manifest once names stabilize — `custom-elements.json`;
+- [x] add package/generated-artifact checks like `@lekoala/combobox`;
+- [x] commit `bun.lock` and freeze installs in CI.
+
+## P2 — real-world migration
+
+Use Formidable/Flatpickr cases as migration fixtures:
+
+- remote enable/disable payload;
+- date markers/events → metadata/decoration;
+- French/Spanish locale → shipped locale message dictionaries (`ar`, `de`, `en`, `es`, `fr`, `hi`, `id`, `it`, `ja`, `ko`, `nl`, `pl`, `pt-BR`, `pt-PT`, `ru`, `tr`, `zh-CN`);
+- initial canonical values;
+- inline calendar;
+- linked start/end fields;
+- month navigation source refresh.
+
+## Explicitly deferred
+
+These should require a separate proposal, not opportunistic growth:
+
+- time picker / datetime picker;
+- single-grid visual **selection** interaction (the band itself is core presentation via `calendar.highlightedRange`);
+- month-as-value picker;
+- multi-date;
+- recurrence;
+- timezone-aware values;
+- natural-language parsing;
+- plugin registry;
+- multiple visible months;
+- swipe gestures;
+- full calendar/scheduler features.
+
+## Open UI nomenclature reference
+
+Cross-check our coverage against the Open UI datepicker research: <https://open-ui.org/components/datepicker.research/> — a cross-design-system vocabulary inventory for date pickers (2023, no longer maintained). It is a term checklist, not a behavior specification; normative behavior stays with the WAI-ARIA APG grid/dialog patterns and the HTML spec. Use these terms as-is in proposals instead of re-defining them.
+
+| Open UI concept | Status | Note |
+| --- | --- | --- |
+| `open` | core | `show()` / `hide()` with a read-only `open` getter (D4). |
+| `navigation` | core | month/year selects plus prev/next buttons (P0). |
+| `selected` | core | `aria-selected` mapped from `value`. |
+| `disabled` | core | native disabled state on the component and its controls. |
+| `disabled dates` | core | `min` / `max`, `isDateDisabled`, source state (P0). |
+| `required` | core | forwarded to the visible native input. |
+| `manual input` | core | editable native field with localized parsing (U1). |
+| `format` | core | `intl.js`; format hint exposed via `aria-describedby`. |
+| `error` | core | distinct `setCustomValidity` messages for invalid vs unavailable dates. |
+| `readonly` / `disabled` | core | native semantics kept separate (D4). |
+| `default` | core | form reset via `defaultValue` (D4). |
+| `clear` | contract boundary | no internal clear button; clearing happens by editing the text input (D4). |
+| `custom cells` | contract boundary | `renderDay()` only; cells stay component-owned (D3). |
+| `weeknumber` | contract boundary | `show-week-numbers` (U3). |
+| `custom weeks` | no | only the `first-day` attribute; no custom week rendering. |
+| `range` | core | `<date-picker range>` two-field shared surface (U9); `linkDateRange()` stays external (U5). |
+| `range selected` | deferred | selection interaction needs its own proposal; `highlightedRange` covers band presentation only. |
+| `range presets` | deferred | application-owned. |
+| `date-time picker` | deferred | time/datetime is explicitly out of scope. |
+| `side by side` | deferred | maps to "multiple visible months". |
+| `footer` | deferred | not part of the grid contract. |
+| `shape`, `size`, `compact`, `subtle`, `light`, `borderless`, `no icon` | app-owned | styling via public `--dp-*` tokens (D3), not a component API. |
+
+## Related prior art: Duet Date Picker
+
+<https://github.com/duetds/date-picker> — a Web Components date picker by the Duet Design System (MIT, Stencil, ~10 kb). The repository was **archived in 2024**; treat it as a source of observed behaviors, not maintained API reference. It validates several of our choices and highlights points we must decide:
+
+- `isDateDisabled` (same seam name as ours), hidden-input ISO submission, `formatLongDate`-style cell labels ("17 November 2020"), month/year announced on change, and a real `table[role="grid"]` with a single roving tab stop — all mirrored in this package.
+- **Differs from us on the canonical model**: its `dateAdapter` and events work with `Date` objects (`valueAsDate`). That is the exact `Date`-object tradeoff our canonical `YYYY-MM-DD` strings avoid.
+- **Differs on modality**: it ships a modal dialog with overlay and an explicit close button, while our popup intentionally stays non-modal (`aria-modal` absent). `docs/ACCESSIBILITY.md` still holds the open question of going modal on small/touch surfaces.
+- **Tab wrap-around**: Duet cycles focus back to the first focusable element inside the dialog. Our non-modal popup lets Tab leave the picker — decided, documented in `docs/ACCESSIBILITY.md`.
+- **Opening focus target**: Duet moves focus to the first (month) select on open; we focus the grid — a deliberate divergence (ArrowDown / trigger button enter the grid).
+- **Deferred alignments**: Duet's touch gestures and modified mobile interface map to our explicit "swipe gestures" deferral.
+
+Resolved without further work: popover flipping near an edge is handled by `@lekoala/floating`, so no `direction`-style prop is needed; the open-popover `Tab` contract is decide-and-document only (see above), not code.

package/docs/TESTING.md

@@ -0,0 +1,73 @@
+# Testing
+
+## Fast loop
+
+```bash
+bun run test:syntax
+bun run typecheck
+bun run test
+```
+
+Pure date math, locale parsing and model transitions belong in `test/unit` and must remain DOM-free.
+
+## Browser loop
+
+```bash
+bun run test:browser
+```
+
+Chromium covers the fast interaction loop. Before release:
+
+```bash
+bun run test:browser:all
+```
+
+runs Chromium, Firefox and WebKit.
+
+For the accessibility-adjacent browser subset used by the AT checklist:
+
+```bash
+bun run test:browser:accessibility
+```
+
+This runs the focused picker/calendar/focus/form/surface specs across the configured desktop projects, including the forced-colors regression check in `calendar.spec.js`.
+The forced-colors style assertion follows the Chromium capture pipeline, so it is intentionally skipped on Firefox and WebKit.
+
+## What belongs in browser tests
+
+Browser tests should cover behavior that cannot be trusted to a DOM shim:
+
+- Popover open/close;
+- focus movement and roving tabindex;
+- real keyboard events;
+- month/year selects;
+- form submission shape;
+- floating placement staying in the viewport;
+- outside pointer close;
+- source cancellation;
+- range validation;
+- forced-colors/zoom smoke cases.
+
+## Core invariants
+
+Keep explicit tests for these regressions:
+
+1. `value`, `display` and `focusedDate` are independent.
+2. Month/year navigation never selects.
+3. Arrow navigation never selects.
+4. `dateactivate` is the only user activation seam.
+5. `selection="none"` never mutates `value`.
+6. `getMonthWeeks()` never pads.
+7. `fixed-weeks` renders 42 day cells.
+8. Outside-month cells can activate.
+9. Source navigation aborts stale loads.
+10. Typed and clicked dates resolve the same disabled state.
+11. Start/end linkage never silently changes sibling values.
+12. Exactly one grid cell has `tabindex="0"`.
+13. A failed or cancelled source load never authorizes activation or validation.
+
+## CI
+
+The included workflow uses Bun 1.4.2 and runs static checks/unit tests before Playwright.
+
+`bun.lock` is committed. Keep installs frozen in CI (`bun install --frozen-lockfile`) so dependency resolution stays deterministic. Regenerate the lock with `bun install` when the manifest changes and commit it in the same change.