stimeo-ui 0.16.0 → 0.18.0

data/dist/controllers/calendar_controller.js

@@ -1,24 +1,48 @@
 import { Controller } from '@hotwired/stimulus';
 
-// src/controllers/calendar_controller.ts
+var FOCUS_EVENTS = /* @__PURE__ */ new Set(["blur", "focus", "focusin", "focusout"]);
+var POINTER_EVENTS = /* @__PURE__ */ new Set(["mouseenter", "mouseleave", "pointerenter", "pointerleave"]);
+function stateReasonFor(event) {
+  if (!event) return "api";
+  if (FOCUS_EVENTS.has(event.type)) return "focus";
+  if (POINTER_EVENTS.has(event.type)) return "pointer";
+  return "user";
+}
+
+function actionSource(source) {
+  if (source instanceof HTMLElement) {
+    return { event: null, host: source, origin: source, reason: "api" };
+  }
+  const event = source ?? null;
+  return {
+    event,
+    host: event?.currentTarget instanceof Element ? event.currentTarget : null,
+    origin: event?.target instanceof Element ? event.target : null,
+    reason: stateReasonFor(event)
+  };
+}
 
-// src/utils/logical_scroll.ts
 function isRtl(element) {
   return window.getComputedStyle(element).direction === "rtl";
 }
 
-// src/utils/arrow_step.ts
 function logicalArrowKey(key, element) {
   if (key !== "ArrowRight" && key !== "ArrowLeft") return key;
   if (!isRtl(element)) return key;
   return key === "ArrowRight" ? "ArrowLeft" : "ArrowRight";
 }
+function gridDirectionElement(grid, root) {
+  const table = grid.closest("table");
+  return table !== null && root.contains(table) ? table : grid;
+}
 function isReservedArrowChord(event, allow = []) {
   if (!event.key.startsWith("Arrow")) return false;
   return event.altKey && !allow.includes("alt") || event.ctrlKey && !allow.includes("ctrl") || event.metaKey && !allow.includes("meta") || event.shiftKey && !allow.includes("shift");
 }
+function hasModifierChord(event) {
+  return event.altKey || event.ctrlKey || event.metaKey || event.shiftKey;
+}
 
-// src/utils/intl_format.ts
 var formatters = /* @__PURE__ */ new WeakMap();
 function intlFormatter(factory, locale, options, fallbackLocale) {
   const cache = cacheFor(factory);
@@ -47,7 +71,6 @@ function construct(factory, locale, options, fallbackLocale) {
   }
 }
 
-// src/utils/dates.ts
 function toISODateString(date) {
   const year = date.getFullYear();
   const month = String(date.getMonth() + 1).padStart(2, "0");
@@ -80,12 +103,35 @@ function parseISOMonthString(monthStr) {
 function toISOMonthString(date) {
   return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}`;
 }
+function monthGridDays(year, month, weekStart) {
+  const first = new Date(year, month - 1, 1);
+  const offset = (first.getDay() - weekStart + 7) % 7;
+  const current = new Date(first);
+  current.setDate(first.getDate() - offset);
+  const days = [];
+  for (let i = 0; i < 42; i++) {
+    days.push(new Date(current));
+    current.setDate(current.getDate() + 1);
+  }
+  return days;
+}
+function dateInMonthClamped(date, year, month) {
+  const target = new Date(year, month - 1, 1);
+  const lastDay = new Date(target.getFullYear(), target.getMonth() + 1, 0).getDate();
+  target.setDate(Math.min(date.getDate(), lastDay));
+  return target;
+}
+function shiftMonthClamped(date, delta) {
+  return dateInMonthClamped(date, date.getFullYear(), date.getMonth() + 1 + delta);
+}
+function shiftYearClamped(date, delta) {
+  return dateInMonthClamped(date, date.getFullYear() + delta, date.getMonth() + 1);
+}
 var MONTH_LABEL_OPTIONS = { month: "long", year: "numeric" };
 function monthLabelFormatter(locale) {
   return intlFormatter(Intl.DateTimeFormat, locale, MONTH_LABEL_OPTIONS, "en");
 }
 
-// src/utils/field_mirror.ts
 function writeField(field, value) {
   if (field.value === value) return false;
   field.value = value;
@@ -95,32 +141,29 @@ function commitField(target) {
   target.dispatchEvent(new Event("change", { bubbles: true }));
 }
 
-// src/utils/locale.ts
 function resolveLocale(element, declared = "") {
   return declared || element.closest("[lang]")?.getAttribute("lang") || void 0;
 }
 
-// src/utils/microtask_coalescer.ts
 var MicrotaskCoalescer = class {
   #run;
   #queued = false;
   #active = false;
   #generation = 0;
-  /** @param run - the single reconciliation pass, invoked at most once per batch. */
   constructor(run) {
     this.#run = run;
   }
-  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
   activate() {
     this.#active = true;
   }
-  /** Closes the window and drops any pending pass; call from `disconnect()`. */
   cancel() {
     this.#active = false;
     this.#queued = false;
     this.#generation += 1;
   }
-  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */
+  get pending() {
+    return this.#queued;
+  }
   schedule() {
     if (!this.#active || this.#queued) return;
     this.#queued = true;
@@ -133,15 +176,95 @@ var MicrotaskCoalescer = class {
   }
 };
 
-// src/utils/target_selector.ts
+var ListenerSet = class {
+  #abort = new AbortController();
+  add(target, type, handler, options) {
+    target.addEventListener(type, handler, { ...options, signal: this.#abort.signal });
+  }
+  dispose() {
+    this.#abort.abort();
+    this.#abort = new AbortController();
+  }
+};
+
+var MorphRenderWatcher = class {
+  #listeners = new ListenerSet();
+  #pass;
+  #element = null;
+  #onMorph = () => this.#pass.schedule();
+  constructor(run) {
+    this.#pass = new MicrotaskCoalescer(run);
+  }
+  observe(element) {
+    if (this.#element === element) return;
+    this.disconnect();
+    this.#element = element;
+    this.#pass.activate();
+    this.#listeners.add(element, "turbo:morph-element", this.#onMorph);
+  }
+  schedule() {
+    this.#pass.schedule();
+  }
+  get pending() {
+    return this.#pass.pending;
+  }
+  disconnect() {
+    this.#listeners.dispose();
+    this.#pass.cancel();
+    this.#element = null;
+  }
+};
+
+function matchesNumberBounds(value, bounds) {
+  if (!Number.isFinite(value)) {
+    const direction = value === Infinity ? "positive" : value === -Infinity ? "negative" : null;
+    if (direction === null) return false;
+    if (bounds.allowInfinity !== "both" && bounds.allowInfinity !== direction) return false;
+  }
+  if (bounds.min !== void 0 && value < bounds.min) return false;
+  if (bounds.max !== void 0 && value > bounds.max) return false;
+  if (bounds.exclusiveMin !== void 0 && value <= bounds.exclusiveMin) return false;
+  if (bounds.integer && !Number.isInteger(value)) return false;
+  if (bounds.allowedValues !== void 0 && !bounds.allowedValues.includes(value)) return false;
+  return true;
+}
+
+function readNumber(raw, fallback, bounds) {
+  return matchesNumberBounds(raw, bounds) ? raw : fallback;
+}
+
+var NumberValueReader = class {
+  #lastRejected = /* @__PURE__ */ new Map();
+  read(owner, name, raw, fallback, bounds) {
+    const resolved = readNumber(raw, fallback, bounds);
+    if (matchesNumberBounds(raw, bounds)) {
+      this.#lastRejected.delete(name);
+      return resolved;
+    }
+    const attribute = `data-${owner.identifier}-${name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}-value`;
+    const literal = owner.element.getAttribute(attribute);
+    if (literal === null) {
+      this.#lastRejected.delete(name);
+      return resolved;
+    }
+    if (this.#lastRejected.get(name) !== literal) {
+      this.#lastRejected.set(name, literal);
+      console.warn(
+        `Stimeo UI: "${owner.identifier}" has an invalid number Value "${name}" declaration ${JSON.stringify(literal)}; using ${fallback}.`
+      );
+    }
+    return resolved;
+  }
+};
+
 function targetSelector(identifier, name) {
   return `[data-${identifier}-target~="${name}"]`;
 }
 
-// src/controllers/calendar_controller.ts
 var OWNED_DISABLED = "owns-disabled";
-var CalendarController = class extends Controller {
-  /** The marker above, in the namespace this controller is registered under. */
+var CalendarController = class _CalendarController extends Controller {
+  #numbers = new NumberValueReader();
+  #fieldWrites = /* @__PURE__ */ new WeakMap();
   get #ownedDisabled() {
     return `data-${this.identifier}-${OWNED_DISABLED}`;
   }
@@ -152,82 +275,31 @@ var CalendarController = class extends Controller {
     min: { type: String, default: "" },
     max: { type: String, default: "" },
     weekStart: { type: Number, default: 0 },
-    // 0 = Sunday, 1 = Monday, etc.
     locale: { type: String, default: "" }
   };
-  static actions = ["next", "onKeydown", "prev", "selectByClick"];
+  static valueConstraints = {
+    weekStart: { finite: true, integer: true, min: 0, max: 6 }
+  };
+  static actions = ["next", "onKeydown", "prev", "select"];
   static events = ["monthchange", "reconcile", "select"];
-  /** The date currently receiving focus in the grid (local time). */
   focusedDate = /* @__PURE__ */ new Date();
-  /**
-   * Whether `connect()` has run and `disconnect()` has not since. The paints
-   * before and during `connect()` describe the grid, so they report nothing.
-   */
   #connected = false;
-  /**
-   * The selection the last paint published — a `YYYY-MM-DD` day, or `""` — which
-   * the next move of the selection is measured from. A pick records its own day
-   * here before painting it.
-   */
   #published = "";
-  /**
-   * How many times a pick or a change the page made has moved the selection, so
-   * a report still pending for a selection a listener has since replaced can tell.
-   */
   #selectionMoves = 0;
-  /**
-   * The month the last paint showed (`YYYY-MM`), or `""` before the first paint.
-   * Only a connected grid reports a paint that moves it: settling on the initial
-   * month — before `connect()` or in it, from the attribute or derived here — is
-   * the grid describing itself, not a navigation, so it must not reach a
-   * listener that refetches inventory or pushes history.
-   *
-   * While `month` is empty this is also the month the next paint shows, so the
-   * grid stays where it is; the first `connect()` of this instance sets it to the
-   * month the grid opens on.
-   */
   #paintedMonth = "";
-  /**
-   * Whether this instance has connected before. Only its first connection picks
-   * the month a grid with no `month` opens on. A later one keeps the month on
-   * screen, and so do the paints Stimulus runs before it.
-   */
+  #monthMoves = 0;
+  #paintedDates = /* @__PURE__ */ new WeakMap();
   #opened = false;
-  /**
-   * Whether the paint about to run was asked for by this grid's own controls.
-   * The `month` and `selected` Values are shared with the page — application
-   * code and a Turbo morph write them too — so the field mirrors take their
-   * "did the user commit this" answer from the route, not from the Value.
-   */
-  #movedByUser = false;
-  /**
-   * Repaints the month on screen after `min`, `max` or `weekStart` changed.
-   *
-   * A morph that swaps several of them repaints once, and the delivery Stimulus
-   * makes before `connect()` is refused, because the grid is painted on
-   * connect. None of these Values decides the month on screen; `min` and `max`
-   * decide whether the requested day is published.
-   */
-  #repaint = new MicrotaskCoalescer(() => {
+  #ownMove = false;
+  #repaint = new MorphRenderWatcher(() => {
     this.#repaintKeepingFocus();
   });
-  /**
-   * The cell DOM focus was on, its day and the month on screen, recorded by the
-   * first repaint of a batch for the pass that settles focus after it.
-   */
   #focusOrigin = null;
-  /**
-   * Settles DOM focus once, after the last repaint of a batch. The callbacks of
-   * one mutation repaint one by one and each reads every Value as it stands, so
-   * a `selected` or `locale` callback can paint a month before that month's own
-   * callback has moved the tab stop into it. Outside a connection no pass is
-   * scheduled, so a grid that is not connected moves no focus.
-   */
   #settleFocus = new MicrotaskCoalescer(() => {
     this.#restoreFocus();
   });
   connect() {
-    this.#repaint.activate();
+    this.#repaint.observe(this.element);
     this.#settleFocus.activate();
     this.#focusOrigin = null;
     if (!this.monthValue && !this.#opened) {
@@ -238,85 +310,55 @@ var CalendarController = class extends Controller {
     this.#render();
     this.#connected = true;
   }
-  /**
-   * Drops a pending repaint and a pending focus move, and stops reporting, so
-   * nothing reaches for a grid that is not connected.
-   */
   disconnect() {
     this.#connected = false;
-    this.#repaint.cancel();
+    this.#repaint.disconnect();
     this.#settleFocus.cancel();
   }
-  /**
-   * Paints the month `month` names, whether application code, a morph or the
-   * grid's own navigation wrote it; focus in the grid follows to the tab stop.
-   */
   monthValueChanged() {
     if (!this.monthValue) return;
     this.#syncFocusedDateWithMonth();
     this.#repaintKeepingFocus();
   }
-  /**
-   * Repaints the label when application code changes `locale` at runtime.
-   *
-   * Stimulus runs this for the initial Value too, before `connect()`. The paint
-   * it triggers is idempotent — the month comes from `month` (or, while that is
-   * still empty, from `focusedDate`) — and a grid that has not connected
-   * reports nothing, so that paint never reports a month.
-   */
   localeValueChanged() {
     this.#repaintKeepingFocus();
   }
-  /**
-   * Repaints `aria-selected` and the field when the requested day changes, and
-   * moves the tab stop to the day the grid now publishes. A request `min` /
-   * `max` withhold is not published, so the tab stop stays where it was.
-   */
   selectedValueChanged() {
     const selection = parseISODateString(this.#selection);
     if (selection) this.focusedDate = selection;
     this.#repaintKeepingFocus();
   }
-  /** Repaints when `min` changes after connect, so the disabled days and the selection follow. */
   minValueChanged() {
     this.#repaint.schedule();
   }
-  /** Repaints when `max` changes after connect, so the disabled days and the selection follow. */
   maxValueChanged() {
     this.#repaint.schedule();
   }
-  /**
-   * Lays the grid out again when `weekStart` changes after connect, so every
-   * date moves to the column of its weekday.
-   *
-   * Only the day cells are painted: column headers are author markup, so the
-   * author updates them together with the Value.
-   */
   weekStartValueChanged() {
     this.#repaint.schedule();
   }
-  /** Navigates to the previous month. */
   prev(event) {
     if (event) event.preventDefault();
     this.#shiftMonth(-1);
   }
-  /** Navigates to the next month. */
   next(event) {
     if (event) event.preventDefault();
     this.#shiftMonth(1);
   }
-  /** Handles day selection when a gridcell is clicked. */
-  selectByClick(event) {
-    const dayElement = event.target?.closest(
-      targetSelector(this.identifier, "day")
-    );
-    if (!dayElement) return;
-    this.selectDayElement(dayElement);
+  select(source) {
+    const { origin, reason } = actionSource(source);
+    if (origin && origin.closest(`[data-controller~="${this.identifier}"]`) !== this.element)
+      return;
+    const day = origin?.closest(targetSelector(this.identifier, "day"));
+    if (!day || !this.dayTargets.includes(day)) return;
+    this.#selectDay(day, reason);
   }
-  /** Handles grid cell keyboard navigation and triggers selection. */
   onKeydown(event) {
     if (event.defaultPrevented) return;
     if (isReservedArrowChord(event)) return;
+    if ((event.key === "Home" || event.key === "End") && hasModifierChord(event)) return;
+    if ((event.key === "PageUp" || event.key === "PageDown") && (event.ctrlKey || event.altKey || event.metaKey))
+      return;
     const dayElement = event.target?.closest(
       targetSelector(this.identifier, "day")
     );
@@ -325,7 +367,8 @@ var CalendarController = class extends Controller {
     if (!date) return;
     let handled = true;
     let nextDate = new Date(date);
-    switch (logicalArrowKey(event.key, this.element)) {
+    const directionElement = this.hasGridTarget ? gridDirectionElement(this.gridTarget, this.element) : this.element;
+    switch (logicalArrowKey(event.key, directionElement)) {
       case "ArrowLeft":
         nextDate.setDate(nextDate.getDate() - 1);
         break;
@@ -340,16 +383,16 @@ var CalendarController = class extends Controller {
         break;
       case "PageUp":
         if (event.shiftKey) {
-          nextDate = this.#calculateShiftedYearDate(date, -1);
+          nextDate = shiftYearClamped(date, -1);
         } else {
-          nextDate = this.#calculateShiftedMonthDate(date, -1);
+          nextDate = shiftMonthClamped(date, -1);
         }
         break;
       case "PageDown":
         if (event.shiftKey) {
-          nextDate = this.#calculateShiftedYearDate(date, 1);
+          nextDate = shiftYearClamped(date, 1);
         } else {
-          nextDate = this.#calculateShiftedMonthDate(date, 1);
+          nextDate = shiftMonthClamped(date, 1);
         }
         break;
       case "Home":
@@ -371,7 +414,7 @@ var CalendarController = class extends Controller {
       case "Enter":
       case " ":
         event.preventDefault();
-        this.selectDayElement(dayElement);
+        this.#selectDay(dayElement, stateReasonFor(event));
         return;
       default:
         handled = false;
@@ -382,43 +425,13 @@ var CalendarController = class extends Controller {
       this.#focusAndNavigateToDate(nextDate);
     }
   }
-  /**
-   * First day of the month the grid paints: the `month` Value when it parses —
-   * while it is empty, the month on screen — otherwise the focused date's month.
-   *
-   * A malformed `month` falls back instead of stopping the paint: every cell
-   * keeps its `aria-selected` and the grid keeps its tab stop, so a Value typo
-   * still leaves the grid reachable by Tab and the author can see what they
-   * typed. Every consumer of "which month is on screen" reads it from here, so
-   * the paint and the `monthchange` report cannot name different months.
-   */
   #paintedMonthStart() {
     const monthInfo = parseISOMonthString(this.#monthRequest);
     return monthInfo ? new Date(monthInfo.year, monthInfo.month - 1, 1) : new Date(this.focusedDate.getFullYear(), this.focusedDate.getMonth(), 1);
   }
-  /**
-   * The month the grid is asked to paint: `month`, or while that is empty the
-   * month on screen, which `connect()` opens on the month of the published
-   * selection, else on the current one.
-   */
   get #monthRequest() {
     return this.monthValue || this.#paintedMonth;
   }
-  /**
-   * Renders the grid days and updates the month/year label, mirrors both
-   * fields, then reports each field the user's move moved and — once connected
-   * — a painted month that differs from the last one painted, and a published
-   * selection that a change the page made moved.
-   *
-   * The report belongs to the paint, not to the `month` Value: the Value is only
-   * one of the things that decide the month on screen. While a malformed `month`
-   * falls back, changing `selected` and selecting a neighbouring month's cell
-   * move the painted month too, and both repaint from here. Reading the report
-   * off the paint keeps the event naming the month the grid shows, in the
-   * `YYYY-MM` the detail contract promises, whichever route repainted.
-   *
-   * @stimeoRenderRoot
-   */
   #render() {
     const monthStart = this.#paintedMonthStart();
     const year = monthStart.getFullYear();
@@ -428,7 +441,7 @@ var CalendarController = class extends Controller {
       const locale = resolveLocale(this.element, this.localeValue);
       this.labelTarget.textContent = monthLabelFormatter(locale).format(monthStart);
     }
-    const days = this.#calculateGridDays(year, month);
+    const days = monthGridDays(year, month, this.#safeWeekStart);
     const dayElements = this.dayTargets;
     const consumerDisabled = /* @__PURE__ */ new Map();
     for (const el of dayElements) {
@@ -447,6 +460,7 @@ var CalendarController = class extends Controller {
         const kept = consumerDisabled.get(dateStr);
         if (kept !== void 0) el.setAttribute("aria-disabled", kept);
       }
+      this.#paintedDates.set(el, dateStr);
       el.setAttribute("data-date", dateStr);
       el.textContent = String(date.getDate());
       const isOutside = date.getFullYear() !== year || date.getMonth() !== month - 1;
@@ -472,25 +486,20 @@ var CalendarController = class extends Controller {
     const painted = toISOMonthString(monthStart);
     const previous = this.#paintedMonth;
     this.#paintedMonth = painted;
+    if (previous !== painted) this.#monthMoves += 1;
+    const monthMove = this.#monthMoves;
     const reconciled = this.#settleSelection(selection);
     const move = this.#selectionMoves;
-    for (const [field, value] of this.#mirrorFields(painted, selection, reconciled)) {
-      if (field.value === value) commitField(field);
+    for (const [field, value, write] of this.#mirrorFields(painted, selection, reconciled)) {
+      if (field.value === value && this.#fieldWrites.get(field) === write) commitField(field);
     }
-    if (this.#connected && previous !== painted && this.#paintedMonth === painted) {
+    if (this.#connected && previous !== painted && monthMove === this.#monthMoves) {
       this.dispatch("monthchange", { detail: { month: painted } });
     }
     if (reconciled && move === this.#selectionMoves) {
       this.dispatch("reconcile", { detail: { date: selection } });
     }
   }
-  /**
-   * Records the selection a paint publishes and says whether it moved from the
-   * one published before, which a connected grid reports as `reconcile`. A pick
-   * records its own day before its paint, so that paint finds no move, and
-   * nothing counts before the grid connects. A move counts as a move of the
-   * selection.
-   */
   #settleSelection(selection) {
     const published = this.#published;
     this.#published = selection;
@@ -498,18 +507,13 @@ var CalendarController = class extends Controller {
     this.#selectionMoves += 1;
     return true;
   }
-  /**
-   * Repaints the grid for a Value callback or a pick. The first repaint of a
-   * batch records where DOM focus stood on a day, for the settle pass; focus
-   * outside the grid is left alone.
-   */
   #repaintKeepingFocus() {
     if (!this.#focusOrigin) {
       const cell = this.dayTargets.find((day) => day === document.activeElement);
       if (cell) {
         this.#focusOrigin = {
           cell,
-          date: cell.getAttribute("data-date"),
+          date: cell.getAttribute("data-date") ?? this.#paintedDates.get(cell) ?? null,
           month: this.#paintedMonth
         };
         this.#settleFocus.schedule();
@@ -517,18 +521,6 @@ var CalendarController = class extends Controller {
     }
     this.#render();
   }
-  /**
-   * Puts DOM focus back on a day it can stay on once a batch of repaints has
-   * landed.
-   *
-   * While the painted month stays, a bound only toggles `aria-disabled` and a
-   * disabled day stays focusable, so nothing is called (`focus()` would scroll
-   * the day into view); `weekStart` moves every date to another cell, so focus
-   * follows its date, or goes to the tab stop once the date has left the grid.
-   * When the painted month moves, every cell shows another day, and focus goes
-   * to the tab stop of the new month. Focus a listener of the paint's events
-   * moved off the recorded cell stays where it went.
-   */
   #restoreFocus() {
     const origin = this.#focusOrigin;
     this.#focusOrigin = null;
@@ -538,57 +530,68 @@ var CalendarController = class extends Controller {
     const destination = (moved ? void 0 : this.dayTargets.find((cell) => cell.getAttribute("data-date") === origin.date)) ?? this.dayTargets.find((cell) => cell.getAttribute("tabindex") === "0");
     destination?.focus();
   }
-  /** Fills a selected-day field inserted or replaced at runtime with the published selection. */
+  labelTargetConnected() {
+    this.#repaint.schedule();
+  }
+  labelTargetDisconnected() {
+    this.#repaint.schedule();
+  }
   fieldTargetConnected(field) {
-    writeField(field, this.#selection);
+    this.#writeField(field, this.#selection);
+  }
+  fieldTargetDisconnected() {
+    this.#repaint.schedule();
   }
-  /** Fills a painted-month field inserted or replaced at runtime. */
   monthFieldTargetConnected(field) {
-    writeField(field, toISOMonthString(this.#paintedMonthStart()));
-  }
-  /**
-   * Mirrors the painted month and the published selection into their optional
-   * fields.
-   *
-   * @param reconciled - Whether a change the page made moved the selection in
-   *   this paint, which `reconcile` reports rather than the field.
-   * @returns Each field this grid's own controls moved, with the value written
-   *   to it, for the paint to report.
-   */
+    this.#writeField(field, toISOMonthString(this.#paintedMonthStart()));
+  }
+  monthFieldTargetDisconnected() {
+    this.#repaint.schedule();
+  }
+  #writeField(field, value) {
+    if (!writeField(field, value)) return false;
+    this.#fieldWrites.set(field, (this.#fieldWrites.get(field) ?? 0) + 1);
+    return true;
+  }
   #mirrorFields(painted, selection, reconciled) {
-    const byUser = this.#movedByUser;
-    this.#movedByUser = false;
+    const ownMove = this.#ownMove;
+    this.#ownMove = false;
     const moved = [];
-    if (this.hasFieldTarget && writeField(this.fieldTarget, selection) && !reconciled) {
-      moved.push([this.fieldTarget, selection]);
+    if (this.hasFieldTarget && this.#writeField(this.fieldTarget, selection) && !reconciled) {
+      moved.push([this.fieldTarget, selection, this.#fieldWrites.get(this.fieldTarget) ?? 0]);
     }
-    if (this.hasMonthFieldTarget && writeField(this.monthFieldTarget, painted)) {
-      moved.push([this.monthFieldTarget, painted]);
+    if (this.hasMonthFieldTarget && this.#writeField(this.monthFieldTarget, painted)) {
+      moved.push([
+        this.monthFieldTarget,
+        painted,
+        this.#fieldWrites.get(this.monthFieldTarget) ?? 0
+      ]);
     }
-    return byUser ? moved : [];
+    return ownMove ? moved : [];
   }
-  selectDayElement(dayElement) {
+  #selectDay(dayElement, reason) {
     if (dayElement.getAttribute("aria-disabled") === "true") return;
     const dateStr = dayElement.getAttribute("data-date");
     if (!dateStr || this.#isDateOutOfBounds(dateStr)) return;
     this.selectedValue = dateStr;
     const selected = parseISODateString(dateStr);
     if (selected) this.focusedDate = selected;
-    this.#movedByUser = true;
-    this.#selectionMoves += 1;
+    this.#ownMove = true;
+    const changed = dateStr !== this.#published;
+    if (changed) this.#selectionMoves += 1;
     const move = this.#selectionMoves;
     this.#published = dateStr;
     this.#repaintKeepingFocus();
-    if (move !== this.#selectionMoves) return;
-    this.dispatch("select", { detail: { date: dateStr } });
+    if (!changed || move !== this.#selectionMoves) return;
+    this.dispatch("select", { detail: { date: dateStr, reason } });
   }
   #focusAndNavigateToDate(date) {
     this.focusedDate = date;
     const targetMonthStr = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}`;
-    this.#movedByUser = true;
+    this.#ownMove = true;
     if (targetMonthStr !== this.#monthRequest) {
       this.monthValue = targetMonthStr;
-      return;
+      if (targetMonthStr !== this.#paintedMonth) return;
     }
     this.#render();
     const dateStr = toISODateString(date);
@@ -599,50 +602,29 @@ var CalendarController = class extends Controller {
     if (this.maxValue && dateStr > this.maxValue) return true;
     return false;
   }
-  /** The day `selected` requests: the Value when it names a real day, else `""`. */
   get #requestedDay() {
     return parseISODateString(this.selectedValue) ? this.selectedValue : "";
   }
-  /** The selection published for `requested`: the day while `min` / `max` allow it, else `""`. */
   #publishable(requested) {
     return requested && !this.#isDateOutOfBounds(requested) ? requested : "";
   }
-  /** The selection the grid publishes now. */
   get #selection() {
     return this.#publishable(this.#requestedDay);
   }
   #shiftMonth(delta) {
     const monthInfo = parseISOMonthString(this.#monthRequest);
     if (!monthInfo) return;
-    this.#movedByUser = true;
+    this.#ownMove = true;
     const nextMonthDate = new Date(monthInfo.year, monthInfo.month - 1 + delta, 1);
     this.monthValue = `${nextMonthDate.getFullYear()}-${String(nextMonthDate.getMonth() + 1).padStart(2, "0")}`;
-  }
-  #calculateShiftedMonthDate(baseDate, delta) {
-    const targetDate = new Date(baseDate.getFullYear(), baseDate.getMonth() + delta, 1);
-    const lastDayInTarget = new Date(
-      targetDate.getFullYear(),
-      targetDate.getMonth() + 1,
-      0
-    ).getDate();
-    const clampedDay = Math.min(baseDate.getDate(), lastDayInTarget);
-    targetDate.setDate(clampedDay);
-    return targetDate;
-  }
-  #calculateShiftedYearDate(baseDate, delta) {
-    const targetDate = new Date(baseDate.getFullYear() + delta, baseDate.getMonth(), 1);
-    const lastDayInTarget = new Date(
-      targetDate.getFullYear(),
-      targetDate.getMonth() + 1,
-      0
-    ).getDate();
-    const clampedDay = Math.min(baseDate.getDate(), lastDayInTarget);
-    targetDate.setDate(clampedDay);
-    return targetDate;
+    if (this.monthValue === this.#paintedMonth) {
+      this.#syncFocusedDateWithMonth();
+      this.#repaintKeepingFocus();
+    }
   }
   #getStartOfWeekDate(date) {
     const currentDay = date.getDay();
-    const shift = (currentDay - this.weekStartValue + 7) % 7;
+    const shift = (currentDay - this.#safeWeekStart + 7) % 7;
     const target = new Date(date);
     target.setDate(date.getDate() - shift);
     return target;
@@ -653,11 +635,6 @@ var CalendarController = class extends Controller {
     target.setDate(start.getDate() + 6);
     return target;
   }
-  /**
-   * Opens the tab stop on the published selection, else on today when the shown
-   * month holds it, else on the 1st of the shown month. A selection the grid
-   * does not show falls back to the 1st in the paint.
-   */
   #initializeFocusedDate() {
     const selection = parseISODateString(this.#selection);
     if (selection) {
@@ -682,29 +659,20 @@ var CalendarController = class extends Controller {
       if (today.getFullYear() === monthInfo.year && today.getMonth() === monthInfo.month - 1) {
         this.focusedDate = today;
       } else {
-        const targetDate = new Date(monthInfo.year, monthInfo.month - 1, 1);
-        const lastDayInTarget = new Date(monthInfo.year, monthInfo.month, 0).getDate();
-        const clampedDay = Math.min(this.focusedDate.getDate(), lastDayInTarget);
-        targetDate.setDate(clampedDay);
-        this.focusedDate = targetDate;
+        this.focusedDate = dateInMonthClamped(this.focusedDate, monthInfo.year, monthInfo.month);
       }
     }
   }
-  #calculateGridDays(year, month) {
-    const firstDay = new Date(year, month - 1, 1);
-    const dayOfWeek = firstDay.getDay();
-    const offset = (dayOfWeek - this.weekStartValue + 7) % 7;
-    const days = [];
-    const current = new Date(firstDay);
-    current.setDate(firstDay.getDate() - offset);
-    for (let i = 0; i < 42; i++) {
-      days.push(new Date(current));
-      current.setDate(current.getDate() + 1);
-    }
-    return days;
+  get #safeWeekStart() {
+    return this.#numbers.read(
+      this,
+      "weekStart",
+      this.weekStartValue,
+      _CalendarController.values.weekStart.default,
+      _CalendarController.valueConstraints.weekStart
+    );
   }
 };
 
 export { CalendarController };
-//# sourceMappingURL=calendar_controller.js.map
 //# sourceMappingURL=calendar_controller.js.map