@lekoala/date-picker 0.3.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) {
@@ -491,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);
@@ -512,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] */
@@ -572,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.
@@ -633,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 */
@@ -645,7 +741,9 @@ export class DateCalendarElement extends HTMLElement {
     }
     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;
       }
@@ -653,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 */
@@ -668,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.
@@ -712,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;
@@ -750,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("");
@@ -789,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}">
@@ -799,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;
   }
@@ -144,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();
@@ -163,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 = "";

package/src/date-picker.css

@@ -6,6 +6,8 @@
   --dp-hover: color-mix(in srgb, var(--dp-fg) 5%, var(--dp-bg));
   --dp-accent: #2563eb;
   --dp-accent-fg: #fff;
+  --dp-focus: var(--dp-accent);
+  --dp-focus-width: 2px;
   --dp-radius: 0.5rem;
   --dp-day-size: 2.75rem;
   --dp-gap: 0.375rem;
@@ -137,14 +139,6 @@ html[dir="rtl"] .dp-month-select {
   pointer-events: none;
 }
 
-/* Inherited RTL mirrors the header layout via the grid; mirror the nav glyphs
-   so previous/next keep their visual sense. Actions stay chronological: no
-   button swap, no keyboard remapping. */
-[dir="rtl"] .dp-nav svg,
-html[dir="rtl"] .dp-nav svg {
-  transform: scaleX(-1);
-}
-
 .dp-calendar-header :where(button, select, input):disabled,
 .dp-picker-button:disabled {
   cursor: not-allowed;
@@ -155,12 +149,13 @@ html[dir="rtl"] .dp-nav svg {
   background: var(--dp-hover);
 }
 
-/* Shared control focus: accent border + light halo. Day cells keep their
-   dedicated outline ring below; the picker trigger has its own inner ring. */
-.dp-calendar-header :where(button, select, input):focus-visible {
-  outline: none;
-  border-color: var(--dp-accent);
-  box-shadow: 0 0 0 3px color-mix(in srgb, var(--dp-accent) 22%, transparent);
+/* Inner outlines survive forced colors and keep focus inside each control.
+   The picker trigger uses a tighter inset around its icon below. */
+.dp-calendar-header :where(button, select, input):focus-visible,
+date-picker > input:not([type="hidden"]):focus-visible,
+.dp-day:focus-visible {
+  outline: var(--dp-focus-width) solid var(--dp-focus);
+  outline-offset: calc(var(--dp-focus-width) * -1);
 }
 
 .dp-day:hover:not([data-disabled="true"]):not([data-selected="true"]):not([data-range-start="true"]):not(
@@ -205,15 +200,6 @@ html[dir="rtl"] .dp-nav svg {
   font-size: 0.875rem;
 }
 
-/* Inner ring: keyboard focus stays inside the cell instead of reading as a
-   second selected state or bleeding onto a neighbouring range band. It is an
-   `outline` (not an inset box-shadow) because forced colors computes
-   box-shadow to `none`, which would erase the keyboard indicator entirely. */
-.dp-day:focus-visible {
-  outline: 2px solid var(--dp-accent);
-  outline-offset: -2px;
-}
-
 /* On an accent-filled cell the ring inverts so it stays readable. */
 .dp-day:is([data-selected="true"], [data-range-start="true"], [data-range-end="true"]):focus-visible {
   outline-color: var(--dp-accent-fg);
@@ -275,6 +261,28 @@ html[dir="rtl"] .dp-nav svg {
   border-end-end-radius: var(--dp-day-radius);
 }
 
+/* Projected band: the range the next commit would produce. It reads as one
+   step short of the committed band, so a hovered, keyboard or dragged preview
+   is never mistaken for the selection itself. */
+[data-range-preview] .dp-day:is([data-range-start="true"], [data-range-end="true"]) {
+  background: color-mix(in srgb, var(--dp-accent) 58%, var(--dp-bg));
+}
+
+[data-range-preview] .dp-day[data-in-range="true"] {
+  background: color-mix(in srgb, var(--dp-accent) 11%, var(--dp-bg));
+}
+
+/* Endpoint handles are draggable only while the committed range is complete
+   and its two ends sit on different days. */
+[data-range-drag] .dp-day:is([data-range-start="true"], [data-range-end="true"]) {
+  cursor: grab;
+}
+
+[data-range-drag="active"],
+[data-range-drag="active"] .dp-day {
+  cursor: grabbing;
+}
+
 .dp-day-number {
   display: block;
   font-variant-numeric: tabular-nums;
@@ -320,14 +328,6 @@ date-picker {
   max-inline-size: 100%;
 }
 
-/* Visible focus is normalized to --dp-accent so the component holds together
-   without a consumer stylesheet; the field's own look stays consumer-owned. */
-date-picker > input:not([type="hidden"]):focus-visible {
-  border-color: var(--dp-accent);
-  outline: none;
-  box-shadow: 0 0 0 3px color-mix(in srgb, var(--dp-accent) 20%, transparent);
-}
-
 /* Every authored control is a grid item. */
 date-picker > input:not([type="hidden"]) {
   min-inline-size: 0;
@@ -368,7 +368,7 @@ date-picker > input:not([type="hidden"]):not([type="time"]) {
    field already shows its own ring through :focus-visible). Same radius as
    everywhere else: no bespoke shape. */
 .dp-picker-button:focus-visible {
-  outline: 2px solid var(--dp-accent);
+  outline: var(--dp-focus-width) solid var(--dp-focus);
   outline-offset: -5px;
   border-radius: var(--dp-radius);
 }