stimeo-ui 0.5.0 → 0.6.0

data/dist/controllers/checkbox_controller.js

@@ -1,17 +1,89 @@
 import { Controller } from '@hotwired/stimulus';
 
+// src/controllers/checkbox_controller.ts
+
+// 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. */
+  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/controllers/checkbox_controller.ts
 var CheckboxController = class extends Controller {
   static targets = ["parent", "child"];
   static actions = ["onChildChange", "onParentChange"];
-  static events = ["change"];
-  /** Reflects the initial aggregate (e.g. from server-rendered child states). */
-  connect() {
-    if (this.childTargets.length > 0) {
-      this.#syncFromChildren(false);
-    } else {
-      this.element.setAttribute("data-state", this.#aggregate());
+  static events = ["change", "reconcile"];
+  /** Collapses every lifecycle signal from one DOM update into one derived pass. */
+  #reconcile = new MicrotaskCoalescer(() => this.#reconcileFromChildren());
+  /** Aggregate this root last settled on, so a derived repair is reported once. */
+  #committedState = null;
+  /** Watches authored checked-attribute changes on retained target elements. */
+  #checkedObserver = new MutationObserver((records) => {
+    if (records.some((record) => this.#isManagedCheckbox(record.target))) {
+      this.#reconcile.schedule();
     }
+  });
+  /** Reflects the initial aggregate and starts retained-DOM reconciliation. */
+  connect() {
+    this.#reconcile.activate();
+    this.#syncFromChildren();
+    this.#checkedObserver.observe(this.element, {
+      attributes: true,
+      attributeFilter: ["checked"],
+      subtree: true
+    });
+    this.element.addEventListener("turbo:morph-element", this.#onMorph);
+    document.addEventListener("reset", this.#onReset, true);
+  }
+  /** Releases the observer, global reset listener, and every pending reconciliation. */
+  disconnect() {
+    this.#reconcile.cancel();
+    this.#checkedObserver.disconnect();
+    this.element.removeEventListener("turbo:morph-element", this.#onMorph);
+    document.removeEventListener("reset", this.#onReset, true);
+  }
+  /** Reconciles the aggregate for a parent added or replaced at runtime. */
+  parentTargetConnected() {
+    this.#reconcile.schedule();
+  }
+  /** Reconciles the aggregate after a parent target leaves the group. */
+  parentTargetDisconnected() {
+    this.#reconcile.schedule();
+  }
+  /** Reconciles the aggregate for a child added at runtime. */
+  childTargetConnected() {
+    this.#reconcile.schedule();
+  }
+  /** Reconciles the aggregate after a child leaves the group. */
+  childTargetDisconnected() {
+    this.#reconcile.schedule();
   }
   /** Cascades the parent's state to every child. Bound via `data-action` (change). */
   onParentChange() {
@@ -20,35 +92,74 @@ var CheckboxController = class extends Controller {
     for (const child of this.childTargets) {
       child.checked = checked;
     }
-    this.parentTarget.indeterminate = false;
-    const state = checked ? "all" : "none";
-    this.element.setAttribute("data-state", state);
-    this.dispatch("change", { detail: { checked, indeterminate: false, state } });
+    this.#reflect(checked ? "all" : "none", true);
+    const detail = this.#settledDetail();
+    if (detail) this.dispatch("change", { detail });
   }
   /** Recomputes the parent from its children. Bound via `data-action` (change). */
   onChildChange() {
-    this.#syncFromChildren(true);
+    this.#syncFromChildren();
+    const detail = this.#settledDetail();
+    if (detail) this.dispatch("change", { detail });
+  }
+  /**
+   * Announces an aggregate this pass derived rather than the user. `change` stays
+   * reserved for the two public actions, so automation never reads a repair as an edit.
+   */
+  #reconcileFromChildren() {
+    const previous = this.#committedState;
+    this.#syncFromChildren();
+    if (this.#committedState === previous) return;
+    const detail = this.#settledDetail();
+    if (detail) this.dispatch("reconcile", { detail });
   }
   /**
    * Derives the parent's `checked`/`indeterminate` and the root `data-state` from
-   * the children, optionally dispatching `change`.
+   * the children. Writing state and reporting it are separate so the caller — not
+   * a flag threaded through the write — decides which event describes the cause.
    */
-  #syncFromChildren(dispatch) {
-    const state = this.#aggregate();
-    if (this.hasParentTarget) {
+  #syncFromChildren() {
+    this.#reflect(this.#aggregate(), this.childTargets.length > 0);
+  }
+  /**
+   * Reflects one aggregate state.
+   *
+   * @param writeParent - whether the state is authoritative over the `parent`
+   * target's own `checked` / `indeterminate`.
+   */
+  #reflect(state, writeParent) {
+    if (writeParent && this.hasParentTarget) {
       this.parentTarget.checked = state === "all";
       this.parentTarget.indeterminate = state === "partial";
     }
     this.element.setAttribute("data-state", state);
-    if (dispatch) {
-      this.dispatch("change", {
-        detail: {
-          checked: this.hasParentTarget ? this.parentTarget.checked : state === "all",
-          indeterminate: this.hasParentTarget ? this.parentTarget.indeterminate : false,
-          state
-        }
-      });
-    }
+    this.#committedState = state;
+  }
+  /** The settled aggregate as event detail, or `null` before anything has settled. */
+  #settledDetail() {
+    const state = this.#committedState;
+    if (state === null) return null;
+    return { checked: state === "all", indeterminate: state === "partial", state };
+  }
+  /** Reconciles retained targets after Turbo has finished morphing their live state. */
+  #onMorph = () => {
+    this.#reconcile.schedule();
+  };
+  /** Reconciles after a non-cancelled reset restores any managed checkbox. */
+  #onReset = (event) => {
+    const form = event.target;
+    if (!(form instanceof HTMLFormElement) || !this.#hasCheckboxOwnedBy(form)) return;
+    queueMicrotask(() => {
+      if (!event.defaultPrevented) this.#reconcile.schedule();
+    });
+  };
+  /** Whether a form owns at least one current parent or child target. */
+  #hasCheckboxOwnedBy(form) {
+    return [...this.parentTargets, ...this.childTargets].some((checkbox) => checkbox.form === form);
+  }
+  /** Whether an observed attribute mutation belongs to this controller's target set. */
+  #isManagedCheckbox(node) {
+    return this.parentTargets.some((checkbox) => checkbox === node) || this.childTargets.some((checkbox) => checkbox === node);
   }
   /**
    * Computes the aggregate state. With children it counts them; with none it

data/dist/controllers/color_picker_controller.js

@@ -74,7 +74,7 @@ var ColorPickerController = class extends Controller {
     logicalTrack: { type: Boolean, default: false }
   };
   static actions = ["onHexInput", "onKeydown", "onPointerDown"];
-  static events = ["change"];
+  static events = ["change", "reconcile"];
   /** Whether the consumer declared a mirroring track and the direction mirrors it. */
   get #mirrored() {
     return this.logicalTrackValue && isRtl(this.element);
@@ -83,14 +83,14 @@ var ColorPickerController = class extends Controller {
   #color = { hue: 0, saturation: 0, lightness: 0, alpha: 100 };
   /** Aborts in-progress pointer-drag listeners on drag end / teardown. */
   #dragAbort = null;
-  /** Seeds the model from the initial hex value and renders every surface. */
+  /** Color the last repaint settled on, so a configuration-driven move is reported once. */
+  #committedHex = null;
   /**
    * Collapses a morph that swaps render inputs into one repaint, and refuses the
    * pass Stimulus delivers before `connect()`.
    */
-  #repaint = new MicrotaskCoalescer(() => {
-    this.#render();
-  });
+  #repaint = new MicrotaskCoalescer(() => this.#reconcileColor());
+  /** Seeds the model from the initial hex value and renders every surface. */
   connect() {
     this.#repaint.activate();
     const parsed = hexToHsla(this.valueValue);
@@ -181,12 +181,24 @@ var ColorPickerController = class extends Controller {
       return;
     }
     this.#color = this.alphaValue ? parsed : { ...parsed, alpha: 100 };
-    this.#render();
+    this.#commitColor();
   }
   /** Clamps and snaps one channel to an integer, then re-renders + emits change. */
   #setChannel(channel, raw, min, max) {
     this.#color[channel] = Math.round(Math.min(max, Math.max(min, raw)));
+    this.#commitColor();
+  }
+  /**
+   * Renders the model and reports a color the user actually moved. A key pressed
+   * at a bound, a pointer that lands on the step already showing, and a re-confirmed
+   * hex all leave the committed color where it was, so no `change` describes them.
+   */
+  #commitColor() {
+    const previous = this.#committedHex;
     this.#render();
+    if (this.#committedHex !== previous) {
+      this.dispatch("change", { detail: this.#settledDetail() });
+    }
   }
   /**
    * Reflects the model onto sliders, the hex input, preview, and form field.
@@ -202,14 +214,28 @@ var ColorPickerController = class extends Controller {
       slider.setAttribute("aria-valuetext", valueText(channel, value));
     }
     const hex = this.#hexString();
+    this.#committedHex = hex;
     if (this.hasHexTarget) this.hexTarget.value = hex;
     for (const field of this.fieldTargets) field.value = hex;
     for (const preview of this.previewTargets) preview.style.setProperty(COLOR_PROPERTY, hex);
     this.element.style.setProperty(COLOR_PROPERTY, hex);
+  }
+  /**
+   * Repaints after `alpha` changed at runtime and reports a color this controller
+   * settled on. Disabling alpha drops it from the model, so the committed color can
+   * move without a user edit; `change` stays reserved for the picker's own actions.
+   */
+  #reconcileColor() {
+    const previous = this.#committedHex;
+    this.#render();
+    if (previous !== null && this.#committedHex !== previous) {
+      this.dispatch("reconcile", { detail: this.#settledDetail() });
+    }
+  }
+  /** The settled color as event detail, shared by both report paths. */
+  #settledDetail() {
     const rgb = hslToRgb(this.#color.hue, this.#color.saturation, this.#color.lightness);
-    this.dispatch("change", {
-      detail: { value: hex, rgba: { ...rgb, a: this.#color.alpha / 100 } }
-    });
+    return { value: this.#hexString(), rgba: { ...rgb, a: this.#color.alpha / 100 } };
   }
   /** The current color as `#RRGGBB`, or `#RRGGBBAA` when alpha is enabled. */
   #hexString() {

data/dist/controllers/date_range_picker_controller.js

@@ -18,6 +18,35 @@ function isReservedArrowChord(event, allow = []) {
   return event.altKey && !allow.includes("alt") || event.ctrlKey && !allow.includes("ctrl") || event.metaKey && !allow.includes("meta") || event.shiftKey && !allow.includes("shift");
 }
 
+// src/utils/before_cache_reset.ts
+var BeforeCacheReset = class _BeforeCacheReset {
+  /** Every subscribed instance, iterated by the one shared document listener. */
+  static #subscribers = /* @__PURE__ */ new Set();
+  /** The shared listener; installed while at least one instance is subscribed. */
+  static #onBeforeCache = () => {
+    for (const subscriber of _BeforeCacheReset.#subscribers) subscriber.#rewind();
+  };
+  #rewind;
+  /** @param rewind - the pass that returns this controller's state to its initial form. */
+  constructor(rewind) {
+    this.#rewind = rewind;
+  }
+  /** Subscribes to `turbo:before-cache`; call from `connect()`. Idempotent. */
+  activate() {
+    const first = _BeforeCacheReset.#subscribers.size === 0;
+    _BeforeCacheReset.#subscribers.add(this);
+    if (first) {
+      document.addEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
+    }
+  }
+  /** Unsubscribes; call from `disconnect()`. Safe when never subscribed. */
+  deactivate() {
+    _BeforeCacheReset.#subscribers.delete(this);
+    if (_BeforeCacheReset.#subscribers.size > 0) return;
+    document.removeEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
+  }
+};
+
 // src/utils/dates.ts
 function toISODateString(date) {
   const year = date.getFullYear();
@@ -138,16 +167,34 @@ var SafeTimeout = class extends TimerRegistry {
   }
 };
 
+// src/utils/string_list.ts
+function parseStringList(raw, fallback = []) {
+  const text = raw.trim();
+  if (text.length === 0) return [...fallback];
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return [...fallback];
+  }
+  if (!Array.isArray(parsed)) return [...fallback];
+  return parsed.filter((entry) => typeof entry === "string");
+}
+
 // src/controllers/date_range_picker_controller.ts
 var GRID_SIZE = 42;
 var DateRangePickerController = class extends Controller {
   static targets = ["grid", "monthLabel", "cell", "status", "startField", "endField"];
   static values = {
     min: { type: String, default: "" },
-    max: { type: String, default: "" }
+    max: { type: String, default: "" },
+    // 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: "" }
   };
   static actions = ["applyPreset", "next", "onKeydown", "prev", "previewTo", "selectDate"];
-  static events = ["change"];
+  static events = ["change", "monthchange"];
   /** The month currently rendered, as `YYYY-MM`. */
   #viewMonth = "";
   /** The confirmed range endpoints (ISO), or "" when unset. */
@@ -161,7 +208,12 @@ var DateRangePickerController = class extends Controller {
   #focusedDate = /* @__PURE__ */ new Date();
   /** Deferred focus after an async month transition (cancelled on teardown). */
   #focusTimer = new SafeTimeout();
-  /** Seeds the range from any pre-filled hidden fields and renders the grid. */
+  /** The declared unavailable dates, indexed for the per-cell paint lookup. */
+  #disabledDates = /* @__PURE__ */ new Set();
+  /** Rewinds an unfinished selection before Turbo snapshots the page. */
+  #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
+  /** Last painted month, or `null` until the initial paint has settled. */
+  #announcedMonth = null;
   /**
    * Collapses a morph that swaps render inputs into one repaint, and refuses the
    * pass Stimulus delivers before `connect()`.
@@ -169,10 +221,17 @@ var DateRangePickerController = class extends Controller {
   #repaint = new MicrotaskCoalescer(() => {
     this.#render();
   });
+  /** Seeds and normalizes the range from optional hidden fields, then paints the grid. */
   connect() {
     this.#repaint.activate();
-    this.#startDate = this.hasStartFieldTarget ? normalizeISO(this.startFieldTarget.value) : "";
-    this.#endDate = this.hasEndFieldTarget ? normalizeISO(this.endFieldTarget.value) : "";
+    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.#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);
@@ -182,6 +241,7 @@ var DateRangePickerController = class extends Controller {
   /** Cancels any pending deferred focus so it never fires on a detached element. */
   disconnect() {
     this.#repaint.cancel();
+    this.#beforeCache.deactivate();
     this.#focusTimer.clearAll();
   }
   /** Repaints when application code (or a Turbo morph) changes `min` at runtime. */
@@ -192,6 +252,11 @@ var DateRangePickerController = class extends Controller {
   maxValueChanged() {
     this.#repaint.schedule();
   }
+  /** Re-indexes the unavailable dates and repaints when the declared set changes. */
+  disabledDatesValueChanged() {
+    this.#disabledDates = new Set(parseStringList(this.disabledDatesValue));
+    this.#repaint.schedule();
+  }
   /** Navigates to the previous month. */
   prev(event) {
     event?.preventDefault();
@@ -207,7 +272,7 @@ var DateRangePickerController = class extends Controller {
     const cell = this.#cellFrom(event.target);
     if (!cell) return;
     const date = cell.getAttribute("data-date");
-    if (!date || cell.getAttribute("aria-disabled") === "true") return;
+    if (!date || !this.#isSelectable(date)) return;
     this.#choose(date);
   }
   /** Previews the range up to a hovered/focused cell while selecting. */
@@ -216,28 +281,27 @@ var DateRangePickerController = class extends Controller {
     if (!cell) return;
     const date = cell.getAttribute("data-date");
     if (!date) return;
+    let shouldRender = false;
     if (event.type.startsWith("focus")) {
       const parsed = parseISODateString(date);
       if (parsed) this.#focusedDate = parsed;
-      if (!this.#pendingStart && cell.getAttribute("tabindex") !== "0") {
-        this.#render();
-      }
+      shouldRender = cell.getAttribute("tabindex") !== "0";
     }
-    if (this.#pendingStart) {
+    if (this.#pendingStart && this.#isSelectable(date) && this.#previewDate !== date) {
       this.#previewDate = date;
-      this.#render();
+      shouldRender = true;
     }
+    if (shouldRender) this.#render();
   }
   /** Applies a named preset (`today` / `last7` / `last30` / `thisMonth`). */
   applyPreset(event) {
     const button = event.target?.closest("[data-range]");
-    const name = button?.getAttribute("data-range");
-    if (!name) return;
-    const range = computePreset(name);
+    const range = computePreset(button?.getAttribute("data-range") ?? "");
     if (!range) return;
-    const start = this.#clampISO(range.start);
-    const end = this.#clampISO(range.end);
-    if (!start || !end) return;
+    const intersection = this.#intersectRange(range);
+    if (!intersection) return;
+    const { start, end } = intersection;
+    if (!this.#isSelectable(start) || !this.#isSelectable(end)) return;
     this.#startDate = start;
     this.#endDate = end;
     this.#pendingStart = "";
@@ -255,12 +319,12 @@ var DateRangePickerController = class extends Controller {
     if (isReservedArrowChord(event)) return;
     const cell = this.#cellFrom(event.target);
     if (!cell) return;
-    const dateStr = cell.getAttribute("data-date");
-    const date = dateStr ? parseISODateString(dateStr) : null;
+    const dateStr = cell.getAttribute("data-date") ?? "";
+    const date = parseISODateString(dateStr);
     if (!date) return;
     if (event.key === "Enter" || event.key === " ") {
       event.preventDefault();
-      if (dateStr && cell.getAttribute("aria-disabled") !== "true") this.#choose(dateStr);
+      if (this.#isSelectable(dateStr)) this.#choose(dateStr);
       return;
     }
     if (event.key === "Escape") {
@@ -293,10 +357,10 @@ var DateRangePickerController = class extends Controller {
         next = addDays(date, 6 - date.getDay());
         break;
       case "PageUp":
-        next = shiftMonthClamped(date, -1);
+        next = event.shiftKey ? shiftYearClamped(date, -1) : shiftMonthClamped(date, -1);
         break;
       case "PageDown":
-        next = shiftMonthClamped(date, 1);
+        next = event.shiftKey ? shiftYearClamped(date, 1) : shiftMonthClamped(date, 1);
         break;
       default:
         return;
@@ -327,12 +391,14 @@ var DateRangePickerController = class extends Controller {
   /** Moves roving focus to `date`, transitioning the month when needed. */
   #moveFocusTo(date) {
     this.#focusedDate = date;
-    if (this.#pendingStart) this.#previewDate = toISODateString(date);
-    this.#transitionTo(toISOMonthString(date), toISODateString(date));
+    const iso = toISODateString(date);
+    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) {
     const isTransition = month !== this.#viewMonth;
+    this.#focusTimer.clearAll();
     this.#viewMonth = month;
     this.#render();
     const focusCell = () => {
@@ -364,17 +430,19 @@ var DateRangePickerController = class extends Controller {
     const info = parseISOMonthString(this.#viewMonth);
     if (!info) return;
     const { year, month } = info;
+    if (this.#previewDate && !this.#isSelectable(this.#previewDate)) this.#previewDate = "";
     if (this.hasMonthLabelTarget) {
       const lang = document.documentElement.lang || "en";
-      const formatter = new Intl.DateTimeFormat(lang, { month: "long", year: "numeric" });
+      const formatter = monthFormatter(lang);
       this.monthLabelTarget.textContent = formatter.format(new Date(year, month - 1, 1));
     }
     const [rangeStart, rangeEnd] = this.#visualRange();
     const days = gridDays(year, month);
     const focusedStr = toISODateString(this.#focusedDate);
     const todayStr = toISODateString(/* @__PURE__ */ new Date());
+    const cells = this.cellTargets;
     for (let i = 0; i < GRID_SIZE; i++) {
-      const el = this.cellTargets[i];
+      const el = cells[i];
       const date = days[i];
       if (!el || !date) continue;
       const iso = toISODateString(date);
@@ -383,8 +451,8 @@ var DateRangePickerController = class extends Controller {
       el.setAttribute("data-outside", String(date.getMonth() !== month - 1));
       el.setAttribute("data-today", String(iso === todayStr));
       el.setAttribute("tabindex", iso === focusedStr ? "0" : "-1");
-      if (this.#outOfBounds(iso)) el.setAttribute("aria-disabled", "true");
-      else el.removeAttribute("aria-disabled");
+      if (this.#isSelectable(iso)) el.removeAttribute("aria-disabled");
+      else el.setAttribute("aria-disabled", "true");
       const isStart = !!rangeStart && iso === rangeStart;
       const isEnd = !!rangeEnd && iso === rangeEnd && rangeEnd !== rangeStart;
       const inside = !!rangeStart && !!rangeEnd && iso > rangeStart && iso < rangeEnd;
@@ -398,6 +466,16 @@ var DateRangePickerController = class extends Controller {
         )
       );
     }
+    for (const extra of cells.slice(GRID_SIZE)) extra.setAttribute("tabindex", "-1");
+    if (!cells.some((cell) => cell.getAttribute("tabindex") === "0")) {
+      const fallback = cells.find((cell) => cell.getAttribute("data-outside") === "false") ?? cells[0];
+      fallback?.setAttribute("tabindex", "0");
+    }
+    const previous = this.#announcedMonth;
+    this.#announcedMonth = this.#viewMonth;
+    if (previous !== null && previous !== this.#viewMonth) {
+      this.dispatch("monthchange", { detail: { month: this.#viewMonth } });
+    }
   }
   /** The ordered [start, end] pair to paint: the preview while selecting, else confirmed. */
   #visualRange() {
@@ -418,15 +496,25 @@ var DateRangePickerController = class extends Controller {
       this.statusTarget.textContent = `${this.#startDate} \u2013 ${this.#endDate}`;
     }
   }
+  /**
+   * True when `iso` may be chosen as a range endpoint.
+   *
+   * The single availability question in the controller: the grid paint, the
+   * preview, and both commit paths ask it, so a cell's `aria-disabled` and what
+   * a click on that cell does are the same decision rather than two that have to
+   * be kept in step.
+   */
+  #isSelectable(iso) {
+    return !this.#outOfBounds(iso) && !this.#disabledDates.has(iso);
+  }
   /** True when `iso` falls outside the `[min, max]` bounds. */
   #outOfBounds(iso) {
     if (this.minValue && iso < this.minValue) return true;
     if (this.maxValue && iso > this.maxValue) return true;
     return false;
   }
-  /** Clamps an ISO date string into `[min, max]`, or "" when unparseable. */
+  /** Clamps a generated ISO date string into `[min, max]`. */
   #clampISO(iso) {
-    if (!iso) return "";
     if (this.minValue && iso < this.minValue) return this.minValue;
     if (this.maxValue && iso > this.maxValue) return this.maxValue;
     return iso;
@@ -436,6 +524,27 @@ var DateRangePickerController = class extends Controller {
     const clamped = this.#clampISO(toISODateString(date));
     return parseISODateString(clamped);
   }
+  /**
+   * Intersects a preset with `[min, max]`, rejecting a disjoint interval.
+   *
+   * Only the bounds narrow a preset here: `disabledDates` excludes single days,
+   * not sub-intervals, so it cannot shrink one to a still-contiguous range. A
+   * day it excludes is still refused as an endpoint — the caller checks that —
+   * but a preset that merely spans one keeps its span.
+   */
+  #intersectRange(range) {
+    const start = this.minValue && range.start < this.minValue ? this.minValue : range.start;
+    const end = this.maxValue && range.end > this.maxValue ? this.maxValue : range.end;
+    return start <= end ? { start, end } : null;
+  }
+  /** Removes provisional range state before Turbo freezes a cached snapshot. */
+  #rewindForCache() {
+    this.#focusTimer.clearAll();
+    if (!this.#pendingStart && !this.#previewDate) return;
+    this.#pendingStart = "";
+    this.#previewDate = "";
+    this.#render();
+  }
   /** Resolves the cell element from an event target, or null. */
   #cellFrom(target) {
     return target?.closest(
@@ -454,6 +563,12 @@ function shiftMonthClamped(date, delta) {
   target.setDate(Math.min(date.getDate(), lastDay));
   return target;
 }
+function shiftYearClamped(date, delta) {
+  const target = new Date(date.getFullYear() + delta, date.getMonth(), 1);
+  const lastDay = new Date(target.getFullYear(), target.getMonth() + 1, 0).getDate();
+  target.setDate(Math.min(date.getDate(), lastDay));
+  return target;
+}
 function gridDays(year, month) {
   const first = new Date(year, month - 1, 1);
   const start = new Date(first);
@@ -470,6 +585,18 @@ function normalizeISO(value) {
   const date = parseISODateString(value.trim());
   return date ? toISODateString(date) : "";
 }
+function orderRange(start, end) {
+  return start && end && end < start ? [end, start] : [start, end];
+}
+function monthFormatter(locale) {
+  const options = { month: "long", year: "numeric" };
+  try {
+    return new Intl.DateTimeFormat(locale, options);
+  } catch (error) {
+    if (!(error instanceof RangeError)) throw error;
+    return new Intl.DateTimeFormat("en", options);
+  }
+}
 function computePreset(name) {
   const today = /* @__PURE__ */ new Date();
   const todayStr = toISODateString(today);