stimeo-ui 0.5.0 → 0.7.0

package/dist/controllers/time_picker_controller.js

@@ -18,9 +18,46 @@ 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/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/time_picker_controller.ts
 var AM = 0;
 var PM = 1;
+var SECONDS_PER_MINUTE = 60;
+var SECONDS_PER_HOUR = 60 * SECONDS_PER_MINUTE;
+var SECONDS_PER_DAY = 24 * SECONDS_PER_HOUR;
+var hasModifier = (event) => event.altKey || event.ctrlKey || event.metaKey || event.shiftKey;
 var TimePickerController = class extends Controller {
   static targets = ["segment", "field"];
   static values = {
@@ -30,35 +67,80 @@ var TimePickerController = class extends Controller {
     wrap: { type: Boolean, default: true }
   };
   static actions = ["onKeydown"];
-  static events = ["change"];
-  /** Current numeric value per segment kind (hours are the *displayed* hours). */
-  #state = { hour: 0, minute: 0, second: 0, meridiem: AM };
+  static events = ["change", "reconcile"];
+  /** Collapses target, Value, and retained-attribute morphs into one silent render. */
+  #reconcile = new MicrotaskCoalescer(() => this.#reconcileDom());
+  /** Canonical state; the displayed hour and meridiem are derived from this value. */
+  #state = { hour: 0, minute: 0, second: 0 };
   /** Direct-entry digit buffer and the segment it belongs to. */
   #typeBuffer = "";
   #typeSegment = null;
-  /** Last composed field value, to suppress duplicate `change` dispatches. */
+  /** Last composed value, used to suppress duplicate user notifications. */
   #lastValue = "";
-  /** Seeds each segment from its initial `aria-valuenow` and syncs the field. */
+  #observer = null;
+  #connected = false;
+  #domDirty = false;
+  /** Seeds state from the DOM, renders canonical ARIA, and starts morph observation. */
   connect() {
-    for (const segment of this.segmentTargets) {
-      const kind = this.#kindOf(segment);
-      if (!kind) continue;
-      const now = Number(segment.getAttribute("aria-valuenow"));
-      const { min, max } = this.#bounds(kind);
-      this.#state[kind] = Number.isFinite(now) ? Math.min(max, Math.max(min, now)) : min;
-    }
-    for (const segment of this.segmentTargets) this.#renderSegment(segment);
-    this.#syncField(false);
+    this.#connected = true;
+    this.#reconcile.activate();
+    this.element.addEventListener("focusout", this.#onFocusOut);
+    this.#domDirty = false;
+    this.#adoptDomState();
+    this.#render();
+    this.#observeMutations();
+  }
+  /** Releases the observer, listener, queued reconciliation, and transient input state. */
+  disconnect() {
+    this.#connected = false;
+    this.#reconcile.cancel();
+    this.element.removeEventListener("focusout", this.#onFocusOut);
+    this.#observer?.disconnect();
+    this.#observer = null;
+    this.#domDirty = false;
+    this.#clearTypeBuffer();
+    this.#lastValue = "";
+  }
+  /** Re-renders the canonical instant when 12/24-hour presentation changes at runtime. */
+  hourCycleValueChanged() {
+    this.#reconcile.schedule();
+  }
+  /** Recomposes the optional seconds portion after a runtime Value change. */
+  secondsValueChanged() {
+    this.#reconcile.schedule();
+  }
+  /** Adopts a segment inserted or replaced by a Turbo morph. */
+  segmentTargetConnected() {
+    this.#domDirty = true;
+    this.#clearTypeBuffer();
+    this.#reconcile.schedule();
+  }
+  /** Rebuilds state after a segment leaves the retained controller element. */
+  segmentTargetDisconnected() {
+    this.#domDirty = true;
+    this.#clearTypeBuffer();
+    this.#reconcile.schedule();
+  }
+  /** Reflects the current composed value into a field added or replaced at runtime. */
+  fieldTargetConnected() {
+    this.#reconcile.schedule();
+  }
+  /** Reconciles silently when the optional field leaves at runtime. */
+  fieldTargetDisconnected() {
+    this.#reconcile.schedule();
   }
-  /** Handles stepping, inter-segment focus moves, jumps, and direct entry. */
+  /** Handles APG stepping, inter-segment focus moves, jumps, and direct entry. */
   onKeydown(event) {
     if (isReservedArrowChord(event)) return;
     const segment = event.target?.closest(
-      "[data-stimeo--time-picker-target='segment']"
+      "[data-stimeo--time-picker-target~='segment']"
     );
-    const kind = segment ? this.#kindOf(segment) : null;
-    if (!segment || !kind) return;
-    switch (logicalArrowKey(event.key, this.element)) {
+    if (!segment || !this.segmentTargets.includes(segment)) return;
+    const kind = this.#kindOf(segment);
+    if (!kind) return;
+    const key = logicalArrowKey(event.key, this.element);
+    if ((key === "Home" || key === "End") && hasModifier(event)) return;
+    switch (key) {
       case "ArrowUp":
         event.preventDefault();
         this.#step(kind, this.#delta(kind));
@@ -77,134 +159,202 @@ var TimePickerController = class extends Controller {
         break;
       case "Home":
         event.preventDefault();
-        this.#set(kind, this.#bounds(kind).min);
+        this.#setDisplayed(kind, this.#bounds(kind).min);
+        this.#commitRender();
         break;
       case "End":
         event.preventDefault();
-        this.#set(kind, this.#bounds(kind).max);
+        this.#setDisplayed(kind, this.#bounds(kind).max);
+        this.#commitRender();
         break;
       default:
-        if (/^[0-9]$/.test(event.key)) {
+        if (kind !== "meridiem" && /^[0-9]$/.test(event.key) && !hasModifier(event)) {
           event.preventDefault();
           this.#typeDigit(segment, kind, event.key);
+          return;
         }
         return;
     }
-    this.#typeBuffer = "";
-    this.#typeSegment = null;
+    this.#clearTypeBuffer();
   }
-  /** The per-step delta: minutes step by `step`, others by 1, meridiem toggles. */
+  /** Clears direct-entry state when Tab, Shift+Tab, or pointer focus leaves a segment. */
+  #onFocusOut = (event) => {
+    const segment = event.target?.closest(
+      "[data-stimeo--time-picker-target~='segment']"
+    );
+    if (!segment || !this.segmentTargets.includes(segment)) return;
+    this.#clearTypeBuffer();
+  };
+  /** Uses the normalized positive-integer minute step; other segments step by one. */
   #delta(kind) {
-    return kind === "minute" ? this.stepValue : 1;
+    if (kind !== "minute") return 1;
+    const step = Math.trunc(this.stepValue);
+    return Number.isFinite(step) && step > 0 ? step : 1;
   }
-  /** Steps a segment, wrapping at its bounds and carrying over when enabled. */
+  /** Mutates one complete action and then renders/notifies its final value once. */
   #step(kind, delta) {
-    if (kind === "meridiem") {
-      this.#set("meridiem", this.#state.meridiem === AM ? PM : AM);
-      return;
-    }
-    const { min, max } = this.#bounds(kind);
-    const span = max - min + 1;
-    const raw = this.#state[kind] + delta;
-    if (raw > max || raw < min) {
-      if (!this.wrapValue) {
-        this.#set(kind, Math.min(max, Math.max(min, raw)));
-        return;
-      }
-      const wrapped = ((raw - min) % span + span) % span + min;
-      const carry = Math.floor((raw - min) / span);
-      this.#set(kind, wrapped);
-      this.#carry(kind, carry);
-      return;
+    if (kind === "meridiem" && this.wrapValue) {
+      this.#state.hour = modulo(this.#state.hour + 12, 24);
+    } else if (this.wrapValue) {
+      const scale = kind === "hour" ? SECONDS_PER_HOUR : kind === "minute" ? SECONDS_PER_MINUTE : 1;
+      this.#setFromSeconds(this.#secondsOfDay + delta * scale);
+    } else if (kind === "hour") {
+      this.#state.hour = Math.min(23, Math.max(0, this.#state.hour + delta));
+    } else {
+      const { min, max } = this.#bounds(kind);
+      const displayed = this.#displayValue(kind);
+      this.#setDisplayed(kind, Math.min(max, Math.max(min, displayed + delta)));
     }
-    this.#set(kind, raw);
-  }
-  /** Propagates a wrap carry from `kind` into the next larger segment. */
-  #carry(kind, amount) {
-    if (kind === "second") this.#step("minute", amount);
-    else if (kind === "minute") this.#step("hour", amount);
-  }
-  /**
-   * Sets a segment's value (clamped to its `[min, max]` bounds), re-renders it,
-   * and resyncs the composed field. Clamping here guards the direct-entry path:
-   * typing `0` into a 12-hour hour (min 1) must not commit an out-of-range
-   * `aria-valuenow="0"`. The stepping path already passes in-bounds values, so
-   * the clamp is a no-op there.
-   */
-  #set(kind, value) {
-    const { min, max } = this.#bounds(kind);
-    this.#state[kind] = Math.min(max, Math.max(min, value));
-    const segment = this.segmentTargets.find((s) => this.#kindOf(s) === kind);
-    if (segment) this.#renderSegment(segment);
-    this.#syncField(true);
+    this.#commitRender();
   }
-  /** Accumulates a typed digit, committing and advancing after two digits. */
+  /** Accumulates a typed digit, rendering once and advancing after completion. */
   #typeDigit(segment, kind, digit) {
-    if (kind === "meridiem") return;
     if (this.#typeSegment !== kind) this.#typeBuffer = "";
     this.#typeSegment = kind;
     const { max } = this.#bounds(kind);
     const candidate = Number(`${this.#typeBuffer}${digit}`);
-    if (candidate <= max) this.#typeBuffer = `${this.#typeBuffer}${digit}`;
-    else this.#typeBuffer = digit;
-    this.#set(kind, Number(this.#typeBuffer));
+    this.#typeBuffer = candidate <= max ? `${this.#typeBuffer}${digit}` : digit;
+    this.#setDisplayed(kind, Number(this.#typeBuffer));
+    this.#commitRender();
     if (this.#typeBuffer.length >= 2 || Number(this.#typeBuffer) * 10 > max) {
-      this.#typeBuffer = "";
-      this.#typeSegment = null;
+      this.#clearTypeBuffer();
       this.#focusSibling(segment, 1);
     }
   }
-  /** Moves focus to the previous/next segment, if one exists. */
+  /** Moves focus to the previous/next valid segment, if one exists. */
   #focusSibling(segment, direction) {
-    const index = this.segmentTargets.indexOf(segment);
-    const next = this.segmentTargets[index + direction];
-    next?.focus();
+    const segments = this.segmentTargets.filter((candidate) => this.#kindOf(candidate) !== null);
+    const index = segments.indexOf(segment);
+    segments[index + direction]?.focus();
+  }
+  /** Clears the direct-entry buffer and its owning segment together. */
+  #clearTypeBuffer() {
+    this.#typeBuffer = "";
+    this.#typeSegment = null;
+  }
+  /** Reconciles one coalesced target, Value, or retained-attribute mutation batch. */
+  #reconcileDom() {
+    if (this.#domDirty) {
+      this.#domDirty = false;
+      this.#clearTypeBuffer();
+      this.#adoptDomState();
+    }
+    this.#render();
+  }
+  /** Rebuilds canonical state from the targets; an absent hour represents midnight. */
+  #adoptDomState() {
+    let displayedHour = 0;
+    let meridiem = AM;
+    let minute = 0;
+    let second = 0;
+    for (const segment of this.segmentTargets) {
+      const kind = this.#kindOf(segment);
+      if (!kind) continue;
+      const value = this.#authoredValue(segment, kind);
+      if (kind === "hour") displayedHour = value;
+      else if (kind === "minute") minute = value;
+      else if (kind === "second") second = value;
+      else meridiem = value;
+    }
+    this.#state = {
+      hour: this.hourCycleValue === 12 ? displayedHour % 12 + (meridiem === PM ? 12 : 0) : displayedHour,
+      minute,
+      second
+    };
   }
-  /** Reflects a segment's current value onto its ARIA/text representation. */
+  /** Reads and integer-clamps one authored `aria-valuenow`. */
+  #authoredValue(segment, kind) {
+    const raw = Number(segment.getAttribute("aria-valuenow"));
+    const { min, max } = this.#bounds(kind);
+    if (!Number.isFinite(raw)) return min;
+    return Math.min(max, Math.max(min, Math.trunc(raw)));
+  }
+  /** Writes a displayed segment value back into canonical state without rendering. */
+  #setDisplayed(kind, raw) {
+    const { min, max } = this.#bounds(kind);
+    const value = Math.min(max, Math.max(min, Math.trunc(raw)));
+    if (kind === "hour") {
+      this.#state.hour = this.hourCycleValue === 12 ? value % 12 + (this.#state.hour >= 12 ? 12 : 0) : value;
+    } else if (kind === "minute" || kind === "second") {
+      this.#state[kind] = value;
+    } else {
+      this.#state.hour = this.#state.hour % 12 + (value === PM ? 12 : 0);
+    }
+  }
+  /** Converts seconds with day wrapping into the canonical three-unit state. */
+  #setFromSeconds(raw) {
+    const seconds = modulo(raw, SECONDS_PER_DAY);
+    this.#state.hour = Math.floor(seconds / SECONDS_PER_HOUR);
+    this.#state.minute = Math.floor(seconds % SECONDS_PER_HOUR / SECONDS_PER_MINUTE);
+    this.#state.second = seconds % SECONDS_PER_MINUTE;
+  }
+  /** Reflects canonical state to every segment without dispatching user events. */
+  #renderSegments() {
+    this.#withoutObservation(() => {
+      for (const segment of this.segmentTargets) this.#renderSegment(segment);
+    });
+  }
+  /**
+   * Reflects canonical state during connection or DOM reconciliation.
+   *
+   * No user edit reaches here, so `change` never fires from this path. A pass
+   * that moves the committed value reports `reconcile` instead.
+   *
+   * @stimeoRenderRoot
+   */
+  #render() {
+    this.#renderSegments();
+    const value = this.#composedValue;
+    const previous = this.#lastValue;
+    this.#writeField(value);
+    this.#lastValue = value;
+    if (previous !== "" && value !== previous) {
+      this.dispatch("reconcile", { detail: { value } });
+    }
+  }
+  /** Reflects one completed user action and dispatches its final change exactly once. */
+  #commitRender() {
+    this.#renderSegments();
+    const value = this.#composedValue;
+    const fieldChanged = this.#writeField(value);
+    if (fieldChanged) this.fieldTarget.dispatchEvent(new Event("change", { bubbles: true }));
+    if (value !== this.#lastValue) this.dispatch("change", { detail: { value } });
+    this.#lastValue = value;
+  }
+  /** Reflects one segment's value and controller-owned ARIA bounds/text. */
   #renderSegment(segment) {
     const kind = this.#kindOf(segment);
     if (!kind) return;
-    const value = this.#state[kind];
-    if (kind === "meridiem") {
-      const text2 = value === PM ? "PM" : "AM";
-      segment.setAttribute("aria-valuenow", String(value));
-      segment.setAttribute("aria-valuetext", text2);
-      segment.setAttribute("aria-valuemin", String(AM));
-      segment.setAttribute("aria-valuemax", String(PM));
-      segment.textContent = text2;
-      return;
-    }
+    const value = this.#displayValue(kind);
+    const text = kind === "meridiem" ? value === PM ? "PM" : "AM" : pad(value);
     const { min, max } = this.#bounds(kind);
-    const text = String(value).padStart(2, "0");
     segment.setAttribute("aria-valuenow", String(value));
     segment.setAttribute("aria-valuetext", text);
     segment.setAttribute("aria-valuemin", String(min));
     segment.setAttribute("aria-valuemax", String(max));
     segment.textContent = text;
   }
-  /** Composes `HH:MM[:SS]` and notifies both native-form and widget consumers. */
-  #syncField(notify) {
-    const h24 = this.#hours24();
-    const parts = [pad(h24), pad(this.#state.minute)];
+  /** Writes a composed value to the optional form field and reports whether it changed. */
+  #writeField(value) {
+    if (!this.hasFieldTarget || this.fieldTarget.value === value) return false;
+    this.fieldTarget.value = value;
+    return true;
+  }
+  /** The canonical form value composed as `HH:MM[:SS]`. */
+  get #composedValue() {
+    const parts = [pad(this.#state.hour), pad(this.#state.minute)];
     if (this.secondsValue) parts.push(pad(this.#state.second));
-    const value = parts.join(":");
-    const fieldChanged = this.hasFieldTarget && this.fieldTarget.value !== value;
-    if (fieldChanged) {
-      this.fieldTarget.value = value;
-    }
-    if (notify && fieldChanged) {
-      this.fieldTarget.dispatchEvent(new Event("change", { bubbles: true }));
-    }
-    if (notify && value !== this.#lastValue) this.dispatch("change", { detail: { value } });
-    this.#lastValue = value;
+    return parts.join(":");
   }
-  /** Converts the displayed hour (+ meridiem in 12-hour mode) to 24-hour. */
-  #hours24() {
-    if (this.hourCycleValue !== 12) return this.#state.hour;
-    const base = this.#state.hour % 12;
-    return base + (this.#state.meridiem === PM ? 12 : 0);
+  /** Returns a canonical unit in the presentation form exposed by its segment. */
+  #displayValue(kind) {
+    if (kind === "hour") {
+      return this.hourCycleValue === 12 ? this.#state.hour % 12 || 12 : this.#state.hour;
+    }
+    if (kind === "meridiem") return this.#state.hour >= 12 ? PM : AM;
+    return this.#state[kind];
   }
-  /** The inclusive `[min, max]` bounds for a segment kind. */
+  /** The inclusive controller-owned bounds for a segment kind. */
   #bounds(kind) {
     switch (kind) {
       case "hour":
@@ -216,6 +366,38 @@ var TimePickerController = class extends Controller {
         return { min: AM, max: PM };
     }
   }
+  /** Watches retained segment state while excluding this controller's own reflections. */
+  #observeMutations() {
+    const observer = new MutationObserver((records) => {
+      const changed = records.some(
+        ({ target }) => target instanceof HTMLElement && this.segmentTargets.includes(target)
+      );
+      if (!changed) return;
+      this.#domDirty = true;
+      this.#clearTypeBuffer();
+      this.#reconcile.schedule();
+    });
+    this.#observer = observer;
+    this.#observeWith(observer);
+  }
+  /** Registers retained attribute observation on the controller subtree. */
+  #observeWith(observer) {
+    observer.observe(this.element, {
+      subtree: true,
+      attributes: true,
+      attributeFilter: ["aria-valuenow", "data-segment"]
+    });
+  }
+  /** Temporarily pauses observation so derived ARIA writes cannot become DOM input. */
+  #withoutObservation(run) {
+    const observer = this.#observer;
+    observer?.disconnect();
+    try {
+      run();
+    } finally {
+      if (observer && this.#connected) this.#observeWith(observer);
+    }
+  }
   /** Reads a segment's declared kind, or null when absent/invalid. */
   #kindOf(segment) {
     const kind = segment.getAttribute("data-segment");
@@ -224,7 +406,14 @@ var TimePickerController = class extends Controller {
     }
     return null;
   }
+  /** Canonical state as seconds since the start of its nominal day. */
+  get #secondsOfDay() {
+    return this.#state.hour * SECONDS_PER_HOUR + this.#state.minute * SECONDS_PER_MINUTE + this.#state.second;
+  }
 };
+function modulo(value, modulus) {
+  return (value % modulus + modulus) % modulus;
+}
 function pad(value) {
   return String(value).padStart(2, "0");
 }