stimeo-ui 0.14.0 → 0.16.0

data/dist/controllers/calendar_controller.js

@@ -85,123 +85,215 @@ function monthLabelFormatter(locale) {
   return intlFormatter(Intl.DateTimeFormat, locale, MONTH_LABEL_OPTIONS, "en");
 }
 
-// src/utils/safe_timeout.ts
-var TimerRegistry = class {
-  /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
-  ids = /* @__PURE__ */ new Set();
-  /**
-   * Cancels a single tracked timer.
-   *
-   * No-ops if the id is unknown (already cleared, fired, or never owned by this
-   * registry), so callers can clear defensively without guarding.
-   */
-  clear(id) {
-    if (this.ids.delete(id)) {
-      this.cancel(id);
-    }
-  }
-  /**
-   * Cancels every tracked timer. Call this from a controller's `disconnect()`
-   * to guarantee no timer outlives the element.
-   */
-  clearAll() {
-    for (const id of this.ids) {
-      this.cancel(id);
-    }
-    this.ids.clear();
-  }
-  /** Number of timers currently tracked (pending). */
-  get size() {
-    return this.ids.size;
+// src/utils/field_mirror.ts
+function writeField(field, value) {
+  if (field.value === value) return false;
+  field.value = value;
+  return true;
+}
+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;
   }
-};
-var SafeTimeout = class extends TimerRegistry {
-  /**
-   * Schedules `callback` after `delay` ms and returns the timer id.
-   *
-   * The id is removed from the registry automatically when the timeout fires,
-   * so {@link TimerRegistry.size | size} reflects only still-pending timers.
-   */
-  set(callback, delay) {
-    const id = this.schedule(() => {
-      this.ids.delete(id);
-      callback();
-    }, delay);
-    this.ids.add(id);
-    return id;
+  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
+  activate() {
+    this.#active = true;
   }
-  schedule(callback, delay) {
-    return window.setTimeout(callback, delay);
+  /** Closes the window and drops any pending pass; call from `disconnect()`. */
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
   }
-  cancel(id) {
-    window.clearTimeout(id);
+  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */
+  schedule() {
+    if (!this.#active || this.#queued) return;
+    this.#queued = true;
+    const generation = this.#generation;
+    queueMicrotask(() => {
+      if (generation !== this.#generation || !this.#queued || !this.#active) return;
+      this.#queued = false;
+      this.#run();
+    });
   }
 };
 
+// src/utils/target_selector.ts
+function targetSelector(identifier, name) {
+  return `[data-${identifier}-target~="${name}"]`;
+}
+
 // src/controllers/calendar_controller.ts
-var OWNED_DISABLED = "data-stimeo--calendar-owns-disabled";
+var OWNED_DISABLED = "owns-disabled";
 var CalendarController = class extends Controller {
-  static targets = ["label", "grid", "day"];
+  /** The marker above, in the namespace this controller is registered under. */
+  get #ownedDisabled() {
+    return `data-${this.identifier}-${OWNED_DISABLED}`;
+  }
+  static targets = ["label", "grid", "day", "field", "monthField"];
   static values = {
     month: { type: String, default: "" },
     selected: { type: String, default: "" },
     min: { type: String, default: "" },
     max: { type: String, default: "" },
-    weekStart: { type: Number, default: 0 }
+    weekStart: { type: Number, default: 0 },
     // 0 = Sunday, 1 = Monday, etc.
+    locale: { type: String, default: "" }
   };
   static actions = ["next", "onKeydown", "prev", "selectByClick"];
-  static events = ["monthchange", "select"];
+  static events = ["monthchange", "reconcile", "select"];
   /** The date currently receiving focus in the grid (local time). */
   focusedDate = /* @__PURE__ */ new Date();
   /**
-   * Deferred focus moves scheduled after an asynchronous month transition.
-   * Tracked so {@link disconnect} can cancel any pending move and a detached
-   * controller never steals focus after the element leaves the DOM (Turbo).
+   * Whether `connect()` has run and `disconnect()` has not since. The paints
+   * before and during `connect()` describe the grid, so they report nothing.
    */
-  #focusTimer = new SafeTimeout();
+  #connected = false;
   /**
-   * The painted month the last `monthchange` reported, or `null` before the first
-   * paint. Settling on the initial month — whether it comes from the attribute or
-   * is derived here — is the grid describing itself, not a navigation, so it must
-   * not reach a listener that refetches inventory or pushes history.
+   * 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.
    */
-  #announcedMonth = null;
+  #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.
+   */
+  #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(() => {
+    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() {
-    if (!this.monthValue) {
-      const today = /* @__PURE__ */ new Date();
-      const monthStr = `${today.getFullYear()}-${String(today.getMonth() + 1).padStart(2, "0")}`;
-      this.monthValue = monthStr;
-      return;
+    this.#repaint.activate();
+    this.#settleFocus.activate();
+    this.#focusOrigin = null;
+    if (!this.monthValue && !this.#opened) {
+      this.#paintedMonth = toISOMonthString(parseISODateString(this.#selection) ?? /* @__PURE__ */ new Date());
     }
+    this.#opened = true;
     this.#initializeFocusedDate();
-    this.render();
+    this.#render();
+    this.#connected = true;
   }
-  /** Cancels any pending deferred focus so it never fires on a detached element. */
+  /**
+   * Drops a pending repaint and a pending focus move, and stops reporting, so
+   * nothing reaches for a grid that is not connected.
+   */
   disconnect() {
-    this.#focusTimer.clearAll();
+    this.#connected = false;
+    this.#repaint.cancel();
+    this.#settleFocus.cancel();
   }
   /**
-   * Stimulus lifecycle callback triggered automatically when the monthValue changes.
-   * Forces a re-render of the date grid and updates labels.
+   * 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.render();
+    this.#repaintKeepingFocus();
   }
   /**
-   * Stimulus lifecycle callback triggered automatically when the selectedValue changes.
-   * Re-renders grid cells to update `aria-selected` indicators.
+   * 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() {
-    if (this.selectedValue) {
-      const selected = parseISODateString(this.selectedValue);
-      if (selected) {
-        this.focusedDate = selected;
-      }
-    }
-    this.render();
+    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) {
@@ -216,7 +308,7 @@ var CalendarController = class extends Controller {
   /** Handles day selection when a gridcell is clicked. */
   selectByClick(event) {
     const dayElement = event.target?.closest(
-      "[data-stimeo--calendar-target='day']"
+      targetSelector(this.identifier, "day")
     );
     if (!dayElement) return;
     this.selectDayElement(dayElement);
@@ -226,7 +318,7 @@ var CalendarController = class extends Controller {
     if (event.defaultPrevented) return;
     if (isReservedArrowChord(event)) return;
     const dayElement = event.target?.closest(
-      "[data-stimeo--calendar-target='day']"
+      targetSelector(this.identifier, "day")
     );
     if (!dayElement) return;
     const date = parseISODateString(dayElement.getAttribute("data-date") ?? "");
@@ -291,8 +383,8 @@ var CalendarController = class extends Controller {
     }
   }
   /**
-   * First day of the month the grid paints: the `month` Value when it parses,
-   * otherwise the focused date's month.
+   * 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
@@ -301,12 +393,22 @@ var CalendarController = class extends Controller {
    * the paint and the `monthchange` report cannot name different months.
    */
   #paintedMonthStart() {
-    const monthInfo = parseISOMonthString(this.monthValue);
+    const monthInfo = parseISOMonthString(this.#monthRequest);
     return monthInfo ? new Date(monthInfo.year, monthInfo.month - 1, 1) : new Date(this.focusedDate.getFullYear(), this.focusedDate.getMonth(), 1);
   }
   /**
-   * Renders the grid days and updates the month/year label, then reports the
-   * painted month once it differs from the one already announced.
+   * 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`
@@ -314,24 +416,36 @@ var CalendarController = class extends Controller {
    * 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() {
+  #render() {
     const monthStart = this.#paintedMonthStart();
     const year = monthStart.getFullYear();
     const month = monthStart.getMonth() + 1;
+    const selection = this.#selection;
     if (this.hasLabelTarget) {
-      const lang = document.documentElement.lang || "en";
-      this.labelTarget.textContent = monthLabelFormatter(lang).format(monthStart);
+      const locale = resolveLocale(this.element, this.localeValue);
+      this.labelTarget.textContent = monthLabelFormatter(locale).format(monthStart);
     }
     const days = this.#calculateGridDays(year, month);
     const dayElements = this.dayTargets;
+    const consumerDisabled = /* @__PURE__ */ new Map();
+    for (const el of dayElements) {
+      const shown = el.getAttribute("data-date");
+      const value = el.getAttribute("aria-disabled");
+      if (!shown || value === null || el.hasAttribute(this.#ownedDisabled)) continue;
+      consumerDisabled.set(shown, value);
+    }
     for (const [index, date] of days.entries()) {
       const el = dayElements[index];
       if (!el) continue;
       const dateStr = toISODateString(date);
       if (el.getAttribute("data-date") !== dateStr) {
         el.removeAttribute("aria-disabled");
-        el.removeAttribute(OWNED_DISABLED);
+        el.removeAttribute(this.#ownedDisabled);
+        const kept = consumerDisabled.get(dateStr);
+        if (kept !== void 0) el.setAttribute("aria-disabled", kept);
       }
       el.setAttribute("data-date", dateStr);
       el.textContent = String(date.getDate());
@@ -339,17 +453,16 @@ var CalendarController = class extends Controller {
       el.setAttribute("data-outside", String(isOutside));
       const todayStr = toISODateString(/* @__PURE__ */ new Date());
       el.setAttribute("data-today", String(dateStr === todayStr));
-      const isSelected = dateStr === this.selectedValue;
-      el.setAttribute("aria-selected", String(isSelected));
+      el.setAttribute("aria-selected", String(dateStr === selection));
       const isFocused = toISODateString(this.focusedDate) === dateStr;
       el.setAttribute("tabindex", isFocused ? "0" : "-1");
       const isDisabled = this.#isDateOutOfBounds(dateStr);
       if (isDisabled) {
-        if (!el.hasAttribute("aria-disabled")) el.setAttribute(OWNED_DISABLED, "");
+        if (!el.hasAttribute("aria-disabled")) el.setAttribute(this.#ownedDisabled, "");
         el.setAttribute("aria-disabled", "true");
-      } else if (el.hasAttribute(OWNED_DISABLED)) {
+      } else if (el.hasAttribute(this.#ownedDisabled)) {
         el.removeAttribute("aria-disabled");
-        el.removeAttribute(OWNED_DISABLED);
+        el.removeAttribute(this.#ownedDisabled);
       }
     }
     if (!dayElements.some((el) => el.getAttribute("tabindex") === "0")) {
@@ -357,50 +470,151 @@ var CalendarController = class extends Controller {
       fallback?.setAttribute("tabindex", "0");
     }
     const painted = toISOMonthString(monthStart);
-    const previous = this.#announcedMonth;
-    this.#announcedMonth = painted;
-    if (previous !== null && previous !== painted) {
+    const previous = this.#paintedMonth;
+    this.#paintedMonth = painted;
+    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);
+    }
+    if (this.#connected && previous !== painted && this.#paintedMonth === painted) {
       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;
+    if (!this.#connected || selection === published) return false;
+    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"),
+          month: this.#paintedMonth
+        };
+        this.#settleFocus.schedule();
+      }
+    }
+    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;
+    if (!origin || document.activeElement !== origin.cell) return;
+    const moved = this.#paintedMonth !== origin.month;
+    if (!moved && origin.cell.getAttribute("data-date") === origin.date) return;
+    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. */
+  fieldTargetConnected(field) {
+    writeField(field, this.#selection);
+  }
+  /** 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.
+   */
+  #mirrorFields(painted, selection, reconciled) {
+    const byUser = this.#movedByUser;
+    this.#movedByUser = false;
+    const moved = [];
+    if (this.hasFieldTarget && writeField(this.fieldTarget, selection) && !reconciled) {
+      moved.push([this.fieldTarget, selection]);
+    }
+    if (this.hasMonthFieldTarget && writeField(this.monthFieldTarget, painted)) {
+      moved.push([this.monthFieldTarget, painted]);
+    }
+    return byUser ? moved : [];
   }
   selectDayElement(dayElement) {
     if (dayElement.getAttribute("aria-disabled") === "true") return;
     const dateStr = dayElement.getAttribute("data-date");
-    if (!dateStr) return;
+    if (!dateStr || this.#isDateOutOfBounds(dateStr)) return;
     this.selectedValue = dateStr;
     const selected = parseISODateString(dateStr);
     if (selected) this.focusedDate = selected;
-    this.render();
+    this.#movedByUser = true;
+    this.#selectionMoves += 1;
+    const move = this.#selectionMoves;
+    this.#published = dateStr;
+    this.#repaintKeepingFocus();
+    if (move !== this.#selectionMoves) return;
     this.dispatch("select", { detail: { date: dateStr } });
   }
   #focusAndNavigateToDate(date) {
     this.focusedDate = date;
     const targetMonthStr = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}`;
-    const isMonthTransition = targetMonthStr !== this.monthValue;
-    if (isMonthTransition) {
+    this.#movedByUser = true;
+    if (targetMonthStr !== this.#monthRequest) {
       this.monthValue = targetMonthStr;
-    } else {
-      this.render();
-    }
-    const focusTarget = () => {
-      const dateStr = toISODateString(date);
-      const targetEl = this.dayTargets.find((el) => el.getAttribute("data-date") === dateStr);
-      targetEl?.focus();
-    };
-    if (isMonthTransition) {
-      this.#focusTimer.set(focusTarget, 0);
-    } else {
-      focusTarget();
+      return;
     }
+    this.#render();
+    const dateStr = toISODateString(date);
+    this.dayTargets.find((el) => el.getAttribute("data-date") === dateStr)?.focus();
   }
   #isDateOutOfBounds(dateStr) {
     if (this.minValue && dateStr < this.minValue) return true;
     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.monthValue);
+    const monthInfo = parseISOMonthString(this.#monthRequest);
     if (!monthInfo) return;
+    this.#movedByUser = true;
     const nextMonthDate = new Date(monthInfo.year, monthInfo.month - 1 + delta, 1);
     this.monthValue = `${nextMonthDate.getFullYear()}-${String(nextMonthDate.getMonth() + 1).padStart(2, "0")}`;
   }
@@ -439,15 +653,18 @@ 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() {
-    if (this.selectedValue) {
-      const selected = parseISODateString(this.selectedValue);
-      if (selected) {
-        this.focusedDate = selected;
-        return;
-      }
+    const selection = parseISODateString(this.#selection);
+    if (selection) {
+      this.focusedDate = selection;
+      return;
     }
-    const monthInfo = parseISOMonthString(this.monthValue);
+    const monthInfo = parseISOMonthString(this.#monthRequest);
     if (monthInfo) {
       const today = /* @__PURE__ */ new Date();
       if (today.getFullYear() === monthInfo.year && today.getMonth() === monthInfo.month - 1) {