@lekoala/date-picker 0.1.1 → 0.3.0

package/src/date-picker.js

@@ -5,11 +5,12 @@ import { DateFieldController } from "./date-field.js";
 import { DateRangeController, normalizeRange } from "./date-range.js";
 import { createDateAdapter, formatLongDate, resolveLocale } from "./intl.js";
 import { getDefaultMessages } from "./messages.js";
+import { compareTimes, isTime } from "./time.js";
 
 let uid = 0;
 
 export class DatePickerElement extends HTMLElement {
-  static observedAttributes = ["value", "locale", "min", "max", "open-on-focus"];
+  static observedAttributes = ["value", "locale", "min", "max", "open-on-focus", "month-format"];
 
   constructor() {
     super();
@@ -25,13 +26,21 @@ export class DatePickerElement extends HTMLElement {
     /** @type {DateRangeController | null} */
     this._range = null;
     this._orderTags = new Set();
+    /** Native time companions, [start, end]. @type {[HTMLInputElement | null, HTMLInputElement | null]} */
+    this._timeFields = [null, null];
+    /** Time inputs currently holding our order error. @type {Set<HTMLInputElement>} */
+    this._timeOrderOwned = new Set();
     /** @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>} */
     this._pendingIntents = new Map();
-    this._button = null;
+    /** 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 = "";
@@ -51,6 +60,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() {
@@ -67,13 +78,16 @@ export class DatePickerElement extends HTMLElement {
   }
 
   _connectSingle() {
-    const input = this.querySelector(":scope > input:not([type=hidden])");
+    const input = this.querySelector(
+      ":scope > input:not([type=hidden]):not([type=time]):not([data-time-start]):not([data-time-end])",
+    );
     if (!(input instanceof HTMLInputElement)) {
       console.warn("<date-picker> expects a direct child text input");
       return;
     }
     this._connected = true;
     this._input = input;
+    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);
@@ -102,7 +116,37 @@ export class DatePickerElement extends HTMLElement {
     }
   }
 
+  /**
+   * Find optional native time companions. They stay fully native (no hidden
+   * input, no field controller); the picker only coordinates from/to order.
+   * A bad composition never breaks the date picker: warn and leave times alone.
+   */
+  _discoverTimeFields() {
+    this._timeFields = [null, null];
+    /** @type {["data-time-start", "data-time-end"]} */
+    const markers = ["data-time-start", "data-time-end"];
+    for (const [index, marker] of markers.entries()) {
+      const matches = this.querySelectorAll(`:scope > input[${marker}]`);
+      if (matches.length > 1) {
+        console.warn(`<date-picker> expects at most one direct child input[${marker}]; ignoring extras`);
+      }
+      const candidate = matches[0];
+      if (candidate == null) continue;
+      if (!(candidate instanceof HTMLInputElement) || candidate.type !== "time") {
+        console.warn(`<date-picker> input[${marker}] must be an <input type="time">; ignoring it`);
+        continue;
+      }
+      this._timeFields[index] = candidate;
+    }
+    if (this.querySelector(":scope > input[type=time]:not([data-time-start]):not([data-time-end])")) {
+      console.warn("<date-picker> time inputs need [data-time-start] or [data-time-end]; ignoring it");
+    }
+  }
+
   _connectRange() {
+    if (this.querySelector(":scope > input[data-time-start], :scope > input[data-time-end]")) {
+      console.warn("<date-picker range> time companions are not supported yet; leaving them native");
+    }
     const startInput = this.querySelector(":scope > input[data-range-start]");
     const endInput = this.querySelector(":scope > input[data-range-end]");
     if (!(startInput instanceof HTMLInputElement) || !(endInput instanceof HTMLInputElement)) {
@@ -127,7 +171,7 @@ export class DatePickerElement extends HTMLElement {
       field.confirm = (date) => this._confirmDate(date);
       field.setupFormValue();
     }
-    this._build(endInput);
+    this._build();
     this._setRangeAria();
     this._syncRangeFields();
     this._bindRange();
@@ -156,6 +200,8 @@ export class DatePickerElement extends HTMLElement {
     this.hide(false);
     this._controller?.abort();
     this._controller = null;
+    this._clearTimeOrderValidity();
+    this._timeFields = [null, null];
     if (this._rangeMode()) {
       for (const field of this._fields || []) this._teardownField(field);
       this._fields = null;
@@ -164,10 +210,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;
@@ -248,6 +295,16 @@ export class DatePickerElement extends HTMLElement {
     else this.removeAttribute("locale");
   }
 
+  /** @public Visible month-name style forwarded to the popup calendar (`long` | `short`); anything else falls back to `long`. */
+  get monthFormat() {
+    return this.getAttribute("month-format") === "short" ? "short" : "long";
+  }
+
+  set monthFormat(value) {
+    if (value === "short") this.setAttribute("month-format", "short");
+    else this.removeAttribute("month-format");
+  }
+
   /** @public */
   get min() {
     const value = this.getAttribute("min") || "";
@@ -342,6 +399,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);
   }
@@ -356,16 +422,22 @@ 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);
+    }
     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);
     }
@@ -386,20 +458,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;
@@ -417,23 +521,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();
@@ -441,7 +543,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();
@@ -479,6 +581,12 @@ export class DatePickerElement extends HTMLElement {
       },
       { signal },
     );
+    for (const [index, timeInput] of this._timeFields.entries()) {
+      if (!timeInput) continue;
+      const endpoint = index === 1 ? "end" : "start";
+      timeInput.addEventListener("input", () => this._revalidateTimeOrder(endpoint), { signal });
+      timeInput.addEventListener("change", () => this._revalidateTimeOrder(endpoint), { signal });
+    }
     button.addEventListener(
       "click",
       (event) => {
@@ -494,10 +602,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) => {
@@ -512,7 +621,7 @@ export class DatePickerElement extends HTMLElement {
           this._field?.dirty();
           this._setValue(date, { emit: true, format: true });
           this.hide(false);
-          this._focusInput();
+          this._restoreFocus();
         });
       },
       { signal },
@@ -545,9 +654,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;
@@ -564,21 +672,16 @@ export class DatePickerElement extends HTMLElement {
       );
       field.input.addEventListener("keydown", (event) => this._onFieldKeyDown(endpoint, event), { signal });
     }
-    button.addEventListener(
-      "click",
-      (event) => {
-        if (this._open) {
-          if (event.detail === 0) {
-            setTimeout(() => this._calendar?.focusGrid(), 0);
-            return;
-          }
-          this.hide(false);
-          return;
-        }
-        this.show();
-      },
-      { signal },
-    );
+    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
@@ -649,9 +752,72 @@ 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);
+    calendar.focusedDate = target;
+  }
+
+  /**
+   * 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;
@@ -702,6 +868,8 @@ export class DatePickerElement extends HTMLElement {
     const cell = event.target.closest(".dp-day[data-date]");
     const date = cell?.getAttribute("data-date") || "";
     if (!isDate(date)) return;
+    // Each activation supersedes every earlier pending one.
+    this._pendingIntents.clear();
     this._pendingIntents.set(date, ++this._rangeCommitId);
   }
 
@@ -721,6 +889,7 @@ export class DatePickerElement extends HTMLElement {
     calendar.locale = this.locale;
     calendar.min = this.min;
     calendar.max = this.max;
+    calendar.monthFormat = this.monthFormat;
     calendar.messages = this._messages;
     calendar.source = this._source;
     calendar.dateState = this._dateState;
@@ -761,25 +930,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 */
@@ -855,7 +1028,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;
   }
 
@@ -959,6 +1134,47 @@ export class DatePickerElement extends HTMLElement {
     }
   }
 
+  /**
+   * Single-mode from/to order on the shared date: `start <= end`.
+   * The order error is attributed to the bound that was just modified; the
+   * other bound only loses a stale order error, never its native validity.
+   * Missing, empty or disabled times fall back to no order constraint: times
+   * are never implicitly required. Equality stays valid (duration rules are
+   * application-owned).
+   * @param {"start" | "end"} which
+   */
+  _revalidateTimeOrder(which) {
+    const [startInput, endInput] = this._timeFields;
+    /** @type {["start", "end"]} */
+    const bounds = ["start", "end"];
+    const inputs = [startInput, endInput];
+    const startValue = startInput && !startInput.disabled ? startInput.value.trim() : "";
+    const endValue = endInput && !endInput.disabled ? endInput.value.trim() : "";
+    const inverted =
+      Boolean(startInput && endInput && startValue && endValue) &&
+      isTime(startValue) &&
+      isTime(endValue) &&
+      compareTimes(endValue, startValue) < 0;
+    for (const [index, bound] of bounds.entries()) {
+      const input = inputs[index];
+      if (!input) continue;
+      const message = bound === "end" ? this._messages.rangeOrderEnd : this._messages.rangeOrderStart;
+      const shouldHaveOrder = inverted && bound === which;
+      if (shouldHaveOrder) {
+        input.setCustomValidity(message);
+        this._timeOrderOwned.add(input);
+      } else if (this._timeOrderOwned.has(input)) {
+        input.setCustomValidity("");
+        this._timeOrderOwned.delete(input);
+      }
+    }
+  }
+
+  _clearTimeOrderValidity() {
+    for (const input of this._timeOrderOwned) input.setCustomValidity("");
+    this._timeOrderOwned.clear();
+  }
+
   _restoreDefault() {
     const field = this._field;
     if (!field) return;
@@ -1001,13 +1217,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);
   }
@@ -1051,40 +1273,50 @@ export class DatePickerElement extends HTMLElement {
     if (!input) return true;
     if (!input.value.trim()) {
       input.setCustomValidity("");
-      return input.checkValidity();
+    } else {
+      await this._commitText(false, { force: true });
     }
-    await this._commitText(false, { force: true });
-    return input.checkValidity();
+    // 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.
+    this._revalidateTimeOrder("start");
+    this._revalidateTimeOrder("end");
+    const timesValid = this._timeFields.every((timeInput) => timeInput?.checkValidity() ?? true);
+    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());
@@ -1095,7 +1327,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);
   }
 
@@ -1115,10 +1347,12 @@ export class DatePickerElement extends HTMLElement {
     this._pendingIntents.clear();
     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 }));

package/src/index.js

@@ -8,6 +8,7 @@ export {
   formatLongDate,
   formatMonthYear,
   monthNames,
+  monthYearOrder,
   resolveLocale,
   weekdayNames,
 } from "./intl.js";