@lekoala/date-picker 0.2.0 → 0.4.0

package/src/date-picker.js

@@ -9,6 +9,9 @@ import { compareTimes, isTime } from "./time.js";
 
 let uid = 0;
 
+/** Pointer travel, in CSS pixels, that turns a press into an endpoint drag. */
+const DRAG_THRESHOLD = 4;
+
 export class DatePickerElement extends HTMLElement {
   static observedAttributes = ["value", "locale", "min", "max", "open-on-focus", "month-format"];
 
@@ -33,10 +36,22 @@ export class DatePickerElement extends HTMLElement {
     /** @type {"" | "start" | "end"} */
     this._lastFocusEndpoint = "";
     this._rangeCommitId = 0;
-    /** Map of clicked/keyboard-activated grid dates to the generation at click
-     * time (range mode supersession/stale protection). @type {Map<string, number>} */
+    /** Grid activation intents, keyed by date: the generation at interaction
+     * time (range mode supersession/stale protection) plus the bound a drag
+     * drop targets, empty for a normal pick.
+     * @type {Map<string, {id: number, endpoint: "" | "start" | "end"}>} */
     this._pendingIntents = new Map();
-    this._button = null;
+    /** Candidate date currently projected onto the calendar band, if any. */
+    this._previewDate = "";
+    /** Live endpoint drag, or null. @type {{pointerId:number, endpoint:"start"|"end", x:number, y:number, date:string, active:boolean} | null} */
+    this._drag = null;
+    /** A real drag already committed; swallow the click that follows it. */
+    this._suppressGridClick = false;
+    /** Overlaid calendar triggers, one per field (single) or per bound (range). @type {{button: HTMLButtonElement, endpoint: "" | "start" | "end"}[]} */
+    this._buttons = [];
+    /** Control that opened the popover, so single mode can restore focus to it.
+     * @type {HTMLElement | null} */
+    this._returnFocus = null;
     this._panel = null;
     this._calendar = null;
     this._originalDescribedBy = "";
@@ -56,6 +71,8 @@ export class DatePickerElement extends HTMLElement {
     this._renderDay = null;
     /** @type {any} */
     this._isDateDisabled = null;
+    /** Public picker coordinate-space request. @type {"viewport" | "document"} */
+    this._coordinateSpace = "viewport";
   }
 
   _rangeMode() {
@@ -84,7 +101,7 @@ export class DatePickerElement extends HTMLElement {
     this._discoverTimeFields();
     this._field = new DateFieldController(input, { messages: this._messages, locale: this.locale });
     this._field.onAttributesChanged = () => this._syncInputState();
-    this._field.confirm = (date) => this._confirmDate(date);
+    this._field.confirm = (date, options) => this._confirmDate(date, options);
     this._setupFormValue();
     this._build();
     this._syncInputState();
@@ -162,10 +179,10 @@ export class DatePickerElement extends HTMLElement {
     ];
     for (const field of this._fields) {
       field.onAttributesChanged = () => this._syncRangeFields();
-      field.confirm = (date) => this._confirmDate(date);
+      field.confirm = (date, options) => this._confirmDate(date, options);
       field.setupFormValue();
     }
-    this._build(endInput);
+    this._build();
     this._setRangeAria();
     this._syncRangeFields();
     this._bindRange();
@@ -204,10 +221,11 @@ export class DatePickerElement extends HTMLElement {
       this._teardownField(this._field);
     }
     this._field = null;
-    this._button?.remove();
+    for (const { button } of this._buttons) button.remove();
+    this._buttons = [];
+    this._returnFocus = null;
     this._panel?.remove();
     this._formatHint?.remove();
-    this._button = null;
     this._panel = null;
     this._calendar = null;
     this._formatHint = null;
@@ -392,6 +410,15 @@ export class DatePickerElement extends HTMLElement {
     if (this._connected) void this.validate();
   }
 
+  /** @public JS-only coordinate-space policy: "viewport" by default, "document" as an explicit opt-in; a change made while open applies to the next opening only. @returns {"viewport" | "document"} */
+  get coordinateSpace() {
+    return this._coordinateSpace;
+  }
+
+  set coordinateSpace(value) {
+    this._coordinateSpace = value === "document" ? "document" : "viewport";
+  }
+
   _adapter() {
     return this._field?.adapter ?? this._fields?.[0]?.adapter ?? createDateAdapter(this.locale);
   }
@@ -406,16 +433,23 @@ export class DatePickerElement extends HTMLElement {
     // The hidden canonical field owns submission; dynamic name/form/disabled
     // movement lives in the field controller.
     this._field?.syncInputState();
-    if (this._button) this._button.disabled = input.disabled || input.readOnly;
+    const button = this._buttons[0]?.button;
+    if (button) button.disabled = input.disabled || input.readOnly;
     if (this._open && (input.disabled || input.readOnly)) this.hide(false);
   }
 
   _syncRangeFields() {
     if (!this._fields) return;
     for (const field of this._fields) field.syncInputState();
+    // Each trigger follows its own bound: a disabled end never disables the
+    // start trigger.
+    for (const { button, endpoint } of this._buttons) {
+      const index = endpoint === "end" ? 1 : 0;
+      const field = this._fields[index];
+      button.disabled = Boolean(field?.input.disabled || field?.input.readOnly);
+    }
+    this._syncDragAffordance();
     const active = this._range?.activeEndpoint === "end" ? 1 : 0;
-    const disabled = this._fields.every((field) => field.input.disabled || field.input.readOnly);
-    if (this._button) this._button.disabled = disabled;
     if (this._open && (this._fields[active]?.input.disabled || this._fields[active]?.input.readOnly)) {
       this.hide(false);
     }
@@ -436,20 +470,52 @@ export class DatePickerElement extends HTMLElement {
     }
   }
 
-  /** @param {HTMLInputElement} [anchorInput] */
-  _build(anchorInput) {
-    const input = anchorInput || this._input;
-    if (!input) return;
-    const panelId = `${this._id}-panel`;
-    const hintId = `${this._id}-format`;
+  /**
+   * Create one calendar trigger. It is a real button overlaid inside the
+   * field's own box (see the CSS): the field reserves the room, the trigger
+   * stays transparent, and the field's focus ring wraps both.
+   * @param {"" | "start" | "end"} endpoint
+   * @returns {HTMLButtonElement}
+   */
+  _createTrigger(endpoint) {
     const button = document.createElement("button");
     button.type = "button";
     button.className = "dp-picker-button";
     button.setAttribute("aria-haspopup", "dialog");
     button.setAttribute("aria-expanded", "false");
-    button.setAttribute("aria-controls", panelId);
+    button.setAttribute("aria-controls", `${this._id}-panel`);
+    if (endpoint) button.dataset.endpoint = endpoint;
     button.innerHTML =
       '<span aria-hidden="true"><svg viewBox="0 0 16 16" width="1em" height="1em" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"><rect x="1.75" y="3" width="12.5" height="11" rx="1.75"/><path d="M1.75 6.75h12.5"/><path d="M5.25 1.75v2.5M10.75 1.75v2.5"/></svg></span>';
+    return button;
+  }
+
+  /**
+   * Build the popup once and one trigger per field. Each trigger is inserted
+   * immediately after its own field so DOM order follows visual/tab order
+   * (`date -> its trigger -> next control`). The hidden ISO field may sit
+   * between the two; it is not focusable.
+   */
+  _build() {
+    const ranges = this._rangeMode();
+    /** @type {[HTMLInputElement, "" | "start" | "end"][]} */
+    const targets = [];
+    if (ranges) {
+      for (const [index, field] of (this._fields || []).entries()) {
+        targets.push([field.input, index === 1 ? "end" : "start"]);
+      }
+    } else if (this._input) {
+      targets.push([this._input, ""]);
+    }
+    if (!targets.length) return;
+    const panelId = `${this._id}-panel`;
+    const hintId = `${this._id}-format`;
+
+    this._buttons = targets.map(([input, endpoint]) => {
+      const button = this._createTrigger(endpoint);
+      input.insertAdjacentElement("afterend", button);
+      return { button, endpoint };
+    });
 
     const panel = document.createElement("div");
     panel.id = panelId;
@@ -467,23 +533,21 @@ export class DatePickerElement extends HTMLElement {
     hint.id = hintId;
     hint.className = "dp-visually-hidden";
 
-    input.insertAdjacentElement("afterend", button);
-    button.insertAdjacentElement("afterend", panel);
-    panel.insertAdjacentElement("afterend", hint);
+    // Out of flow (popover / visually hidden): placement is irrelevant.
+    this.append(panel, hint);
 
-    this._button = button;
     this._panel = panel;
     this._calendar = calendar;
     this._formatHint = hint;
 
-    if (!this._rangeMode()) {
-      this._originalDescribedBy = input.getAttribute("aria-describedby") || "";
+    if (!ranges && this._input) {
+      this._originalDescribedBy = this._input.getAttribute("aria-describedby") || "";
       const describedBy = [this._originalDescribedBy, hintId].filter(Boolean).join(" ");
-      input.setAttribute("aria-describedby", describedBy);
-      input.setAttribute("role", "combobox");
-      input.setAttribute("aria-haspopup", "dialog");
-      input.setAttribute("aria-expanded", "false");
-      input.setAttribute("aria-controls", panelId);
+      this._input.setAttribute("aria-describedby", describedBy);
+      this._input.setAttribute("role", "combobox");
+      this._input.setAttribute("aria-haspopup", "dialog");
+      this._input.setAttribute("aria-expanded", "false");
+      this._input.setAttribute("aria-controls", panelId);
     }
     this._refreshLocale();
     this._refreshButtonLabel();
@@ -491,7 +555,7 @@ export class DatePickerElement extends HTMLElement {
 
   _bind() {
     const input = this._input;
-    const button = this._button;
+    const button = this._buttons[0]?.button;
     const calendar = this._calendar;
     if (!input || !button || !calendar) return;
     const controller = new AbortController();
@@ -550,10 +614,11 @@ export class DatePickerElement extends HTMLElement {
           this.hide(false);
           return;
         }
-        this.show();
+        this.show({ returnFocus: button });
       },
       { signal },
     );
+    button.addEventListener("keydown", (event) => this._onTriggerKeyDown("", event), { signal });
     calendar.addEventListener(
       "dateactivate",
       (event) => {
@@ -568,11 +633,13 @@ export class DatePickerElement extends HTMLElement {
           this._field?.dirty();
           this._setValue(date, { emit: true, format: true });
           this.hide(false);
-          this._focusInput();
+          this._restoreFocus();
         });
       },
       { signal },
     );
+    // Re-check availability after a source load. validate() commits with
+    // moveDisplay:false, so the visible month stays where the user navigated.
     calendar.addEventListener("dateloadend", () => void this.validate(), { signal });
     this.ownerDocument.addEventListener(
       "pointerdown",
@@ -601,9 +668,8 @@ export class DatePickerElement extends HTMLElement {
   }
 
   _bindRange() {
-    const button = this._button;
     const calendar = this._calendar;
-    if (!this._fields || !button || !calendar) return;
+    if (!this._fields || !this._buttons.length || !calendar) return;
     const controller = new AbortController();
     this._controller = controller;
     const { signal } = controller;
@@ -620,26 +686,35 @@ export class DatePickerElement extends HTMLElement {
       );
       field.input.addEventListener("keydown", (event) => this._onFieldKeyDown(endpoint, event), { signal });
     }
-    button.addEventListener(
+    for (const entry of this._buttons) {
+      const endpoint = entry.endpoint;
+      if (endpoint === "") continue;
+      entry.button.addEventListener("click", (event) => this._onRangeTriggerClick(endpoint, event), {
+        signal,
+      });
+      entry.button.addEventListener("keydown", (event) => this._onTriggerKeyDown(endpoint, event), {
+        signal,
+      });
+    }
+    // Record grid-activation intent synchronously (click or Enter/Space). The
+    // picker only commits a dateactivate whose generation still matches, so a
+    // response that resolves after the active endpoint changed (or after a
+    // newer activation) is dropped without touching either bound.
+    calendar.addEventListener(
       "click",
       (event) => {
-        if (this._open) {
-          if (event.detail === 0) {
-            setTimeout(() => this._calendar?.focusGrid(), 0);
-            return;
-          }
-          this.hide(false);
+        if (this._suppressGridClick) {
+          // The gesture already committed through the drop path; this click is
+          // only the tail of the drag and must not activate a second time.
+          this._suppressGridClick = false;
+          event.preventDefault();
+          event.stopImmediatePropagation();
           return;
         }
-        this.show();
+        this._captureGridIntent(event);
       },
-      { signal },
+      { capture: true, signal },
     );
-    // Record grid-activation intent synchronously (click or Enter/Space). The
-    // picker only commits a dateactivate whose generation still matches, so a
-    // response that resolves after the active endpoint changed (or after a
-    // newer activation) is dropped without touching either bound.
-    calendar.addEventListener("click", (event) => this._captureGridIntent(event), { capture: true, signal });
     calendar.addEventListener("keydown", (event) => this._captureGridIntent(event), {
       capture: true,
       signal,
@@ -652,16 +727,17 @@ export class DatePickerElement extends HTMLElement {
         if (!isDate(date)) return;
         queueMicrotask(() => {
           if (custom.defaultPrevented || !this._connected || !this._range) return;
-          const pending = this._pendingIntents.get(date);
+          const intent = this._pendingIntents.get(date);
           // A response is dropped when the active endpoint changed, the popup
           // closed or a newer activation superseded this one.
-          if (pending === undefined || pending !== this._rangeCommitId) return;
+          if (intent === undefined || intent.id !== this._rangeCommitId) return;
           this._pendingIntents.delete(date);
-          const result = this._range.activate(date, (which) => {
-            const index = which === "end" ? 1 : 0;
-            const field = this._fields?.[index];
-            return field != null && !field.input.disabled && !field.input.readOnly;
-          });
+          const editable = (/** @type {"start" | "end"} */ bound) => this._boundEditable(bound);
+          // Click, keyboard and drop share this one machine; only the entry
+          // point differs, a drag naming the handle it grabbed.
+          const result = intent.endpoint
+            ? this._range.moveEndpoint(date, intent.endpoint, editable)
+            : this._range.activate(date, editable);
           if (result.status === "refused") {
             this._calendar?.dispatchEvent(
               new CustomEvent("dateinvalid", {
@@ -671,7 +747,10 @@ export class DatePickerElement extends HTMLElement {
             );
             return;
           }
-          this._setBound(result.endpoint, date, { emit: true, user: true });
+          this._applyRangeTransition(result);
+          // A drop adjusts an existing range rather than validating it, so the
+          // popup stays open for the next adjustment.
+          if (intent.endpoint) return;
           if (result.close || result.status === "complete") {
             this.hide(false);
             this._focusField(result.endpoint);
@@ -680,6 +759,18 @@ export class DatePickerElement extends HTMLElement {
       },
       { signal },
     );
+    // Preview seams. Hover and keyboard only supply a candidate date; the range
+    // machine decides what that candidate would produce.
+    calendar.addEventListener("datefocus", (event) => this._onGridDateFocus(event), { signal });
+    calendar.addEventListener("pointerover", (event) => this._onGridPointerOver(event), { signal });
+    calendar.addEventListener("pointerleave", () => this._onGridPointerLeave(), { signal });
+    calendar.addEventListener("pointerdown", (event) => this._onGridPointerDown(event), { signal });
+    calendar.addEventListener("pointermove", (event) => this._onGridPointerMove(event), { signal });
+    calendar.addEventListener("pointerup", (event) => this._onGridPointerUp(event), { signal });
+    calendar.addEventListener("pointercancel", (event) => this._onGridPointerCancel(event), { signal });
+    calendar.addEventListener("lostpointercapture", (event) => this._onGridPointerCancel(event), { signal });
+    // Re-check availability after a source load. validate() commits with
+    // moveDisplay:false, so the visible month stays where the user navigated.
     calendar.addEventListener("dateloadend", () => void this.validate(), { signal });
     this.ownerDocument.addEventListener(
       "pointerdown",
@@ -705,9 +796,75 @@ export class DatePickerElement extends HTMLElement {
     this.addEventListener("keydown", (event) => this._onEscape(event), { signal });
   }
 
+  /**
+   * Point the shared calendar at one range bound and invalidate any pending
+   * activation, so a late response can never commit on the wrong bound.
+   * @param {"start" | "end"} endpoint
+   */
+  _activateRangeEndpoint(endpoint) {
+    const calendar = this._calendar;
+    if (!this._range || !calendar) return;
+    this._range.focus(endpoint);
+    this._rangeCommitId++;
+    this._pendingIntents.clear();
+    this._lastFocusEndpoint = endpoint;
+    const target = this._boundCanonical(endpoint) || todayISO();
+    calendar.display = monthKey(target);
+    // Roving-focus target only: `focusedDate` without a DOM focus move emits no
+    // `datefocus`, so pointing the calendar at a bound never previews anything.
+    calendar.focusedDate = target;
+    this._clearPreview();
+  }
+
+  /**
+   * Range has one trigger per bound. A press on the other bound's trigger is a
+   * local switch, not a toggle: it repoints the single open popup instead of
+   * closing it. Only a press on the already-active bound toggles shut.
+   * @param {"start" | "end"} endpoint
+   * @param {MouseEvent} event
+   */
+  _onRangeTriggerClick(endpoint, event) {
+    if (!this._open) {
+      this.show({ endpoint });
+      return;
+    }
+    if (event.detail === 0) {
+      // Keyboard activation of an already-open picker: switch the bound, then
+      // move into the grid. Escape keeps closing it.
+      this._activateRangeEndpoint(endpoint);
+      setTimeout(() => this._calendar?.focusGrid(), 0);
+      return;
+    }
+    if (endpoint !== this._range?.activeEndpoint) {
+      this._activateRangeEndpoint(endpoint);
+      return;
+    }
+    this.hide(false);
+  }
+
+  /**
+   * ArrowDown on a trigger opens the popup and drops into the grid, like the
+   * field itself (Enter/Space go through the click path). Needed because focus
+   * now returns to the trigger that opened the popover.
+   * @param {"" | "start" | "end"} endpoint
+   * @param {KeyboardEvent} event
+   */
+  _onTriggerKeyDown(endpoint, event) {
+    if (event.key !== "ArrowDown") return;
+    event.preventDefault();
+    if (this._open) {
+      if (this._rangeMode() && endpoint) this._activateRangeEndpoint(endpoint);
+      // Chromium drops script-initiated focus changes during keydown dispatch.
+      setTimeout(() => this._calendar?.focusGrid(), 0);
+      return;
+    }
+    if (this._rangeMode()) this.show({ endpoint: endpoint || undefined });
+    else this.show({ returnFocus: this._buttons[0]?.button });
+  }
+
   /** @param {"" | "start" | "end"} endpoint @param {KeyboardEvent} event */
   _onFieldKeyDown(endpoint, event) {
-    if (event.key === "ArrowDown" || (event.altKey && event.key === "ArrowDown")) {
+    if (event.key === "ArrowDown") {
       event.preventDefault();
       if (this._rangeMode() && endpoint) {
         this._lastFocusEndpoint = endpoint;
@@ -758,7 +915,249 @@ export class DatePickerElement extends HTMLElement {
     const cell = event.target.closest(".dp-day[data-date]");
     const date = cell?.getAttribute("data-date") || "";
     if (!isDate(date)) return;
-    this._pendingIntents.set(date, ++this._rangeCommitId);
+    // Each activation supersedes every earlier pending one.
+    this._pendingIntents.clear();
+    this._pendingIntents.set(date, { id: ++this._rangeCommitId, endpoint: "" });
+  }
+
+  /** Whether one bound can receive a user pick right now.
+   * @param {"start" | "end"} bound */
+  _boundEditable(bound) {
+    const field = this._fields?.[bound === "end" ? 1 : 0];
+    return field != null && !field.input.disabled && !field.input.readOnly;
+  }
+
+  /**
+   * Single write path for a calendar-driven range change. Both fields are
+   * synchronized before anything is announced, because one transition can move
+   * both bounds at once (`10` then `5` commits `start 10 -> 5` together with
+   * `end "" -> 10`); writing bound by bound would expose an intermediate
+   * inverted pair. Synthetic `input`/`change` stay on the bounds that moved.
+   * @param {import("./date-range.js").RangeTransition} transition
+   */
+  _applyRangeTransition(transition) {
+    const fields = this._fields;
+    if (!fields || !this._range || transition.status === "refused") return;
+    /** @type {import("./date-field.js").DateFieldController[]} */
+    const moved = [];
+    for (const which of transition.changedEndpoints) {
+      const field = fields[which === "end" ? 1 : 0];
+      const next = which === "end" ? transition.range.end : transition.range.start;
+      if (!field || field.canonical === next) continue;
+      field.setCanonical(next, { format: true });
+      moved.push(field);
+    }
+    this._syncHighlight();
+    this._refreshRangeButtonLabel();
+    this._revalidateRange(transition.endpoint);
+    if (!moved.length) return;
+    this._emitRangeChange();
+    for (const field of moved) {
+      field.input.dispatchEvent(new Event("input", { bubbles: true }));
+      field.input.dispatchEvent(new Event("change", { bubbles: true }));
+    }
+  }
+
+  /**
+   * Project a candidate date onto the calendar band. Purely visual: no
+   * `rangechange`, no field write, no validation and no source request — the
+   * projection reads the month state already loaded, and the real availability
+   * check still runs on commit.
+   * @param {string} date @param {"" | "start" | "end"} [endpoint]
+   */
+  _setPreview(date, endpoint = "") {
+    const calendar = this._calendar;
+    if (!calendar || !this._range || !this._open) return;
+    // A cell already known to be unavailable must not promise a band that the
+    // commit would refuse.
+    const candidate = isDate(date) && !calendar.getDateState(date).disabled ? date : "";
+    const preview = candidate
+      ? this._range.previewRange(candidate, endpoint, (bound) => this._boundEditable(bound))
+      : null;
+    if (!preview) {
+      this._clearPreview();
+      return;
+    }
+    this._previewDate = candidate;
+    calendar.toggleAttribute("data-range-preview", true);
+    calendar.highlightedRange = preview;
+  }
+
+  /** Drop the projection and put the committed range back on the band. */
+  _clearPreview() {
+    if (!this._previewDate) return;
+    this._syncHighlight();
+  }
+
+  /** @param {Event} event */
+  _onGridDateFocus(event) {
+    // The keyboard candidate is the cell that actually took focus, so Enter
+    // commits exactly what the roving focus was previewing.
+    if (this._drag) return;
+    const date = /** @type {CustomEvent} */ (event).detail?.date;
+    if (isDate(date)) this._setPreview(date);
+  }
+
+  /**
+   * Hover candidate. `focusedDate` stays the keyboard target only: pointer
+   * hover never moves it, it just feeds the same projection.
+   * @param {Event} event
+   */
+  _onGridPointerOver(event) {
+    const pointer = /** @type {PointerEvent} */ (event);
+    if (this._drag || pointer.pointerType === "touch") return;
+    this._setPreview(this._cellDate(pointer.target));
+  }
+
+  _onGridPointerLeave() {
+    // Before capture, a gesture that leaves the grid can no longer become a
+    // drag; drop it so it cannot block the next press.
+    if (this._drag?.active === false) this._drag = null;
+    if (this._drag) return;
+    this._clearPreview();
+  }
+
+  /** @param {EventTarget | null} target @returns {string} */
+  _cellDate(target) {
+    const cell = target instanceof Element ? target.closest(".dp-day[data-date]") : null;
+    const date = cell?.getAttribute("data-date") || "";
+    return isDate(date) ? date : "";
+  }
+
+  /** @param {number} x @param {number} y @returns {string} */
+  _dateAtPoint(x, y) {
+    const element = this.ownerDocument.elementFromPoint(x, y);
+    if (!(element instanceof Element) || !this._calendar?.contains(element)) return "";
+    return this._cellDate(element);
+  }
+
+  /**
+   * Arm an endpoint drag. Only a complete, ordered range offers two distinct
+   * handles; a one-day range carries both markers on the same cell, and
+   * guessing which one the user meant would be worse than not dragging.
+   * @param {Event} event
+   */
+  _onGridPointerDown(event) {
+    const pointer = /** @type {PointerEvent} */ (event);
+    this._suppressGridClick = false;
+    // An armed gesture that never started and never released (the pointer left
+    // the grid) must not block the next one.
+    if (this._drag?.active === false) this._drag = null;
+    if (!this._open || !this._range || this._drag) return;
+    if (!pointer.isPrimary || pointer.button !== 0) return;
+    // Mouse and pen first: touch keeps native scrolling (no global
+    // `touch-action: none`) and stays a plain tap.
+    if (pointer.pointerType !== "mouse" && pointer.pointerType !== "pen") return;
+    if (!this._range.complete) return;
+    const cell = pointer.target instanceof Element ? pointer.target.closest(".dp-day[data-date]") : null;
+    if (!(cell instanceof HTMLElement)) return;
+    const isStart = cell.hasAttribute("data-range-start");
+    const isEnd = cell.hasAttribute("data-range-end");
+    if (isStart === isEnd) return;
+    const endpoint = isStart ? "start" : "end";
+    const date = this._cellDate(cell);
+    if (!date || !this._boundEditable(endpoint)) return;
+    this._drag = {
+      pointerId: pointer.pointerId,
+      endpoint,
+      x: pointer.clientX,
+      y: pointer.clientY,
+      date,
+      active: false,
+    };
+  }
+
+  /** @param {Event} event */
+  _onGridPointerMove(event) {
+    const pointer = /** @type {PointerEvent} */ (event);
+    const drag = this._drag;
+    if (!drag || pointer.pointerId !== drag.pointerId) return;
+    if (!drag.active) {
+      // A press and release without travel stays a plain click.
+      const travelled =
+        Math.abs(pointer.clientX - drag.x) > DRAG_THRESHOLD ||
+        Math.abs(pointer.clientY - drag.y) > DRAG_THRESHOLD;
+      if (!travelled) return;
+      drag.active = true;
+      // Capture only once the gesture is a drag. Capturing on the press would
+      // retarget the trailing click to the calendar and swallow a plain pick
+      // on the very cell that carries a handle.
+      try {
+        this._calendar?.setPointerCapture(drag.pointerId);
+      } catch {
+        // No active pointer for this id (synthetic event): move and up still
+        // arrive through normal bubbling.
+      }
+      this._syncDragAffordance();
+    }
+    const date = this._dateAtPoint(pointer.clientX, pointer.clientY);
+    // An unavailable cell is not a drop target: hold the last valid projection
+    // instead of promising a move that would be refused.
+    if (!date || this._calendar?.getDateState(date).disabled) return;
+    drag.date = date;
+    this._setPreview(date, drag.endpoint);
+  }
+
+  /** @param {Event} event */
+  _onGridPointerUp(event) {
+    const pointer = /** @type {PointerEvent} */ (event);
+    const drag = this._drag;
+    if (!drag || pointer.pointerId !== drag.pointerId) return;
+    this._drag = null;
+    this._releaseDragCapture(drag.pointerId);
+    if (!drag.active) {
+      this._syncDragAffordance();
+      return;
+    }
+    this._suppressGridClick = true;
+    const transition = this._range?.projectEndpoint(drag.date, drag.endpoint, (bound) =>
+      this._boundEditable(bound),
+    );
+    if (!transition || transition.status === "refused" || !transition.changedEndpoints.length) {
+      this._syncHighlight();
+      return;
+    }
+    // The drop goes through the same availability check and the same
+    // cancelable `dateactivate` seam as a click, under the same generation
+    // guard: a late response can never move a bound after the popup closed or
+    // after a newer interaction.
+    const target = drag.endpoint === "start" ? transition.range.start : transition.range.end;
+    this._pendingIntents.clear();
+    this._pendingIntents.set(target, { id: ++this._rangeCommitId, endpoint: drag.endpoint });
+    void this._calendar?.activateDate(target);
+  }
+
+  /** @param {Event} event */
+  _onGridPointerCancel(event) {
+    const pointer = /** @type {PointerEvent} */ (event);
+    const drag = this._drag;
+    if (!drag || pointer.pointerId !== drag.pointerId) return;
+    this._drag = null;
+    this._releaseDragCapture(drag.pointerId);
+    // A cancelled gesture commits nothing and restores the committed band.
+    this._syncHighlight();
+  }
+
+  /** @param {number} pointerId */
+  _releaseDragCapture(pointerId) {
+    const calendar = this._calendar;
+    if (calendar?.hasPointerCapture(pointerId)) calendar.releasePointerCapture(pointerId);
+  }
+
+  /** Expose whether the band currently offers draggable handles, and whether
+   * one is being dragged, so the cursor can say so. */
+  _syncDragAffordance() {
+    const calendar = this._calendar;
+    if (!calendar || !this._range) return;
+    if (this._drag?.active) {
+      calendar.setAttribute("data-range-drag", "active");
+      return;
+    }
+    const { start, end } = this._range;
+    const draggable =
+      this._range.complete && start !== end && (this._boundEditable("start") || this._boundEditable("end"));
+    if (draggable) calendar.setAttribute("data-range-drag", "ready");
+    else calendar.removeAttribute("data-range-drag");
   }
 
   /** @param {KeyboardEvent} event */
@@ -818,25 +1217,29 @@ export class DatePickerElement extends HTMLElement {
   }
 
   _refreshButtonLabel() {
-    if (!this._button) return;
+    const single = this._buttons[0]?.button;
+    if (!single) return;
     if (this._rangeMode()) {
       this._refreshRangeButtonLabel();
       return;
     }
     const prefix = this._value ? this._messages.changeDate : this._messages.chooseDate;
     const suffix = this._value ? `, ${formatLongDate(this._value, this.locale)}` : "";
-    this._button.setAttribute("aria-label", `${prefix}${suffix}`);
+    single.setAttribute("aria-label", `${prefix}${suffix}`);
   }
 
+  /** Each bound has its own trigger, so each needs its own accessible name: the
+   * bound label is what tells two otherwise identical triggers apart. */
   _refreshRangeButtonLabel() {
-    if (!this._button || !this._range) return;
+    if (!this._range) return;
     const { start, end } = this._range;
-    const hasRange = Boolean(start && end);
-    const prefix = hasRange ? this._messages.changeDate : this._messages.chooseDate;
-    const suffix = hasRange
-      ? `, ${formatLongDate(start, this.locale)} – ${formatLongDate(end, this.locale)}`
-      : "";
-    this._button.setAttribute("aria-label", `${prefix}${suffix}`);
+    for (const { button, endpoint } of this._buttons) {
+      const bound = endpoint === "end" ? end : start;
+      const prefix = bound ? this._messages.changeDate : this._messages.chooseDate;
+      const suffix = bound ? `, ${formatLongDate(bound, this.locale)}` : "";
+      const boundLabel = endpoint === "end" ? this._messages.rangeEnd : this._messages.rangeStart;
+      button.setAttribute("aria-label", `${prefix}${suffix}, ${boundLabel}`);
+    }
   }
 
   /** @param {string} value */
@@ -847,7 +1250,7 @@ export class DatePickerElement extends HTMLElement {
     this._reflecting = false;
   }
 
-  /** @param {string} value @param {{emit?:boolean,format?:boolean,reflect?:boolean}} [options] */
+  /** @param {string} value @param {{emit?:boolean,format?:boolean,reflect?:boolean,moveDisplay?:boolean}} [options] */
   _setValue(value, options = {}) {
     if (value && !isDate(value)) throw new TypeError(`Invalid date-picker value: ${value}`);
     const previous = this._value;
@@ -856,7 +1259,9 @@ export class DatePickerElement extends HTMLElement {
     this._field?.setCanonical(this._value, { format: options.format !== false });
     if (this._calendar) {
       this._calendar.value = this._value;
-      if (this._value) this._calendar.focusedDate = this._value;
+      // A background revalidation keeps the user's visible month and keyboard
+      // target; only an explicit commit re-homes them onto the value.
+      if (this._value && options.moveDisplay !== false) this._calendar.focusedDate = this._value;
     }
     this._refreshButtonLabel();
     if (previous !== this._value) {
@@ -873,29 +1278,39 @@ export class DatePickerElement extends HTMLElement {
    * Calendar-backed availability gate injected into the field controllers.
    * A cancelled or failed source load confirms nothing: do not fill the
    * submitted ISO field nor treat the date as available.
-   * @param {string} date @returns {Promise<{ok: boolean, message?: string}>}
+   * @param {string} date @param {{moveDisplay?: boolean}} [options]
+   * @returns {Promise<{ok: boolean, message?: string}>}
    */
-  async _confirmDate(date) {
+  async _confirmDate(date, options = {}) {
     const calendar = this._calendar;
     if (!calendar) return { ok: true };
-    const display = monthKey(date);
-    if (calendar.display !== display) calendar.display = display;
+    // Only a user-initiated commit may re-home the visible month. A revalidation
+    // (source reload, attribute change) must leave `display` where the user left
+    // it, per the display/value separation contract.
+    if (options.moveDisplay !== false) {
+      const display = monthKey(date);
+      if (calendar.display !== display) calendar.display = display;
+    }
     const confirmed = await calendar.ensureDate(date);
     const state = calendar.getDateState(date);
     if (!confirmed || state.disabled) return { ok: false, message: this._messages.unavailableDate };
     return { ok: true };
   }
 
-  /** @param {boolean} emit @param {{force?: boolean}} [options] */
+  /** @param {boolean} emit @param {{force?: boolean, moveDisplay?: boolean}} [options] */
   async _commitText(emit, options = {}) {
     const field = this._field;
     if (!field) return false;
     // Blur/change skip untouched text; explicit validation must recheck the
     // current value against the latest constraints regardless of dirtiness.
     if (!options.force && !field.isDirty) return false;
-    const result = await field.commit();
+    const result = await field.commit(options);
     if (result.status === "stale" || result.status === "invalid") return false;
-    this._setValue(result.value || "", { emit, format: result.status === "ok" });
+    this._setValue(result.value || "", {
+      emit,
+      format: result.status === "ok",
+      moveDisplay: options.moveDisplay,
+    });
     return true;
   }
 
@@ -912,7 +1327,9 @@ export class DatePickerElement extends HTMLElement {
       this._orderTags.delete(index);
       return false;
     }
-    this._setBound(which, result.value || "", { emit: true, user: true, format: result.status === "ok" });
+    // Typed commits keep native input/change only; synthetic events are
+    // reserved for calendar-driven changes (no native input event occurred).
+    this._setBound(which, result.value || "", { emit: false, user: true, format: result.status === "ok" });
     return true;
   }
 
@@ -974,20 +1391,23 @@ export class DatePickerElement extends HTMLElement {
     this.dispatchEvent(new CustomEvent("rangechange", { detail: { ...this._range.range }, bubbles: true }));
   }
 
-  /** Forward only a displayable range to the calendar band. An inverted or
-   * start-less business range shows no misleading band. */
+  /** Displayable projection of the business range. An inverted or start-less
+   * pair shows no misleading band. @returns {{start:string, end:string}} */
+  _displayRange() {
+    const { start, end } = this._range?.range ?? { start: "", end: "" };
+    if (!start) return { start: "", end: "" };
+    if (end && compareDates(end, start) < 0) return { start, end: "" };
+    return { start, end };
+  }
+
+  /** Put the committed range back on the calendar band, dropping any
+   * projection currently shown over it. */
   _syncHighlight() {
     if (!this._calendar || !this._range) return;
-    const { start, end } = this._range;
-    if (!start) {
-      this._calendar.highlightedRange = { start: "", end: "" };
-      return;
-    }
-    if (end && compareDates(end, start) < 0) {
-      this._calendar.highlightedRange = { start, end: "" };
-    } else {
-      this._calendar.highlightedRange = { start, end };
-    }
+    this._previewDate = "";
+    this._calendar.removeAttribute("data-range-preview");
+    this._calendar.highlightedRange = this._displayRange();
+    this._syncDragAffordance();
   }
 
   /**
@@ -1099,13 +1519,19 @@ export class DatePickerElement extends HTMLElement {
     }, 0);
   }
 
-  _focusInput() {
-    // focus() must not run synchronously from a keydown handler (Chromium drops
-    // focus changes there) and must not re-open the popover under the default
-    // open-on-focus. Deferring keeps _suppressFocusOpen active for the call.
+  /**
+   * Restore focus to the control that opened the popover (single mode). focus()
+   * must not run synchronously from a keydown handler (Chromium drops focus
+   * changes there) and must not re-open the popover under the default
+   * open-on-focus. Deferring keeps _suppressFocusOpen active for the call.
+   */
+  _restoreFocus() {
+    const target = this._returnFocus;
+    this._returnFocus = null;
+    if (!(target instanceof HTMLElement) || !target.isConnected || target.matches(":disabled")) return;
     this._suppressFocusOpen = true;
     setTimeout(() => {
-      this._input?.focus();
+      target.focus();
       this._suppressFocusOpen = false;
     }, 0);
   }
@@ -1135,7 +1561,7 @@ export class DatePickerElement extends HTMLElement {
       // field controller, hidden ISO, range model and events stay coherent.
       // Empty text flows through commit()'s "clear" outcome, not an early exit.
       for (const [index, field] of fields.entries()) {
-        const result = await field.commit();
+        const result = await field.commit({ moveDisplay: false });
         if (result.status === "ok" || result.status === "clear") {
           const which = index === 1 ? "end" : "start";
           this._setBound(which, result.value || "", { format: result.status === "ok" });
@@ -1150,7 +1576,7 @@ export class DatePickerElement extends HTMLElement {
     if (!input.value.trim()) {
       input.setCustomValidity("");
     } else {
-      await this._commitText(false, { force: true });
+      await this._commitText(false, { force: true, moveDisplay: false });
     }
     // Same start-then-end order as the range path, so a from/to inversion
     // ends reported on "end". A programmatic time change resyncs here too.
@@ -1160,34 +1586,39 @@ export class DatePickerElement extends HTMLElement {
     return input.checkValidity() && timesValid;
   }
 
-  /** @public @param {{moveFocus?:boolean}} [options] */
+  /** @public @param {{moveFocus?:boolean, endpoint?:"start"|"end", returnFocus?:HTMLElement}} [options] */
   show(options = {}) {
     const panel = this._panel;
     const calendar = this._calendar;
-    const button = this._button;
-    if (!panel || !calendar || !button || this._open) return;
+    if (!panel || !calendar || !this._buttons.length || this._open) return;
     if (this._rangeMode()) {
-      const endpoint = this._resolveRangeEndpoint();
+      const endpoint = options.endpoint || this._resolveRangeEndpoint();
       if (!endpoint) return;
-      this._range?.focus(endpoint);
-      this._rangeCommitId++;
-      this._pendingIntents.clear();
-      const target = this._boundCanonical(endpoint) || todayISO();
-      calendar.display = monthKey(target);
-      calendar.focusedDate = target;
-      this._lastFocusEndpoint = endpoint;
+      this._activateRangeEndpoint(endpoint);
     } else {
       const input = this._input;
       if (!input || input.disabled || input.readOnly) return;
       const target = this._value || this._adapter().parse(input.value) || todayISO();
       calendar.display = monthKey(target);
       calendar.focusedDate = target;
+      // Popover convention: closing returns focus to the control that opened.
+      this._returnFocus = options.returnFocus instanceof HTMLElement ? options.returnFocus : input;
     }
     panel.showPopover();
     this._open = true;
     this._setExpanded(true);
+    // Freeze the explicitly configured coordinate space once per opening: a
+    // change made while open takes effect on the next opening, never the
+    // current one.
+    const coordinateSpace = this.coordinateSpace;
+    panel.style.position = coordinateSpace === "document" ? "absolute" : "fixed";
     const position = () =>
-      reposition(this, panel, { placement: "bottom-start", distance: 4, shiftPadding: 8 });
+      reposition(this, panel, {
+        placement: "bottom-start",
+        distance: 4,
+        shiftPadding: 8,
+        coordinateSpace,
+      });
     position();
     this._stopTracking = autoUpdate(this, panel, position);
     if (options.moveFocus !== false) queueMicrotask(() => calendar.focusGrid());
@@ -1198,7 +1629,7 @@ export class DatePickerElement extends HTMLElement {
   _setExpanded(expanded) {
     const value = expanded ? "true" : "false";
     this._input?.setAttribute("aria-expanded", value);
-    this._button?.setAttribute("aria-expanded", value);
+    for (const { button } of this._buttons) button.setAttribute("aria-expanded", value);
     for (const field of this._fields || []) field.input.setAttribute("aria-expanded", value);
   }
 
@@ -1216,12 +1647,20 @@ export class DatePickerElement extends HTMLElement {
     this._setExpanded(false);
     this._rangeCommitId++;
     this._pendingIntents.clear();
+    this._suppressGridClick = false;
+    if (this._drag) {
+      this._releaseDragCapture(this._drag.pointerId);
+      this._drag = null;
+    }
+    this._syncHighlight();
     if (restoreFocus) {
       if (this._rangeMode()) {
+        // Range owns a workflow: after a first pick the active bound moved, so
+        // focus follows the bound rather than the original trigger.
         const endpoint = this._restoreFocusEndpoint();
         if (endpoint) this._focusField(endpoint);
       } else {
-        this._focusInput();
+        this._restoreFocus();
       }
     }
     this.dispatchEvent(new Event("close", { bubbles: true }));