@lekoala/date-picker 0.2.0 → 0.4.0

package/docs/ACCESSIBILITY.md

@@ -38,13 +38,15 @@ Weekday headings use visible short labels plus a full `abbr` value.
 | Shift+PageDown | same/clamped day in next year |
 | Enter / Space | activate focused date |
 
-Moving focus never changes selection.
+Moving focus never changes selection. Each cell that actually receives focus dispatches `datefocus`, so an application can follow keyboard navigation without reading internal DOM classes; hover never dispatches it, and assigning `focusedDate` without moving focus stays silent.
 
-## Month/year controls
+A range preview projected onto the band is visual only: it never contributes a range start/end to a day's accessible name, so a proposal is never announced as a committed selection.
+
+Endpoint dragging is a pointer enhancement. Every adjustment it offers is also reachable from the keyboard: activating before or after a complete range moves the corresponding bound.
 
-The prototype deliberately uses native selects. They are easy to discover, keyboard-operable, and do not require nested custom popovers.
+## Month/year controls
 
-The year select is a moving window around the displayed year when no hard min/max exists. Navigating past the current window causes a normal re-render centered on the new year.
+The month control is a native select and the year control is a native number input. They are easy to discover, keyboard-operable, and do not require nested custom popovers.
 
 ## Date picker input
 
@@ -99,19 +101,29 @@ The same resolved date state used by the grid is used for manual-entry validatio
 
 Forced colors should not rely on the normal selected-day fill tokens.
 
-When `forced-colors: active`, the selected day switches to a border-based treatment:
+When `forced-colors: active`, the selected day and range endpoints switch to a border-based treatment:
 
 - `Canvas` background;
 - `CanvasText` foreground;
-- `Highlight` outer border;
-- an inner `CanvasText` ring.
+- `2px Highlight` outer border;
+- in-range days keep a `1px Highlight` underline (the range fill is lost and the browser does not know the semantics).
 
-Today keeps the base 1px outline — `border-color: var(--dp-accent)` force-adjusts to `CanvasText` here, so it stays a thin `CanvasText` border. Selected and today therefore remain distinct through border color, width, the inner ring and weight (selected is `700`), not through a shared system key.
-
-This avoids relying on white text over a `Highlight` fill, which can become ambiguous when the active high-contrast theme resolves `Highlight` near-white or when small white digits rasterize poorly. The disabled state is `GrayText` at full opacity.
+Today keeps a thin `1px Highlight` border while selected carries the wider border, so the two stay distinct through border width. The disabled state relies on the native dimming, verified by capture. The month select hands its caret back to the browser (`appearance: auto`), since the author-drawn gradient is a non-system color.
 
 Guard: re-run the `color-contrast` review and the forced-colors screenshot bundle whenever `--dp-*` styling or day-cell rendering changes.
 
+## Visible focus
+
+Fields (including native time companions), calendar header controls and day cells use an inner solid outline. `--dp-focus` defaults to `var(--dp-accent)` and `--dp-focus-width` defaults to `2px`; the inward offset follows the width. This replaces the previous accent border and soft halo on fields and header controls. The resting input appearance stays consumer-owned.
+
+Focus is only ever drawn on a real box. The calendar trigger is a real button painted inside the date field's own box, so the field's focus ring naturally wraps the affordance too — no host-level ring, no pseudo-element. When the trigger itself is focused it shows a small inner ring, like the native `input[type=time]` indicator, instead of pretending the whole field is focused.
+
+Day cells use an **inner** ring too: keyboard focus stays inside the 44px cell instead of reading as a second selected state, and it never bleeds onto a neighbouring range band. The ring is an `outline` with `outline-offset: -2px`, not an inset `box-shadow`, because forced colors computes `box-shadow` to `none` — an inset shadow would erase the keyboard indicator (including on disabled days, which must stay discoverable). `outline-color` is force-adjusted to a system color there, so the ring survives high contrast. On a cell already filled with the accent (selected, range endpoints) the ring inverts to `--dp-accent-fg` so it stays readable.
+
+Each native time companion is an independent control and keeps its own ring; they are not joined, so rings never merge and no neighbour swallows another's focus. In `[range]`, each bound owns its trigger and its own ring, and focus follows the active bound rather than the original trigger.
+
+Closing returns focus to the control that opened the popover (field or trigger) in single mode.
+
 ## Recommended manual test matrix
 
 Beyond what the automated suite covers, the following pairings should be exercised before a broad adoption of 0.1. Results are recorded in [AT-CHECKLIST.md](AT-CHECKLIST.md); the human rows there are still open:

package/docs/API.md

@@ -31,7 +31,7 @@ Presentation-only range band. It never changes `value`, `selection` or `focusedD
 calendar.isDateDisabled = (date) => boolean;
 calendar.dateState = (date, sourceState) => ({
   disabled,
-  enabled, // true = explicit exception to generic disabled rules
+  enabled, // true = lifts isDateDisabled() only; never min/max or resolved disabled
   description,
   ...applicationMetadata
 });
@@ -62,6 +62,7 @@ calendar.nextMonth();
 calendar.focusDate("2026-09-10");
 calendar.focusGrid();
 calendar.getDateState("2026-09-10");
+await calendar.activateDate("2026-09-10");
 await calendar.ensureDate("2026-09-10");
 await calendar.refreshSource();
 calendar.render();
@@ -87,6 +88,28 @@ calendar.addEventListener("dateactivate", (event) => {
 });
 ```
 
+`activateDate(date)` runs that same path on demand: availability check, then
+the cancelable event, then selection. Click, keyboard and the range endpoint
+drag all go through it, so an application that cancels `dateactivate` cannot be
+bypassed by a different input device.
+
+#### `datefocus`
+
+Fired when a date cell actually receives focus, with `{ date, state }`. Arrow,
+Home, End, PageUp and PageDown all emit one through the cell that took focus.
+
+```js
+calendar.addEventListener("datefocus", (event) => {
+  console.log(event.detail.date);
+});
+```
+
+It observes navigation and nothing else: a disabled day still reports it (grid
+navigation stays discoverable), hover never does, and assigning `focusedDate`
+without moving DOM focus stays silent. The three verbs are distinct —
+`datefocus` observes, `dateactivate` requests an activation, `datechange`
+observes a selection.
+
 #### `datechange`
 
 Fired when `selection="single"` changes `value`.
@@ -152,6 +175,23 @@ The direct child text input is required. On enhancement its original `name` move
 - `isDateDisabled`;
 - `messages`.
 
+### Popup positioning
+
+- `coordinateSpace` — JS-only, `"viewport"` by default.
+
+```text
+"viewport"
+  panel uses position: fixed
+  general/default integration
+
+"document"
+  panel uses position: absolute
+  explicit optimization when the application knows the picker
+  reference moves with root-page scrolling
+```
+
+`document` follows the `@lekoala/floating` consumer contract: the picker panel is a top-layer popover, so its absolute positioning resolves against the initial containing block; the application remains responsible for knowing that the `<date-picker>` reference itself moves with the root document. Changing `coordinateSpace` while open configures the next opening, never the current one. See the `@lekoala/floating` documentation for the coordinate-space doctrine.
+
 ### Read-only properties
 
 ```js
@@ -231,6 +271,8 @@ Optional native time companions (one or both). They are direct children, fixed a
 
 Two editable fields share one calendar popup. The mode is fixed at connect time (`range` attribute + both marked direct child inputs); switching single/range at runtime is not supported in V1.
 
+Each field gets its own calendar trigger, inserted right after it (`start`, then its trigger, `end`, then its trigger), so DOM order matches visual/tab order. Both triggers point at the same popup; activating the other bound's trigger while it is open switches the active bound and keeps it open.
+
 ### Strict API
 
 - `range` — atomic get/set of `{ start, end }` (canonical `YYYY-MM-DD`). The setter validates through `normalizeRange` (ISO-only, ordered; inverted throws) and applies both bounds, the visible fields and both hidden fields **before** one `rangechange` event — no intermediate new-start/old-end state is observable.
@@ -253,8 +295,12 @@ The business range may be temporarily incomplete or inverted; `calendar.highligh
 ### Interaction
 
 - When an ordered range is complete, picking before its start updates only the start; picking after its end updates only the end, regardless of the opening field. The popup closes after this update. An uneditable target bound refuses the activation.
-- Otherwise, opening through a field targets that bound (`activeEndpoint`). Picking from `start` commits it, moves the endpoint to `end` without closing, and a second pick commits and closes. Opening from `end` refuses a date before `start` (`dateinvalid`, nothing changes).
-- The shared trigger opens the last active bound, else `start`; it never auto-switches to a `readonly`/`disabled` bound.
+- Otherwise, opening through a field targets that bound (`activeEndpoint`). Picking from `start` commits it, moves the endpoint to `end` without closing, and a second pick commits and closes.
+- **Calendar interaction never produces an inverted range.** While a range is being created, a second pick before the anchor is sorted rather than refused: `10` then `15` gives `10 -> 15`, `10` then `5` gives `5 -> 10`, and `10` then `10` a one-day range. That transition moves **both** bounds at once and is applied in a single write — one `rangechange`, with synthetic `input`/`change` on each bound that moved, and no intermediate inverted pair ever observable. Typed text keeps the opposite contract and may be temporarily inverted (see [DECISIONS D6](DECISIONS.md)).
+- Changing one bound of an already complete pair keeps that bound's identity: moving `end` before `start` is refused (`dateinvalid`, nothing changes) instead of rewriting the other field.
+- **Preview.** While a range is being created, hovering a day or moving the keyboard focus projects the range the next pick would commit onto `calendar.highlightedRange`, and the pick commits exactly what was projected. The projection is visual only: no `rangechange`, no field write, no validation and no source request. It reads the month already loaded, so a day known to be unavailable promises nothing; the real availability check still runs on commit. Pointer hover never moves `focusedDate`, which stays the keyboard target. Leaving the grid, Escape and closing the popup restore the committed band.
+- **Endpoint drag.** On a complete, ordered range whose two ends sit on different days, each endpoint can be dragged with a mouse or pen (pointer events plus capture, armed only once the pointer travels). A handle never crosses the other one — the candidate is clamped to it, equality allowed — an unavailable cell is not a drop target, and `pointercancel` restores the committed band. The drop runs the same projection and the same `ensureDate` + cancelable `dateactivate` path as a click, emits one `rangechange`, and keeps the popup open: a drag adjusts a range, it does not validate it. A press without travel stays a plain click. Touch keeps native scrolling and stays a plain tap.
+- Each bound owns its trigger (`input[data-range-start]` then its trigger, `input[data-range-end]` then its trigger); the two triggers share **one** popup, calendar, source and state. Pressing the other bound's trigger while the popup is open switches the active bound and keeps it open instead of toggling it shut. A trigger never opens a `readonly`/`disabled` bound.
 - Typing stays independent per field. Moving `start` past `end` keeps both values and flags the *modified* bound with `rangeOrderStart`; fixing either side revalidates both. Parse/source errors are never cleared by cross-bound revalidation.
 - A stale availability response resolving after the active endpoint changed (or after a newer selection) never commits; a field focus that switches the endpoint invalidates in-flight activations.
 
@@ -278,6 +324,29 @@ rangePosition("2026-09-12", range); // "start" | "in" | "end" | "single" | ""
 
 `normalizeRange` validates an ordered displayable range and never reorders: an inversion or an `end` without a `start` throws. `rangePosition` classifies one day within a displayable range (see [`highlightedRange`](#highlightedrange)).
 
+## `DateRangeController`
+
+The pure two-bound state machine behind `date-picker[range]`. It owns the
+selection rules and knows nothing about DOM, popups or async availability.
+
+```js
+const model = new DateRangeController();
+model.focus("start");
+model.activate("2026-09-10"); // { status: "pending", endpoint: "start", … }
+model.previewRange("2026-09-05"); // { start: "2026-09-05", end: "2026-09-10" }
+model.activate("2026-09-05"); // changedEndpoints: ["start", "end"]
+```
+
+- `project(date, editable?)` / `projectEndpoint(date, endpoint, editable?)` describe a transition without applying it;
+- `activate(date, editable?)` / `moveEndpoint(date, endpoint, editable?)` apply one;
+- `previewRange(date, endpoint?, editable?)` returns the displayable band a candidate would produce, or `null` when there is nothing to promise.
+
+A transition is `{ status, endpoint, changedEndpoints, range, activeEndpoint, close? }`.
+`range` is the whole resulting pair, because one interaction can move both
+bounds; `changedEndpoints` names the ones that actually move. Every rule exists
+once, as a projection, and the previews read the same projections the commit
+applies.
+
 ## `createDateAdapter(locale)`
 
 Locale-aware editable numeric adapter:

package/docs/ARCHITECTURE.md

@@ -93,7 +93,10 @@ This prevents rich decorations from breaking grid semantics or keyboard behavior
 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.
+`enabled: true` is the explicit exception seam: when the resolved state carries
+`enabled === true`, it lifts `isDateDisabled()` only. It never bypasses
+`min`/`max` or the resolved `state.disabled` (source state merged with
+`dateState()` output, so `dateState()` can already replace a source `disabled`).
 
 Both click activation and typed picker validation use this resolved state.
 
@@ -144,6 +147,17 @@ The picker creates a `<date-calendar selection="none">` in a native manual popov
 
 Native Popover owns the top layer. `@lekoala/floating` owns coordinates and geometry updates.
 
+### Coordinate space
+
+`picker.coordinateSpace` (`"viewport"` default, `"document"` explicit opt-in, JS-only, no attribute) is frozen once per opening in `show()`; `panel.style.position` is coupled:
+
+```text
+viewport (default) → fixed
+document           → absolute
+```
+
+No layout inference is performed. Coordinate-space choice is consumer policy; `@lekoala/floating` owns only coordinate math and update tracking.
+
 The picker does not implement:
 
 - custom portals;
@@ -157,7 +171,7 @@ The popup remains in authored DOM, preserving inherited locale/theme/density con
 
 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.
+`<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. The shell owns one calendar trigger per bound (each inserted after its own field, both pointing at the same popup) and switches the active endpoint without closing it. `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:
 

package/docs/AT-CHECKLIST.md

@@ -44,7 +44,7 @@ Release decision (0.1.0): the human reader/OS pairings below are **deferred past
 
 - [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).
+- [ ] [manual] Forced-colors mode keeps selected/today/disabled distinguishable with the simplified border-based treatment (re-check after the neutral-palette + rhythm pass; spot-check with the forced-colors screenshot bundle).
 
 ## Automated pass
 

package/docs/DECISIONS.md

@@ -1,13 +1,15 @@
 # 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.
+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`, `datechange`, `dateinvalid`, `displaychange`, `dateloadstart`, `dateloadend`, `dateloaderror`.
-- `date-picker`: `valuechange`, `open`, `close`.
+- `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:*`).
 
@@ -35,6 +37,8 @@ Context: DOM-backed styling hooks become API the moment they are documented —
 
 - 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.
@@ -44,4 +48,15 @@ Context: DOM-backed styling hooks become API the moment they are documented —
 - 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.
+- 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.

package/docs/MIGRATION-FLATPICKR.md

@@ -1,6 +1,6 @@
 # Flatpickr / Formidable migration map
 
-This prototype was scoped against the existing `FlatpickrInput` wrapper rather than against Flatpickr's full feature list.
+This project was scoped against the existing `FlatpickrInput` wrapper rather than against Flatpickr's full feature list.
 
 ## Directly covered
 
@@ -78,7 +78,7 @@ calendar.isDateDisabled = (date) => isWeekend(date);
 // 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.
+The prototype promotes this legacy behavior into a documented generic field: `enabled: true` reopens a date disabled by `isDateDisabled()`, but never bypasses hard `min`/`max` bounds or a resolved `state.disabled`.
 
 ## Not migrated into this component
 

package/docs/TESTING.md

@@ -68,6 +68,6 @@ Keep explicit tests for these regressions:
 
 ## CI
 
-The included workflow uses Bun 1.4.2 and runs static checks/unit tests before Playwright.
+The included workflow uses Bun 1.4.3 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.

package/docs/USE_CASES.md

@@ -111,6 +111,9 @@ Acceptance:
 - 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lekoala/date-picker",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Native-first date picker and inline calendar primitives",
   "type": "module",
   "sideEffects": [
@@ -20,7 +20,7 @@
   },
   "homepage": "https://github.com/lekoala/date-picker",
   "bugs": "https://github.com/lekoala/date-picker/issues",
-  "packageManager": "bun@1.4.2",
+  "packageManager": "bun@1.4.3",
   "keywords": [
     "date-picker",
     "calendar",
@@ -162,13 +162,13 @@
     "prepublishOnly": "bun run verify"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.11",
-    "@lekoala/calendar": "0.1.0",
-    "@playwright/test": "1.62.1",
-    "temporal-polyfill": "^1.0.4",
+    "@biomejs/biome": "2.5.15",
+    "@lekoala/calendar": "0.2.0",
+    "@playwright/test": "1.64.0",
+    "temporal-polyfill": "^1.0.5",
     "typescript": "7.0.2"
   },
   "dependencies": {
-    "@lekoala/floating": "^0.1.1"
+    "@lekoala/floating": "^0.2.0"
   }
 }