@lekoala/date-picker 0.5.1 → 0.5.2

package/docs/DECISIONS.md

@@ -1,74 +1,74 @@
-# Decisions
-
-Frozen contracts for the public 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`, `datefocus`, `datechange`, `dateinvalid`, `displaychange`, `dateloadstart`, `dateloadend`, `dateloaderror`.
-- `date-picker`: `valuechange`, `open`, `close`, plus `rangechange` in range mode.
-
-The observation verbs stay distinct: `datefocus` observes navigation, `dateactivate` requests an activation (and is cancelable), `datechange` observes a selection. `datefocus` is named after the user event rather than after the `focusedDate` setter, so a programmatic assignment that moves no DOM focus never announces one.
-
-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.
-- Closing returns focus to the control that opened the popover (field or trigger) — the usual popover convention. Range mode is the exception: focus follows the active bound, because a first pick moves the workflow to the other bound.
-- The calendar trigger is overlaid inside the field's own box, like the native `input[type=time]` indicator. The field reserves its place (`padding-inline-end`), keeps its border/background, and owns the focus ring for the pair; the trigger is a real button with an inner ring of its own. A range bound owns its own trigger; the two share one popup, calendar, source and state.
-- `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.
-
-## D5 — Time is a native companion, not picker state
-
-- Time fields are authored native `input[type=time]` marked `[data-time-start]` / `[data-time-end]`; `name`, `value`, `required`, `min`, `max`, `step` and submission stay native. There is no hidden time input and no time field controller.
-- `picker.value` / `picker.range` remain date-only (`YYYY-MM-DD`); the picker never constructs a datetime, a timestamp or a timezone-bearing value.
-- The picker only coordinates from/to order (`start <= end`, equality allowed); duration rules stay application-owned.
-- Custom time UI and slot picking stay outside the package.
-
-## D6 — Calendar interaction never produces an inverted range
-
-Pointing and typing are different contracts, deliberately.
-
-- **Interaction** (click, keyboard, endpoint drag) always yields an ordered range. While a range is being created, the second selection is sorted against the anchor: `10` then `5` commits `5 -> 10`, and `10` then `10` a one-day range. No `dateinvalid` is fired merely because the second point is earlier.
-- **Text entry** may be temporarily inverted. Typing `start` past `end` keeps both values and reports `rangeOrderStart` / `rangeOrderEnd` on the modified bound, because a half-typed pair is a normal editing state.
-- An explicit change to **one bound of an already complete pair** keeps that bound's identity: moving `end` before `start` is refused rather than silently rewriting the other field.
-- Because one interaction can move both bounds at once, a transition describes the whole resulting pair (`{ status, endpoint, changedEndpoints, range, activeEndpoint }`) and is applied in a single write: one `rangechange`, with synthetic `input` / `change` only on the bounds that actually moved.
-- Hover, keyboard focus and endpoint drag read the **same projection** (`previewRange()`) that the commit applies, so what the band promises is what the next selection commits. A preview writes nothing: no `rangechange`, no field write, no validation, no source request.
-- Click, keyboard and drop all end in that one range machine and in the same `ensureDate` plus cancelable `dateactivate` path, so an application veto cannot be bypassed by choosing another input device.
-
-## D7 — Author classes own header control styling
-
-`controlClasses` and `setDefaultControlClasses()` are the public hooks for styling the month, year and navigation roles with a host design system. A role with non-empty author classes receives no library skin, including in forced colors. Layout remains component-owned. Roles without author classes retain the default skin.
-
-The `.dp-*` namespace stays internal (D3); it is reserved and ignored in author class lists. Day grid cells and the picker trigger are outside this API. There is no HTML attribute.
-
-## D8 — Defaults are accessible through registered constructors
-
-Both element classes expose static `setDefaultControlClasses`, `getDefaultControlClasses`, `setDefaultMessages` and `getDefaultMessages` methods delegating to the existing module functions. This additive API makes defaults available in classic builds through `customElements.get()` without introducing a global. The constructors share one defaults state within a build. Instances without overrides resolve current defaults when used, and connected instances refresh when defaults change. Disconnected instances unsubscribe and read current defaults on reconnection. For `controlClasses`, an assignment stores only the normalized roles provided: omitted roles follow current global defaults at read/render time, an explicit empty string restores the library skin for that role, and `null` follows all defaults. Global class changes also refresh instances with partial overrides. Message assignments merge with current defaults and pin that instance setting; `null` resumes following global message defaults. Pickers forward only their own overrides to their calendar, preserving global inheritance.
-
-Writable public properties assigned before element definition are replayed through their setters on connection. Options are applied before building controls; picker `value` and `range` wait for the fields and range controller. The display, focus, activation and selection contracts remain distinct.
+# Decisions
+
+Frozen contracts for the public 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`, `datefocus`, `datechange`, `dateinvalid`, `displaychange`, `dateloadstart`, `dateloadend`, `dateloaderror`.
+- `date-picker`: `valuechange`, `open`, `close`, plus `rangechange` in range mode.
+
+The observation verbs stay distinct: `datefocus` observes navigation, `dateactivate` requests an activation (and is cancelable), `datechange` observes a selection. `datefocus` is named after the user event rather than after the `focusedDate` setter, so a programmatic assignment that moves no DOM focus never announces one.
+
+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.
+- Closing returns focus to the control that opened the popover (field or trigger) — the usual popover convention. Range mode is the exception: focus follows the active bound, because a first pick moves the workflow to the other bound.
+- The calendar trigger is overlaid inside the field's own box, like the native `input[type=time]` indicator. The field reserves its place (`padding-inline-end`), keeps its border/background, and owns the focus ring for the pair; the trigger is a real button with an inner ring of its own. A range bound owns its own trigger; the two share one popup, calendar, source and state.
+- `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.
+
+## D5 — Time is a native companion, not picker state
+
+- Time fields are authored native `input[type=time]` marked `[data-time-start]` / `[data-time-end]`; `name`, `value`, `required`, `min`, `max`, `step` and submission stay native. There is no hidden time input and no time field controller.
+- `picker.value` / `picker.range` remain date-only (`YYYY-MM-DD`); the picker never constructs a datetime, a timestamp or a timezone-bearing value.
+- The picker only coordinates from/to order (`start <= end`, equality allowed); duration rules stay application-owned.
+- Custom time UI and slot picking stay outside the package.
+
+## D6 — Calendar interaction never produces an inverted range
+
+Pointing and typing are different contracts, deliberately.
+
+- **Interaction** (click, keyboard, endpoint drag) always yields an ordered range. While a range is being created, the second selection is sorted against the anchor: `10` then `5` commits `5 -> 10`, and `10` then `10` a one-day range. No `dateinvalid` is fired merely because the second point is earlier.
+- **Text entry** may be temporarily inverted. Typing `start` past `end` keeps both values and reports `rangeOrderStart` / `rangeOrderEnd` on the modified bound, because a half-typed pair is a normal editing state.
+- An explicit change to **one bound of an already complete pair** keeps that bound's identity: moving `end` before `start` is refused rather than silently rewriting the other field.
+- Because one interaction can move both bounds at once, a transition describes the whole resulting pair (`{ status, endpoint, changedEndpoints, range, activeEndpoint }`) and is applied in a single write: one `rangechange`, with synthetic `input` / `change` only on the bounds that actually moved.
+- Hover, keyboard focus and endpoint drag read the **same projection** (`previewRange()`) that the commit applies, so what the band promises is what the next selection commits. A preview writes nothing: no `rangechange`, no field write, no validation, no source request.
+- Click, keyboard and drop all end in that one range machine and in the same `ensureDate` plus cancelable `dateactivate` path, so an application veto cannot be bypassed by choosing another input device.
+
+## D7 — Author classes own header control styling
+
+`controlClasses` and `setDefaultControlClasses()` are the public hooks for styling the month, year and navigation roles with a host design system. A role with non-empty author classes receives no library skin, including in forced colors. Layout remains component-owned. Roles without author classes retain the default skin.
+
+The `.dp-*` namespace stays internal (D3); it is reserved and ignored in author class lists. Day grid cells and the picker trigger are outside this API. There is no HTML attribute.
+
+## D8 — Defaults are accessible through registered constructors
+
+Both element classes expose static `setDefaultControlClasses`, `getDefaultControlClasses`, `setDefaultMessages` and `getDefaultMessages` methods delegating to the existing module functions. This additive API makes defaults available in classic builds through `customElements.get()` without introducing a global. The constructors share one defaults state within a build. Instances without overrides resolve current defaults when used, and connected instances refresh when defaults change. Disconnected instances unsubscribe and read current defaults on reconnection. For `controlClasses`, an assignment stores only the normalized roles provided: omitted roles follow current global defaults at read/render time, an explicit empty string restores the library skin for that role, and `null` follows all defaults. Global class changes also refresh instances with partial overrides. Message assignments merge with current defaults and pin that instance setting; `null` resumes following global message defaults. Pickers forward only their own overrides to their calendar, preserving global inheritance.
+
+Writable public properties assigned before element definition are replayed through their setters on connection. Options are applied before building controls; picker `value` and `range` wait for the fields and range controller. The display, focus, activation and selection contracts remain distinct.

package/docs/USE_CASES.md

@@ -1,156 +1,156 @@
-# Use cases
-
-These cases define the product more strongly than a feature checklist. A proposed API change should be tested against them before being accepted.
-
-## U1 — Editable localized date field
-
-A user can type `06/09/2026` in `fr-BE`, open the calendar, select the same date visually, and submit `2026-09-06` to the server.
-
-Acceptance:
-
-- input remains editable;
-- label still targets the real input;
-- required/custom validity still works;
-- display formatting does not leak into submitted data.
-
-## U2 — Inline selector
-
-An inline calendar owns one selected date.
-
-Acceptance:
-
-- month/year navigation does not change the value;
-- arrow-key focus does not change the value;
-- click/Enter/Space activates and selects;
-- today, focused and selected are visually/semantically distinct.
-
-## U3 — Mini calendar navigator
-
-An inline `selection="none"` calendar navigates a separate agenda/calendar.
-
-Acceptance:
-
-- there may be no selected value at all;
-- changing month/year only changes what the mini calendar displays;
-- activating a date dispatches `dateactivate` and the application calls `calendarView.gotoDate(date)`;
-- outside-month days remain activatable;
-- six-row height is available as presentation, not baked into month math;
-- ISO week numbers are available;
-- a narrow/compact presentation can use short month names (`month-format="short"`).
-
-## U4 — Constrained dates
-
-Example: only the next 90 days, weekdays only.
-
-Acceptance:
-
-- min/max affect both activation and typed validation;
-- custom disabled days can still receive keyboard focus so the reason can be announced;
-- disabled activation never changes the value;
-- previous/next controls stop at bounded months.
-
-## U5 — Linked start/end dates
-
-Two fields represent a range.
-
-Acceptance:
-
-- end cannot validate before start;
-- start cannot validate after end;
-- changing one side revalidates the other;
-- the component never silently rewrites the sibling value;
-- each picker remains independently usable and replaceable.
-
-## U6 — Remote availability
-
-Changing the displayed month loads per-day state from a backend.
-
-Acceptance:
-
-- load receives the actual rendered range;
-- superseded navigation aborts the previous request;
-- state can disable a day or describe it;
-- loading logic is independent of URL/backend format;
-- a typed date can call `ensureDate()` before validation.
-
-## U7 — Morning / afternoon indicators
-
-A date can carry richer state such as morning/afternoon availability.
-
-Acceptance:
-
-- the business fields remain opaque to core logic;
-- visual badges/dots live inside the owned day cell;
-- accessible meaning is supplied through `description`;
-- custom rendering cannot replace focus/ARIA semantics.
-
-## U8 — Keyboard-only operation
-
-Everything above works without a pointing device.
-
-Acceptance:
-
-- one grid cell in the Tab sequence;
-- arrows, Home/End, PageUp/PageDown, Shift+PageUp/PageDown work;
-- changing display follows keyboard focus when focus crosses a month;
-- activation requires Enter/Space;
-- Escape closes the picker and restores a sensible focus target;
-- month/year selects remain normal native controls.
-
-## U9 — Two fields, one shared calendar
-
-A form has two editable date fields (arrival/departure) that share a single calendar surface inside one picker popup.
-
-Acceptance:
-
-- each field stays independently editable and localized, with its own hidden ISO value for submission;
-- opening from a bound targets that bound: selecting a first date commits it, moves the active endpoint to the other bound without closing, and a second selection commits and closes;
-- once an ordered range is complete, activating before it extends the start and activating after it extends the end, regardless of the opening field; the opposite bound stays unchanged and readonly/disabled bounds remain protected;
-- a preloaded range shows the band on open and is never reordered;
-- month/year navigation and arrow-key focus never mutate either bound;
-- an inverted range (start after end) keeps both entered values and surfaces an order error on the bound that was just modified; changing either side revalidates both;
-- form reset restores both fields in one resync;
-- a stale async availability response arriving after the active endpoint changed never commits a value or closes the popup;
-- calendar interaction never produces an inverted range: while a range is being created, a second selection before the first is sorted (`10` then `5` commits `5 -> 10`) in one atomic update; an explicit change to one bound of an already complete pair keeps that bound's identity instead;
-- pointer hover and keyboard navigation project the range the next selection would commit onto the band, without changing any value, and a selection commits exactly what was projected;
-- the endpoints of a complete range can be dragged to adjust it, through the same projection, the same availability check and the same cancelable activation as a click;
-- only the bounds are validated; per-night availability stays application-owned.
-
-## U10 — Date with native time companions
-
-A form pairs a date with one or two native times (appointment at `09:30`, from/to on the same day).
-
-Acceptance:
-
-- times stay native `input[type=time]` fields with their own names and submission;
-- `value` stays a `YYYY-MM-DD` date;
-- an inverted from/to surfaces an order error on the modified bound;
-- a missing or disabled time lifts the order constraint;
-- calendar selection and form reset keep the entered times.
-
-## U11 — Host design system controls
-
-The calendar header uses application-owned control classes without styling internal `.dp-*` selectors.
-
-Acceptance:
-
-- author classes survive every render;
-- the library applies no border, background, caret, padding, hover, disabled or focus skin to a role with author classes;
-- controls stretch to equal heights, the year keeps its grid-track width and long month names truncate;
-- labels, keyboard navigation and focus restoration are unchanged;
-- controls without author classes keep the default skin.
-
-## Not a use case for this package
-
-Do not grow the API to cover these without a separate design:
-
-- time slots;
-- duration picking;
-- timezone conversion;
-- appointment recurrence;
-- resource scheduling;
-- drag/drop;
-- event rendering;
-- multi-day scheduler views.
-
-Those belong to `@lekoala/calendar` or application logic.
+# Use cases
+
+These cases define the product more strongly than a feature checklist. A proposed API change should be tested against them before being accepted.
+
+## U1 — Editable localized date field
+
+A user can type `06/09/2026` in `fr-BE`, open the calendar, select the same date visually, and submit `2026-09-06` to the server.
+
+Acceptance:
+
+- input remains editable;
+- label still targets the real input;
+- required/custom validity still works;
+- display formatting does not leak into submitted data.
+
+## U2 — Inline selector
+
+An inline calendar owns one selected date.
+
+Acceptance:
+
+- month/year navigation does not change the value;
+- arrow-key focus does not change the value;
+- click/Enter/Space activates and selects;
+- today, focused and selected are visually/semantically distinct.
+
+## U3 — Mini calendar navigator
+
+An inline `selection="none"` calendar navigates a separate agenda/calendar.
+
+Acceptance:
+
+- there may be no selected value at all;
+- changing month/year only changes what the mini calendar displays;
+- activating a date dispatches `dateactivate` and the application calls `calendarView.gotoDate(date)`;
+- outside-month days remain activatable;
+- six-row height is available as presentation, not baked into month math;
+- ISO week numbers are available;
+- a narrow/compact presentation can use short month names (`month-format="short"`).
+
+## U4 — Constrained dates
+
+Example: only the next 90 days, weekdays only.
+
+Acceptance:
+
+- min/max affect both activation and typed validation;
+- custom disabled days can still receive keyboard focus so the reason can be announced;
+- disabled activation never changes the value;
+- previous/next controls stop at bounded months.
+
+## U5 — Linked start/end dates
+
+Two fields represent a range.
+
+Acceptance:
+
+- end cannot validate before start;
+- start cannot validate after end;
+- changing one side revalidates the other;
+- the component never silently rewrites the sibling value;
+- each picker remains independently usable and replaceable.
+
+## U6 — Remote availability
+
+Changing the displayed month loads per-day state from a backend.
+
+Acceptance:
+
+- load receives the actual rendered range;
+- superseded navigation aborts the previous request;
+- state can disable a day or describe it;
+- loading logic is independent of URL/backend format;
+- a typed date can call `ensureDate()` before validation.
+
+## U7 — Morning / afternoon indicators
+
+A date can carry richer state such as morning/afternoon availability.
+
+Acceptance:
+
+- the business fields remain opaque to core logic;
+- visual badges/dots live inside the owned day cell;
+- accessible meaning is supplied through `description`;
+- custom rendering cannot replace focus/ARIA semantics.
+
+## U8 — Keyboard-only operation
+
+Everything above works without a pointing device.
+
+Acceptance:
+
+- one grid cell in the Tab sequence;
+- arrows, Home/End, PageUp/PageDown, Shift+PageUp/PageDown work;
+- changing display follows keyboard focus when focus crosses a month;
+- activation requires Enter/Space;
+- Escape closes the picker and restores a sensible focus target;
+- month/year selects remain normal native controls.
+
+## U9 — Two fields, one shared calendar
+
+A form has two editable date fields (arrival/departure) that share a single calendar surface inside one picker popup.
+
+Acceptance:
+
+- each field stays independently editable and localized, with its own hidden ISO value for submission;
+- opening from a bound targets that bound: selecting a first date commits it, moves the active endpoint to the other bound without closing, and a second selection commits and closes;
+- once an ordered range is complete, activating before it extends the start and activating after it extends the end, regardless of the opening field; the opposite bound stays unchanged and readonly/disabled bounds remain protected;
+- a preloaded range shows the band on open and is never reordered;
+- month/year navigation and arrow-key focus never mutate either bound;
+- an inverted range (start after end) keeps both entered values and surfaces an order error on the bound that was just modified; changing either side revalidates both;
+- form reset restores both fields in one resync;
+- a stale async availability response arriving after the active endpoint changed never commits a value or closes the popup;
+- calendar interaction never produces an inverted range: while a range is being created, a second selection before the first is sorted (`10` then `5` commits `5 -> 10`) in one atomic update; an explicit change to one bound of an already complete pair keeps that bound's identity instead;
+- pointer hover and keyboard navigation project the range the next selection would commit onto the band, without changing any value, and a selection commits exactly what was projected;
+- the endpoints of a complete range can be dragged to adjust it, through the same projection, the same availability check and the same cancelable activation as a click;
+- only the bounds are validated; per-night availability stays application-owned.
+
+## U10 — Date with native time companions
+
+A form pairs a date with one or two native times (appointment at `09:30`, from/to on the same day).
+
+Acceptance:
+
+- times stay native `input[type=time]` fields with their own names and submission;
+- `value` stays a `YYYY-MM-DD` date;
+- an inverted from/to surfaces an order error on the modified bound;
+- a missing or disabled time lifts the order constraint;
+- calendar selection and form reset keep the entered times.
+
+## U11 — Host design system controls
+
+The calendar header uses application-owned control classes without styling internal `.dp-*` selectors.
+
+Acceptance:
+
+- author classes survive every render;
+- the library applies no border, background, caret, padding, hover, disabled or focus skin to a role with author classes;
+- controls stretch to equal heights, the year keeps its grid-track width and long month names truncate;
+- labels, keyboard navigation and focus restoration are unchanged;
+- controls without author classes keep the default skin.
+
+## Not a use case for this package
+
+Do not grow the API to cover these without a separate design:
+
+- time slots;
+- duration picking;
+- timezone conversion;
+- appointment recurrence;
+- resource scheduling;
+- drag/drop;
+- event rendering;
+- multi-day scheduler views.
+
+Those belong to `@lekoala/calendar` or application logic.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lekoala/date-picker",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Native-first date picker and inline calendar primitives",
   "type": "module",
   "sideEffects": [
@@ -143,7 +143,7 @@
     "typecheck": "tsc -p jsconfig.json",
     "types": "tsc -p tsconfig.types.json",
     "test": "bun test test/unit",
-    "test:syntax": "node --check src/date.js && node --check src/intl.js && node --check src/calendar-model.js && node --check src/source.js && node --check src/messages.js && node --check src/control-classes.js && node --check src/upgrade-properties.js && node --check src/date-calendar.js && node --check src/date-field.js && node --check src/date-picker.js && node --check src/date-range.js && node --check src/time.js && node --check src/index.js && node --check src/define.js",
+    "test:syntax": "bun scripts/check-syntax.js",
     "test:types": "tsc -p test/types/tsconfig.json",
     "test:browser": "playwright test browser --project chromium",
     "test:browser:accessibility": "playwright test test/browser/picker.spec.js test/browser/focus.spec.js test/browser/calendar.spec.js test/browser/form-state.spec.js test/browser/surfaces.spec.js",

package/src/activation-intents.js

@@ -0,0 +1,9 @@
+/**
+ * Package-internal: the host intent each activation event carries. A host
+ * (`date-picker`) hands its intent to the next activation through
+ * `_hostIntent`; `activateDate()` takes it synchronously and tags the events
+ * it dispatches, so a late response is matched to its own interaction, never
+ * to an earlier or later activation of the same date.
+ * @type {WeakMap<Event, unknown>}
+ */
+export const activationIntents = new WeakMap();

package/src/date-calendar.js

@@ -1,3 +1,4 @@
+import { activationIntents } from "./activation-intents.js";
 import { CalendarModel } from "./calendar-model.js";
 import {
   getDefaultControlClasses,
@@ -165,6 +166,9 @@ export class DateCalendarElement extends HTMLElement {
     this._rendering = false;
     /** @type {DateSource | null} */
     this._source = null;
+    /** Intent the host attached to the next activation of `date`.
+     * @type {{date: string, intent: unknown} | null} */
+    this._hostIntent = null;
     this._sourceStates = new Map();
     this._loadedRanges = new Set();
     this._loadController = null;
@@ -537,7 +541,7 @@ export class DateCalendarElement extends HTMLElement {
     return { start: first[0], end: last[6] };
   }
 
-  /** @public @param {string} date */
+  /** @public @param {string} date @returns {DateState & {disabled: boolean}} */
   getDateState(date) {
     const fromSource = this._sourceStates.get(date) || {};
     const local = this._dateState?.(date, { ...fromSource }) || {};
@@ -681,6 +685,16 @@ export class DateCalendarElement extends HTMLElement {
     }
   }
 
+  /** Leave exactly one roving tab stop, on `date`'s cell when rendered.
+   * @param {string} date */
+  _syncRovingDom(date) {
+    for (const cell of this.querySelectorAll('.dp-day[tabindex="0"]')) {
+      if (cell instanceof HTMLElement && cell.dataset.date !== date) cell.tabIndex = -1;
+    }
+    const cell = this.querySelector(`.dp-day[data-date="${CSS.escape(date)}"]`);
+    if (cell instanceof HTMLElement) cell.tabIndex = 0;
+  }
+
   /** @param {string} previousValue @param {string} nextValue */
   _moveSelectionDom(previousValue, nextValue) {
     if (previousValue) {
@@ -767,21 +781,30 @@ export class DateCalendarElement extends HTMLElement {
    * @param {string} date @returns {Promise<boolean>}
    */
   async activateDate(date) {
+    const hostIntent = this._hostIntent?.date === date ? this._hostIntent.intent : undefined;
+    this._hostIntent = null;
+    /** @param {Event} event */
+    const tagged = (event) => {
+      if (hostIntent !== undefined) activationIntents.set(event, hostIntent);
+      return event;
+    };
     // Guarantee remote state before deciding: a date clicked before the
     // source resolves must not be treated as available, and a cancelled or
     // failed load must not authorize it either.
     const confirmed = await this.ensureDate(date);
     const state = this.getDateState(date);
     if (!confirmed || state.disabled) {
-      this.dispatchEvent(new CustomEvent("dateinvalid", { detail: { date, state }, bubbles: true }));
+      this.dispatchEvent(tagged(new CustomEvent("dateinvalid", { detail: { date, state }, bubbles: true })));
       return false;
     }
     const accepted = this.dispatchEvent(
-      new CustomEvent("dateactivate", {
-        detail: { date, state },
-        bubbles: true,
-        cancelable: true,
-      }),
+      tagged(
+        new CustomEvent("dateactivate", {
+          detail: { date, state },
+          bubbles: true,
+          cancelable: true,
+        }),
+      ),
     );
     if (!accepted) return false;
     if (this.selection === "single") {
@@ -820,6 +843,8 @@ export class DateCalendarElement extends HTMLElement {
     this._model.setFocused(this._clamp(date));
     this._reflect("display", this._model.display);
     if (previousDisplay !== this.display) this._emitDisplayChange();
+    // Engines that do not focus a clicked cell still need the tab stop moved.
+    else this._syncRovingDom(this._model.focused);
     void this.activateDate(date);
   }
 
@@ -832,9 +857,8 @@ export class DateCalendarElement extends HTMLElement {
     }
     if (target instanceof HTMLInputElement && target.matches(".dp-year-input")) {
       const year = Number(target.value);
-      // 9999 is a valid civil year but its December grid overflows into 10000,
-      // so the editable range stops one year short of the unrenderable month.
-      if (!Number.isInteger(year) || year < 1 || year > 9998) {
+      // 9999-12 overflows into 10000, but _setDisplay() clamps it to 9999-11.
+      if (!Number.isInteger(year) || year < 1 || year > 9999) {
         if (this._connected) this.render(false);
         return;
       }
@@ -855,6 +879,8 @@ export class DateCalendarElement extends HTMLElement {
     const date = target.dataset.date || "";
     if (!isDate(date)) return;
     this._model.focused = date;
+    // A pointer focuses the cell directly; keep exactly one tab stop on it.
+    this._syncRovingDom(date);
     this.dispatchEvent(
       new CustomEvent("datefocus", { detail: { date, state: this.getDateState(date) }, bubbles: true }),
     );
@@ -915,8 +941,8 @@ export class DateCalendarElement extends HTMLElement {
     const nextKey = stepMonthKey(display, 1);
     const prevDisabled = Boolean(minMonth && prevKey !== null && prevKey < minMonth);
     const nextDisabled = Boolean(maxMonth && nextKey !== null && nextKey > maxMonth);
-    const minYearAttr = this.min ? ` min="${Number(this.min.slice(0, 4))}"` : "";
-    const maxYearAttr = this.max ? ` max="${Number(this.max.slice(0, 4))}"` : "";
+    const minYearAttr = ` min="${this.min ? Number(this.min.slice(0, 4)) : 1}"`;
+    const maxYearAttr = ` max="${this.max ? Number(this.max.slice(0, 4)) : 9999}"`;
     const showWeeks = this.showWeekNumbers && this.firstDay === 1;
     const weekHeader = showWeeks
       ? `<th scope="col" class="dp-week-heading" abbr="${escapeHtml(this.messages.week)}">#</th>`