@lekoala/date-picker 0.2.0 → 0.4.0

package/src/date-calendar.js

@@ -2,12 +2,13 @@ import { CalendarModel } from "./calendar-model.js";
 import {
   addDays,
   clampDate,
+  clampDisplayMonth,
   compareDates,
+  endOfMonth,
   getMonthWeeks,
   isDate,
   isoWeekNumber,
   monthKey,
-  shiftMonth,
   todayISO,
 } from "./date.js";
 import { normalizeRange, rangePosition } from "./date-range.js";
@@ -46,20 +47,43 @@ function yearOf(month) {
   return Number(month.slice(0, 4));
 }
 
+/**
+ * Step a `YYYY-MM` key by ±1, or `null` when the step leaves the canonical
+ * 0001-01..9999-12 window. Pure arithmetic, so an out-of-range intermediate
+ * date is never constructed and the calendar edges cannot throw.
+ * @param {string} month
+ * @param {number} amount
+ * @returns {string | null}
+ */
+function stepMonthKey(month, amount) {
+  const [year, index] = month.split("-").map(Number);
+  const absolute = year * 12 + (index - 1) + amount;
+  const stepYear = Math.floor(absolute / 12);
+  const stepMonth = (((absolute % 12) + 12) % 12) + 1;
+  if (stepYear < 1 || stepYear > 9999) return null;
+  return `${String(stepYear).padStart(4, "0")}-${String(stepMonth).padStart(2, "0")}`;
+}
+
+/**
+ * Band attributes for one day position. Markup and in-place band updates read
+ * the same map, so the two paths cannot disagree about a cell's state.
+ * @param {"" | "start" | "in" | "end" | "single"} position
+ * @returns {Record<string, boolean>}
+ */
+function rangeAttributeMap(position) {
+  return {
+    "data-range-start": position === "start" || position === "single",
+    "data-range-end": position === "end" || position === "single",
+    "data-in-range": position === "in",
+  };
+}
+
 /** @param {"" | "start" | "in" | "end" | "single"} position */
 function rangeAttributes(position) {
-  switch (position) {
-    case "single":
-      return ' data-range-start="true" data-range-end="true"';
-    case "start":
-      return ' data-range-start="true"';
-    case "end":
-      return ' data-range-end="true"';
-    case "in":
-      return ' data-in-range="true"';
-    default:
-      return "";
-  }
+  return Object.entries(rangeAttributeMap(position))
+    .filter(([, on]) => on)
+    .map(([name]) => ` ${name}="true"`)
+    .join("");
 }
 
 /** @param {"" | "start" | "in" | "end" | "single"} position */
@@ -125,6 +149,12 @@ export class DateCalendarElement extends HTMLElement {
     this._isDateDisabled = null;
     /** @type {DateRange} */
     this._highlightedRange = { start: "", end: "" };
+    // Bounds and preview flag the cells were last painted with. The preview
+    // flag changes the accessible names (a proposal drops the committed
+    // range-start/range-end suffix), so a repaint is due when either changes.
+    /** @type {DateRange} */
+    this._paintedRange = { start: "", end: "" };
+    this._paintedPreview = false;
     this._messages = getDefaultMessages();
     this._onClick = this._onClick.bind(this);
     this._onChange = this._onChange.bind(this);
@@ -262,9 +292,17 @@ export class DateCalendarElement extends HTMLElement {
 
   set highlightedRange(value) {
     const next = normalizeRange(value);
-    if (next.start === this._highlightedRange.start && next.end === this._highlightedRange.end) return;
+    const preview = this.hasAttribute("data-range-preview");
+    // Repaint when the preview mode changed even if the bounds are identical:
+    // entering/leaving a preview rewrites every cell's accessible name.
+    if (
+      next.start === this._paintedRange.start &&
+      next.end === this._paintedRange.end &&
+      preview === this._paintedPreview
+    )
+      return;
     this._highlightedRange = next;
-    if (this._connected) this.render();
+    if (this._connected) this._updateRangeDom();
   }
 
   /** @public */
@@ -343,7 +381,7 @@ export class DateCalendarElement extends HTMLElement {
     const attrDisplay = this.getAttribute("display") || "";
     if (attrDisplay) {
       try {
-        this._model.setDisplay(attrDisplay);
+        this._model.setDisplay(clampDisplayMonth(attrDisplay, firstDay));
       } catch {
         // Invalid author markup falls back to the current model display.
       }
@@ -368,11 +406,21 @@ export class DateCalendarElement extends HTMLElement {
 
   /** @param {string} value */
   _clamp(value) {
-    return clampDate(value, this.min, this.max);
+    const bounded = clampDate(value, this.min, this.max);
+    const month = monthKey(bounded);
+    const safeMonth = clampDisplayMonth(month, this.firstDay);
+    if (safeMonth === month) return bounded;
+    // The renderable window excludes this month (a calendar edge): keep the
+    // day-of-month where the target month has it, else fall back to its last
+    // day, so the focused date always exists in the rendered grid.
+    const day = Number(bounded.slice(8, 10)) || 1;
+    const candidate = addDays(`${safeMonth}-01`, day - 1);
+    const last = endOfMonth(safeMonth);
+    return compareDates(candidate, last) > 0 ? last : candidate;
   }
 
   _weeks(display = this.display) {
-    const weeks = getMonthWeeks(display, { firstDay: this.firstDay });
+    const weeks = getMonthWeeks(clampDisplayMonth(display, this.firstDay), { firstDay: this.firstDay });
     if (!this.fixedWeeks || weeks.length >= 6) return weeks;
     let cursor = weeks[weeks.length - 1]?.[6] || "";
     while (weeks.length < 6 && cursor) {
@@ -386,7 +434,7 @@ export class DateCalendarElement extends HTMLElement {
 
   /** @param {HTMLElement} element @returns {string} */
   _focusTargetKey(element) {
-    if (element.matches(".dp-month-select, .dp-year-select, .dp-year-input") && element.id) {
+    if (element.matches(".dp-month-select, .dp-year-input") && element.id) {
       return `#${CSS.escape(element.id)}`;
     }
     if (element.matches(".dp-nav[data-calendar-action]")) {
@@ -416,7 +464,8 @@ export class DateCalendarElement extends HTMLElement {
     const outsideBounds =
       (this.min && compareDates(date, this.min) < 0) || (this.max && compareDates(date, this.max) > 0);
     const explicitlyEnabled = state.enabled === true;
-    // min/max > state.disabled > enabled:true lifts only isDateDisabled().
+    // min/max > resolved state.disabled > isDateDisabled(), unless resolved
+    // state.enabled === true lifts only isDateDisabled().
     const disabledByRule = explicitlyEnabled ? false : Boolean(this._isDateDisabled?.(date));
     const disabled = Boolean(outsideBounds) || Boolean(state.disabled) || disabledByRule;
     return { ...state, disabled };
@@ -490,7 +539,7 @@ export class DateCalendarElement extends HTMLElement {
   /** @param {string} display @param {{emit?:boolean}} [options] */
   _setDisplay(display, options = {}) {
     const previous = this._model.display;
-    this._model.setDisplay(display);
+    this._model.setDisplay(clampDisplayMonth(display, this.firstDay));
     this._model.focused = this._clamp(this._model.focused);
     this._model.display = monthKey(this._model.focused);
     this._reflect("display", this._model.display);
@@ -511,12 +560,12 @@ export class DateCalendarElement extends HTMLElement {
 
   /** @public */
   previousMonth() {
-    return this._setDisplay(shiftMonth(this.display, -1));
+    return this._setDisplay(stepMonthKey(this.display, -1) ?? this.display);
   }
 
   /** @public */
   nextMonth() {
-    return this._setDisplay(shiftMonth(this.display, 1));
+    return this._setDisplay(stepMonthKey(this.display, 1) ?? this.display);
   }
 
   /** @public @param {string} date @param {{moveFocus?:boolean}} [options] */
@@ -571,14 +620,62 @@ export class DateCalendarElement extends HTMLElement {
     return false;
   }
 
+  /**
+   * Accessible name of one day cell. The band contribution is dropped while a
+   * preview is projected onto `highlightedRange`: a proposal must not be
+   * announced as a committed range start/end.
+   * @param {string} date @param {DateState} state
+   * @param {"" | "start" | "in" | "end" | "single"} position
+   */
+  _dayLabel(date, state, position) {
+    const rangeLabel = this.hasAttribute("data-range-preview") ? "" : rangeLabelKey(position);
+    const description = typeof state.description === "string" ? state.description : "";
+    return [
+      formatLongDate(date, this.locale),
+      description,
+      rangeLabel ? this._messages[rangeLabel] : "",
+      state.disabled ? this._messages.unavailable : "",
+    ]
+      .filter(Boolean)
+      .join(". ");
+  }
+
+  /**
+   * Repaint the range band over the cells already rendered. The band is
+   * presentation on top of the same grid, so it must never rebuild it: a full
+   * render would drop `renderDay()` nodes and fight the roving focus on every
+   * hover of a live range preview.
+   */
+  _updateRangeDom() {
+    this._paintedRange = { ...this._highlightedRange };
+    this._paintedPreview = this.hasAttribute("data-range-preview");
+    for (const cell of this.querySelectorAll(".dp-day[data-date]")) {
+      if (!(cell instanceof HTMLTableCellElement)) continue;
+      const date = cell.dataset.date || "";
+      const position = rangePosition(date, this._highlightedRange);
+      for (const [name, on] of Object.entries(rangeAttributeMap(position))) {
+        if (on) cell.setAttribute(name, "true");
+        else cell.removeAttribute(name);
+      }
+      cell.setAttribute("aria-label", this._dayLabel(date, this.getDateState(date), position));
+    }
+  }
+
   /** @public */
   focusGrid() {
     const target = this.querySelector(`.dp-day[data-date="${CSS.escape(this.focusedDate)}"]`);
     if (target instanceof HTMLElement) target.focus();
   }
 
-  /** @param {string} date @returns {Promise<boolean>} */
-  async _activate(date) {
+  /**
+   * Run one explicit activation: availability check, then the cancelable
+   * `dateactivate` seam, then selection. Click, keyboard and any other input
+   * device share this single path, so an application that cancels
+   * `dateactivate` cannot be bypassed by a new interaction.
+   * @public
+   * @param {string} date @returns {Promise<boolean>}
+   */
+  async activateDate(date) {
     // Guarantee remote state before deciding: a date clicked before the
     // source resolves must not be treated as available, and a cancelled or
     // failed load must not authorize it either.
@@ -632,7 +729,7 @@ export class DateCalendarElement extends HTMLElement {
     this._model.setFocused(this._clamp(date));
     this._reflect("display", this._model.display);
     if (previousDisplay !== this.display) this._emitDisplayChange();
-    void this._activate(date);
+    void this.activateDate(date);
   }
 
   /** @param {Event} event */
@@ -642,13 +739,11 @@ export class DateCalendarElement extends HTMLElement {
       this._setDisplay(`${this.display.slice(0, 4)}-${target.value}`);
       return;
     }
-    if (target instanceof HTMLSelectElement && target.matches(".dp-year-select")) {
-      this._setDisplay(`${target.value}-${this.display.slice(5, 7)}`);
-      return;
-    }
     if (target instanceof HTMLInputElement && target.matches(".dp-year-input")) {
       const year = Number(target.value);
-      if (!Number.isInteger(year) || year < 1 || year > 9999) {
+      // 9999 is a valid civil year but its December grid overflows into 10000,
+      // so the editable range stops one year short of the unrenderable month.
+      if (!Number.isInteger(year) || year < 1 || year > 9998) {
         if (this._connected) this.render(false);
         return;
       }
@@ -656,12 +751,22 @@ export class DateCalendarElement extends HTMLElement {
     }
   }
 
-  /** @param {FocusEvent} event */
+  /**
+   * Real DOM focus is the single source of truth for `datefocus`: the model is
+   * synced here and the event is announced from here, so the temporary focus
+   * arithmetic in `_onKeyDown` cannot emit phantom events, and setting
+   * `focusedDate` without moving focus stays silent.
+   * @param {FocusEvent} event
+   */
   _onFocusIn(event) {
     const target = event.target;
     if (!(target instanceof HTMLTableCellElement) || !target.matches(".dp-day[data-date]")) return;
     const date = target.dataset.date || "";
-    if (isDate(date)) this._model.focused = date;
+    if (!isDate(date)) return;
+    this._model.focused = date;
+    this.dispatchEvent(
+      new CustomEvent("datefocus", { detail: { date, state: this.getDateState(date) }, bubbles: true }),
+    );
   }
 
   /** @param {KeyboardEvent} event */
@@ -671,7 +776,7 @@ export class DateCalendarElement extends HTMLElement {
     const date = target.dataset.date || this.focusedDate;
     if (event.key === "Enter" || event.key === " ") {
       event.preventDefault();
-      void this._activate(date);
+      void this.activateDate(date);
       return;
     }
     // Movement primitives live in CalendarModel; the DOM only syncs render/focus.
@@ -715,8 +820,10 @@ export class DateCalendarElement extends HTMLElement {
     const gridId = `${this._id}-grid`;
     const minMonth = this.min ? monthKey(this.min) : "";
     const maxMonth = this.max ? monthKey(this.max) : "";
-    const prevDisabled = Boolean(minMonth && shiftMonth(display, -1) < minMonth);
-    const nextDisabled = Boolean(maxMonth && shiftMonth(display, 1) > maxMonth);
+    const prevKey = stepMonthKey(display, -1);
+    const nextKey = stepMonthKey(display, 1);
+    const prevDisabled = Boolean(minMonth && prevKey !== null && prevKey < minMonth);
+    const nextDisabled = Boolean(maxMonth && nextKey !== null && nextKey > maxMonth);
     const minYearAttr = this.min ? ` min="${Number(this.min.slice(0, 4))}"` : "";
     const maxYearAttr = this.max ? ` max="${Number(this.max.slice(0, 4))}"` : "";
     const showWeeks = this.showWeekNumbers && this.firstDay === 1;
@@ -753,16 +860,7 @@ export class DateCalendarElement extends HTMLElement {
             const focused = this.focusedDate === date;
             const isToday = date === today;
             const position = rangePosition(date, this._highlightedRange);
-            const rangeLabel = rangeLabelKey(position);
-            const description = typeof state.description === "string" ? state.description : "";
-            const label = [
-              formatLongDate(date, locale),
-              description,
-              rangeLabel ? this._messages[rangeLabel] : "",
-              state.disabled ? this._messages.unavailable : "",
-            ]
-              .filter(Boolean)
-              .join(". ");
+            const label = this._dayLabel(date, state, position);
             return `<td class="dp-day" data-date="${date}"${outside ? ' data-outside-month="true"' : ""}${isToday ? ' data-today="true" aria-current="date"' : ""}${selected ? ' data-selected="true" aria-selected="true"' : ""}${rangeAttributes(position)}${state.disabled ? ' data-disabled="true" aria-disabled="true"' : ""} tabindex="${focused ? "0" : "-1"}" aria-label="${escapeHtml(label)}"><span class="dp-day-number" aria-hidden="true">${Number(date.slice(8, 10))}</span><span class="dp-day-extra" aria-hidden="true"></span></td>`;
           })
           .join("");
@@ -792,8 +890,8 @@ export class DateCalendarElement extends HTMLElement {
         <div class="dp-calendar-header">
           ${yearFirst ? yearControl : monthControl}
           ${yearFirst ? monthControl : yearControl}
-          <button type="button" class="dp-nav dp-prev" data-calendar-action="previous" aria-label="${escapeHtml(this._messages.previousMonth)}"${prevDisabled ? " disabled" : ""}><svg aria-hidden="true" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="m10 4-4 4 4 4"/></svg></button>
-          <button type="button" class="dp-nav dp-next" data-calendar-action="next" aria-label="${escapeHtml(this._messages.nextMonth)}"${nextDisabled ? " disabled" : ""}><svg aria-hidden="true" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="m6 4 4 4-4 4"/></svg></button>
+          <button type="button" class="dp-nav dp-prev" data-calendar-action="previous" aria-label="${escapeHtml(this._messages.previousMonth)}"${prevDisabled ? " disabled" : ""}><svg aria-hidden="true" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="m4 10 4-4 4 4"/></svg></button>
+          <button type="button" class="dp-nav dp-next" data-calendar-action="next" aria-label="${escapeHtml(this._messages.nextMonth)}"${nextDisabled ? " disabled" : ""}><svg aria-hidden="true" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="m4 6 4 4 4-4"/></svg></button>
         </div>
         <h2 id="${headingId}" class="dp-calendar-heading dp-visually-hidden" aria-live="polite">${escapeHtml(formatMonthYear(`${display}-15`, locale))}</h2>
         <table id="${gridId}" class="dp-grid" role="grid" aria-labelledby="${headingId}">
@@ -802,6 +900,8 @@ export class DateCalendarElement extends HTMLElement {
         </table>
       </div>`;
     this._rendering = false;
+    this._paintedRange = { ...this._highlightedRange };
+    this._paintedPreview = this.hasAttribute("data-range-preview");
 
     if (focusKey) {
       queueMicrotask(() => {

package/src/date-field.js

@@ -33,8 +33,9 @@ export class DateFieldController {
     this.onAttributesChanged = null;
     /**
      * Async availability gate for a parsed date. Returning `{ ok: false }`
-     * marks the target unavailable. Swappable at runtime.
-     * @type {((date: string) => Promise<{ok: boolean, message?: string}>) | null}
+     * marks the target unavailable. Swappable at runtime. The commit options
+     * are forwarded so the gate can honor `moveDisplay`.
+     * @type {((date: string, options?: {moveDisplay?: boolean}) => Promise<{ok: boolean, message?: string}>) | null}
      */
     this.confirm = null;
   }
@@ -117,18 +118,26 @@ export class DateFieldController {
   }
 
   /** Live text input: the raw text no longer matches the canonical value, so
-   * the hidden ISO must not submit it. */
+   * the hidden ISO must not submit it. A text that formats back to the current
+   * canonical value (e.g. re-applied by a calendar pick) keeps the ISO value
+   * valid; invalidating in-flight commits first still drops stale async work. */
   handleInput() {
     const input = this.input;
-    this._dirty = true;
+    const text = input.value.trim();
+    const canonical = this.canonical ? this.adapter.format(this.canonical) : "";
     this.dirty();
+    if (text === canonical) {
+      this._dirty = false;
+      if (this.hidden) this.hidden.value = this.canonical;
+      input.setCustomValidity("");
+      return;
+    }
+    this._dirty = true;
     if (this.hidden) this.hidden.value = "";
-    const text = input.value.trim();
     if (!text) {
       input.setCustomValidity("");
       return;
     }
-    const canonical = this.canonical ? this.adapter.format(this.canonical) : "";
     input.setCustomValidity(text === canonical ? "" : this.messages.invalidDate);
   }
 
@@ -136,9 +145,12 @@ export class DateFieldController {
    * Commit the visible text. Returns the parsed canonical date on success, the
    * empty string on a clear, or a falsy marker for invalid/stale commits. The
    * caller applies the canonical value so reflection and events stay central.
+   * `options` is forwarded to the `confirm` gate so a revalidation can ask it
+   * not to move the calendar display (source reloads must not re-home it).
+   * @param {{moveDisplay?: boolean}} [options]
    * @returns {Promise<{status: "ok" | "clear" | "invalid" | "stale", value?: string}>}
    */
-  async commit() {
+  async commit(options = {}) {
     const input = this.input;
     const commitId = ++this._commitId;
     const text = input.value.trim();
@@ -155,7 +167,7 @@ export class DateFieldController {
       return { status: "invalid" };
     }
     if (this.confirm) {
-      const result = await this.confirm(parsed);
+      const result = await this.confirm(parsed, options);
       if (commitId !== this._commitId) return { status: "stale" };
       if (!result?.ok) {
         if (this.hidden) this.hidden.value = "";