@lekoala/date-picker 0.2.0 → 0.3.0

package/src/date-picker.js

@@ -36,7 +36,11 @@ export class DatePickerElement extends HTMLElement {
     /** 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 = "";
@@ -56,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() {
@@ -165,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();
@@ -204,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;
@@ -392,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);
   }
@@ -406,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);
     }
@@ -436,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;
@@ -467,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();
@@ -491,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();
@@ -550,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) => {
@@ -568,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 },
@@ -601,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;
@@ -620,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
@@ -705,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;
@@ -758,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);
   }
 
@@ -818,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 */
@@ -912,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;
   }
 
@@ -1099,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);
   }
@@ -1160,34 +1284,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 +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);
   }
 
@@ -1218,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 }));