stimeo-ui 0.14.0 → 0.16.0

package/dist/controllers/date_range_picker_controller.d.ts

@@ -33,13 +33,26 @@ import { Controller } from '@hotwired/stimulus';
  * `data-range-start` / `data-in-range` / `data-range-end` hooks. Assistive tech
  * is told the two confirmed endpoints via `aria-selected`; inner cells use
  * `data-in-range` (visual only) so the announcement stays to the two ends. The
- * confirmed range is also mirrored to the live `status` region.
+ * range the user confirms is also announced in the live `status` region.
  *
  * Selection model: the first click/Enter sets a *pending* start and enters
  * "selecting" mode (preview follows the pointer/focus); the second confirms the
- * end (auto-swapped if earlier than the start) and dispatches `change` with
- * `{ start, end }` ISO dates. Escape abandons an in-progress selection,
- * restoring the last confirmed range.
+ * end (auto-swapped if earlier than the start), and a preset confirms its range
+ * in one step. Escape abandons an in-progress selection, restoring the last
+ * confirmed range.
+ *
+ * A confirmed range is painted — the cells, both hidden fields and the status —
+ * before anything reports it. Each hidden field that moved then emits a native
+ * bubbling `change`, the way a form control does, so `stimeo--auto-submit` and
+ * form-level validation hear it; `monthchange` follows when the paint moved the
+ * month, and last `change` dispatches `{ start: string, end: string }`, the ISO
+ * range the picker holds. A bound a listener moves meanwhile is applied by the
+ * repaint its Value callback runs, so the `reconcile` it causes follows the
+ * `change`. A listener that replaces the range before these reports are all out
+ * — by confirming another range, or with a repaint that narrows this one — has
+ * the replacing range report itself: what is still pending for the replaced
+ * range is not sent, and focus stays where the replacing move put it. The seed
+ * `connect()` reads out of the hidden fields is written back silently.
  *
  * Availability is declarative on both axes: `min` / `max` bound the selectable
  * interval and `disabledDates` excludes individual dates inside it. Both are
@@ -49,6 +62,17 @@ import { Controller } from '@hotwired/stimulus';
  * navigation dispatches `monthchange` with `{ month }` as a notification (for
  * fetching a month's availability, say); the fetched result comes back in
  * through `disabledDates`, which repaints on its own.
+ *
+ * The same predicate holds the confirmed range. When a change to `min`, `max`
+ * or `disabledDates` leaves an end unselectable, the paint narrows the range:
+ * each end moves inward to the nearest day that can still be chosen, and a
+ * range with no such day left is cleared. The hidden fields follow without a
+ * native `change`, the status keeps announcing what the user confirmed, and
+ * `reconcile` dispatches `{ start: string, end: string }` — the narrowed range,
+ * empty strings once cleared — rather than `change`, which stays the user's.
+ * `connect()` narrows the range it reads from the fields the same way,
+ * silently. An in-progress selection whose start becomes unselectable is
+ * dropped, as Escape would drop it, and the next pick starts a new one.
  */
 declare class DateRangePickerController extends Controller<HTMLElement> {
     #private;
@@ -66,9 +90,13 @@ declare class DateRangePickerController extends Controller<HTMLElement> {
             type: StringConstructor;
             default: string;
         };
+        locale: {
+            type: StringConstructor;
+            default: string;
+        };
     };
     static actions: readonly ["applyPreset", "next", "onKeydown", "prev", "previewTo", "selectDate"];
-    static events: readonly ["change", "monthchange"];
+    static events: readonly ["change", "monthchange", "reconcile"];
     readonly gridTarget: HTMLElement;
     readonly hasGridTarget: boolean;
     readonly monthLabelTarget: HTMLElement;
@@ -83,10 +111,17 @@ declare class DateRangePickerController extends Controller<HTMLElement> {
     minValue: string;
     maxValue: string;
     disabledDatesValue: string;
-    /** Seeds and normalizes the range from optional hidden fields, then paints the grid. */
+    localeValue: string;
+    /**
+     * Seeds the range from optional hidden fields — ordered, and narrowed to the
+     * days that can be chosen — then paints the grid, which writes the range back
+     * to the fields silently.
+     */
     connect(): void;
     /** Cancels any pending deferred focus so it never fires on a detached element. */
     disconnect(): void;
+    /** Repaints the label when application code changes `locale` at runtime. */
+    localeValueChanged(): void;
     /** Repaints when application code (or a Turbo morph) changes `min` at runtime. */
     minValueChanged(): void;
     /** Repaints when application code (or a Turbo morph) changes `max` at runtime. */

package/dist/controllers/date_range_picker_controller.js

@@ -114,6 +114,21 @@ 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;
+  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;
@@ -214,6 +229,11 @@ function parseStringList(raw, fallback = []) {
   return parsed.filter((entry) => typeof entry === "string");
 }
 
+// src/utils/target_selector.ts
+function targetSelector(identifier, name) {
+  return `[data-${identifier}-target~="${name}"]`;
+}
+
 // src/controllers/date_range_picker_controller.ts
 var GRID_SIZE = 42;
 var DateRangePickerController = class extends Controller {
@@ -224,10 +244,11 @@ var DateRangePickerController = class extends Controller {
     // A JSON list read through `parseStringList` rather than Stimulus's `Array`
     // type: that reader throws out of the value observer before any callback
     // runs, so one malformed attribute would stop the picker from connecting.
-    disabledDates: { type: String, default: "" }
+    disabledDates: { type: String, default: "" },
+    locale: { type: String, default: "" }
   };
   static actions = ["applyPreset", "next", "onKeydown", "prev", "previewTo", "selectDate"];
-  static events = ["change", "monthchange"];
+  static events = ["change", "monthchange", "reconcile"];
   /** The month currently rendered, as `YYYY-MM`. */
   #viewMonth = "";
   /** The confirmed range endpoints (ISO), or "" when unset. */
@@ -241,6 +262,13 @@ var DateRangePickerController = class extends Controller {
   #focusedDate = /* @__PURE__ */ new Date();
   /** Deferred focus after an async month transition (cancelled on teardown). */
   #focusTimer = new SafeTimeout();
+  /**
+   * How many times the confirmed range has moved — a commit or a narrowing — so
+   * a report still pending for a range a listener has since replaced can tell.
+   */
+  #rangeMoves = 0;
+  /** How many month transitions have started, so one a listener starts mid-paint keeps its focus. */
+  #transitions = 0;
   /** The declared unavailable dates, indexed for the per-cell paint lookup. */
   #disabledDates = /* @__PURE__ */ new Set();
   /** Rewinds an unfinished selection before Turbo snapshots the page. */
@@ -254,17 +282,22 @@ var DateRangePickerController = class extends Controller {
   #repaint = new MicrotaskCoalescer(() => {
     this.#render();
   });
-  /** Seeds and normalizes the range from optional hidden fields, then paints the grid. */
+  /**
+   * Seeds the range from optional hidden fields — ordered, and narrowed to the
+   * days that can be chosen — then paints the grid, which writes the range back
+   * to the fields silently.
+   */
   connect() {
     this.#repaint.activate();
     this.#beforeCache.activate();
     const authoredStart = this.hasStartFieldTarget ? normalizeISO(this.startFieldTarget.value) : "";
     const authoredEnd = this.hasEndFieldTarget ? normalizeISO(this.endFieldTarget.value) : "";
-    [this.#startDate, this.#endDate] = orderRange(authoredStart, authoredEnd);
+    [this.#startDate, this.#endDate] = this.#selectableRange(
+      ...orderRange(authoredStart, authoredEnd)
+    );
     this.#pendingStart = "";
     this.#previewDate = "";
     this.#announcedMonth = null;
-    this.#commitFields();
     const anchor = parseISODateString(this.#startDate) ?? this.#clampToBounds(/* @__PURE__ */ new Date()) ?? /* @__PURE__ */ new Date();
     this.#focusedDate = anchor;
     this.#viewMonth = toISOMonthString(anchor);
@@ -277,6 +310,10 @@ var DateRangePickerController = class extends Controller {
     this.#beforeCache.deactivate();
     this.#focusTimer.clearAll();
   }
+  /** Repaints the label when application code changes `locale` at runtime. */
+  localeValueChanged() {
+    this.#repaint.schedule();
+  }
   /** Repaints when application code (or a Turbo morph) changes `min` at runtime. */
   minValueChanged() {
     this.#repaint.schedule();
@@ -335,16 +372,11 @@ var DateRangePickerController = class extends Controller {
     if (!intersection) return;
     const { start, end } = intersection;
     if (!this.#isSelectable(start) || !this.#isSelectable(end)) return;
-    this.#startDate = start;
-    this.#endDate = end;
-    this.#pendingStart = "";
-    this.#previewDate = "";
+    const move = this.#setConfirmed(start, end);
     const endDate = parseISODateString(end);
     if (endDate) this.#focusedDate = endDate;
-    this.#commitFields();
-    this.#transitionTo(toISOMonthString(parseISODateString(end) ?? /* @__PURE__ */ new Date()), end);
-    this.#announce();
-    this.dispatch("change", { detail: { start, end } });
+    this.#transitionTo(toISOMonthString(parseISODateString(end) ?? /* @__PURE__ */ new Date()), end, true);
+    this.#reportConfirmed(move);
   }
   /** Grid keyboard navigation, selection (Enter/Space), and Escape-to-cancel. */
   onKeydown(event) {
@@ -403,7 +435,7 @@ var DateRangePickerController = class extends Controller {
   }
   /** Records a chosen date as either the pending start or the confirmed end. */
   #choose(date) {
-    if (!this.#pendingStart) {
+    if (!this.#pendingStart || !this.#isSelectable(this.#pendingStart)) {
       this.#pendingStart = date;
       this.#previewDate = date;
       const parsed = parseISODateString(date);
@@ -412,14 +444,32 @@ var DateRangePickerController = class extends Controller {
       return;
     }
     const [start, end] = date < this.#pendingStart ? [date, this.#pendingStart] : [this.#pendingStart, date];
+    const move = this.#setConfirmed(start, end);
+    this.#render(true);
+    this.#reportConfirmed(move);
+  }
+  /**
+   * Makes `start`–`end` the confirmed range, ending any selection in progress,
+   * ahead of the paint that shows it.
+   *
+   * @returns The move count the range is now at, which its `change` checks.
+   */
+  #setConfirmed(start, end) {
     this.#startDate = start;
     this.#endDate = end;
     this.#pendingStart = "";
     this.#previewDate = "";
-    this.#commitFields();
-    this.#render();
-    this.#announce();
-    this.dispatch("change", { detail: { start, end } });
+    this.#rangeMoves += 1;
+    return this.#rangeMoves;
+  }
+  /**
+   * Dispatches `change` for the range confirmed at `move`, once its paint has
+   * reported it through the fields. A listener of those reports that moved the
+   * range on has had the range it moved to reported instead.
+   */
+  #reportConfirmed(move) {
+    if (move !== this.#rangeMoves) return;
+    this.dispatch("change", { detail: { start: this.#startDate, end: this.#endDate } });
   }
   /** Moves roving focus to `date`, transitioning the month when needed. */
   #moveFocusTo(date) {
@@ -428,12 +478,21 @@ var DateRangePickerController = class extends Controller {
     if (this.#pendingStart && this.#isSelectable(iso)) this.#previewDate = iso;
     this.#transitionTo(toISOMonthString(date), iso);
   }
-  /** Renders `month`, then focuses the cell for `dateStr` (deferred if async). */
-  #transitionTo(month, dateStr) {
+  /**
+   * Renders `month`, then focuses the cell for `dateStr` (deferred if async).
+   * A listener of the paint's reports that started another move has placed
+   * focus itself, so this one leaves it there.
+   *
+   * @param confirmed - Whether the paint shows a range the user has just confirmed.
+   */
+  #transitionTo(month, dateStr, confirmed = false) {
     const isTransition = month !== this.#viewMonth;
     this.#focusTimer.clearAll();
     this.#viewMonth = month;
-    this.#render();
+    this.#transitions += 1;
+    const transition = this.#transitions;
+    this.#render(confirmed);
+    if (transition !== this.#transitions) return;
     const focusCell = () => {
       this.cellTargets.find((c) => c.getAttribute("data-date") === dateStr)?.focus();
     };
@@ -455,18 +514,27 @@ var DateRangePickerController = class extends Controller {
     this.#render();
   }
   /**
-   * Builds the six-week grid and binds range/roving/disabled state per cell.
+   * Builds the six-week grid and binds range/roving/disabled state per cell,
+   * mirrors the confirmed range to the hidden fields, then reports what the
+   * paint moved.
+   *
+   * @param confirmed - Whether the paint shows a range the user has just
+   *   confirmed, which the status then announces and each moved field reports.
    *
    * @stimeoRenderRoot
    */
-  #render() {
+  #render(confirmed = false) {
     const info = parseISOMonthString(this.#viewMonth);
     if (!info) return;
     const { year, month } = info;
+    if (this.#pendingStart && !this.#isSelectable(this.#pendingStart)) {
+      this.#pendingStart = "";
+      this.#previewDate = "";
+    }
     if (this.#previewDate && !this.#isSelectable(this.#previewDate)) this.#previewDate = "";
+    const narrowed = this.#narrowConfirmedRange();
     if (this.hasMonthLabelTarget) {
-      const lang = document.documentElement.lang || "en";
-      const formatter = monthLabelFormatter(lang);
+      const formatter = monthLabelFormatter(resolveLocale(this.element, this.localeValue));
       this.monthLabelTarget.textContent = formatter.format(new Date(year, month - 1, 1));
     }
     const [rangeStart, rangeEnd] = this.#visualRange();
@@ -504,11 +572,54 @@ var DateRangePickerController = class extends Controller {
       const fallback = cells.find((cell) => cell.getAttribute("data-outside") === "false") ?? cells[0];
       fallback?.setAttribute("tabindex", "0");
     }
+    const move = this.#rangeMoves;
+    const moved = this.#mirrorFields();
+    if (confirmed) {
+      this.#announce();
+      for (const [field, value] of moved) {
+        if (field.value === value) commitField(field);
+      }
+    }
     const previous = this.#announcedMonth;
     this.#announcedMonth = this.#viewMonth;
     if (previous !== null && previous !== this.#viewMonth) {
       this.dispatch("monthchange", { detail: { month: this.#viewMonth } });
     }
+    if (narrowed && move === this.#rangeMoves) {
+      this.dispatch("reconcile", { detail: { start: this.#startDate, end: this.#endDate } });
+    }
+  }
+  /**
+   * Narrows the confirmed range to days that can still be chosen. The paint
+   * mirrors it to the fields without reporting a commit.
+   *
+   * @returns Whether the range moved.
+   */
+  #narrowConfirmedRange() {
+    const [start, end] = this.#selectableRange(this.#startDate, this.#endDate);
+    if (start === this.#startDate && end === this.#endDate) return false;
+    this.#startDate = start;
+    this.#endDate = end;
+    this.#rangeMoves += 1;
+    return true;
+  }
+  /**
+   * The range `start`–`end` with each end moved inward to the nearest day that
+   * can be chosen, or two empty strings when none of its days can be. A lone
+   * endpoint is the one-day range it names, and stays lone.
+   */
+  #selectableRange(start, end) {
+    let from = parseISODateString(start || end);
+    let to = parseISODateString(end || start);
+    if (!from || !to) return [start, end];
+    while (from.getTime() <= to.getTime() && !this.#isSelectable(toISODateString(from))) {
+      from = addDays(from, 1);
+    }
+    while (to.getTime() >= from.getTime() && !this.#isSelectable(toISODateString(to))) {
+      to = addDays(to, -1);
+    }
+    if (from.getTime() > to.getTime()) return ["", ""];
+    return [start ? toISODateString(from) : "", end ? toISODateString(to) : ""];
   }
   /** The ordered [start, end] pair to paint: the preview while selecting, else confirmed. */
   #visualRange() {
@@ -518,10 +629,20 @@ var DateRangePickerController = class extends Controller {
     }
     return [this.#startDate, this.#endDate];
   }
-  /** Writes the confirmed range to the hidden fields. */
-  #commitFields() {
-    if (this.hasStartFieldTarget) this.startFieldTarget.value = this.#startDate;
-    if (this.hasEndFieldTarget) this.endFieldTarget.value = this.#endDate;
+  /**
+   * Writes the confirmed range to the hidden fields.
+   *
+   * @returns Each field whose value moved, with the value written to it.
+   */
+  #mirrorFields() {
+    const moved = [];
+    if (this.hasStartFieldTarget && writeField(this.startFieldTarget, this.#startDate)) {
+      moved.push([this.startFieldTarget, this.#startDate]);
+    }
+    if (this.hasEndFieldTarget && writeField(this.endFieldTarget, this.#endDate)) {
+      moved.push([this.endFieldTarget, this.#endDate]);
+    }
+    return moved;
   }
   /** Announces the confirmed range in the live status region. */
   #announce() {
@@ -581,7 +702,7 @@ var DateRangePickerController = class extends Controller {
   /** Resolves the cell element from an event target, or null. */
   #cellFrom(target) {
     return target?.closest(
-      "[data-stimeo--date-range-picker-target='cell']"
+      targetSelector(this.identifier, "cell")
     ) ?? null;
   }
 };