stimeo-ui 0.15.0 → 0.17.0

package/dist/controllers/time_picker_controller.d.ts

@@ -22,6 +22,12 @@ import { Controller } from '@hotwired/stimulus';
  *
  * `reconcile` dispatches `{ value: string }`.
  *
+ * All published state is settled before its reports. A synchronous listener
+ * that confirms another value leaves that newer confirmation to report itself;
+ * reports still pending for the replaced value are not sent. A read-only listener
+ * or a confirmation that moves no published value leaves pending reports intact.
+ * An event already being dispatched still reaches its remaining listeners.
+ *
  * @remarks
  * `segment` targets declare the spinbuttons; the optional `field` target receives
  * the composed form value. `hourCycle` selects 12- or 24-hour presentation
@@ -36,7 +42,8 @@ import { Controller } from '@hotwired/stimulus';
  * step the focused spinbutton; wrapping seconds or minutes carries into the next
  * unit, and 12-hour stepping crosses AM/PM at noon and midnight. Typing digits
  * enters a value directly and advances after completion. The digit buffer is
- * discarded on another action, target replacement, or focus departure.
+ * discarded on another action, a segment target change, a page write taken in
+ * from a segment, or focus departure.
  *
  * A user action that changes the composed value dispatches exactly one bubbling
  * native `change` from the field, when present, and one
@@ -69,6 +76,16 @@ declare class TimePickerController extends Controller<HTMLElement> {
             default: boolean;
         };
     };
+    static valueConstraints: {
+        hourCycle: {
+            finite: true;
+            allowedValues: number[];
+        };
+        step: {
+            readonly finite: true;
+            readonly exclusiveMin: 0;
+        };
+    };
     static actions: readonly ["onKeydown"];
     static events: readonly ["change", "reconcile"];
     readonly segmentTargets: HTMLElement[];

package/dist/controllers/time_picker_controller.js

@@ -1,13 +1,9 @@
 import { Controller } from '@hotwired/stimulus';
 
-// src/controllers/time_picker_controller.ts
-
-// 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;
@@ -18,27 +14,42 @@ 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
+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 }));
+}
+
+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 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;
@@ -51,14 +62,100 @@ var MicrotaskCoalescer = class {
   }
 };
 
-// src/controllers/time_picker_controller.ts
+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();
+  }
+  disconnect() {
+    this.#listeners.dispose();
+    this.#pass.cancel();
+    this.#element = null;
+  }
+};
+
+var MoveCounter = class {
+  #sequence = 0;
+  record() {
+    this.#sequence += 1;
+    return this.#sequence;
+  }
+  isLatest(token) {
+    return token === this.#sequence;
+  }
+};
+
+var NUMBER_BOUNDS = {
+  positive: { finite: true, exclusiveMin: 0 }};
+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}"]`;
+}
+
 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 {
+var TimePickerController = class _TimePickerController extends Controller {
+  #numbers = new NumberValueReader();
+  #moves = new MoveCounter();
+  #move = 0;
   static targets = ["segment", "field"];
   static values = {
     hourCycle: { type: Number, default: 24 },
@@ -66,34 +163,32 @@ var TimePickerController = class extends Controller {
     seconds: { type: Boolean, default: false },
     wrap: { type: Boolean, default: true }
   };
+  static valueConstraints = {
+    hourCycle: { finite: true, allowedValues: [12, 24] },
+    step: NUMBER_BOUNDS.positive
+  };
   static actions = ["onKeydown"];
   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. */
+  #reconcile = new MorphRenderWatcher(() => this.#reconcileDom());
   #state = { hour: 0, minute: 0, second: 0 };
-  /** Direct-entry digit buffer and the segment it belongs to. */
   #typeBuffer = "";
   #typeSegment = null;
-  /** Last composed value, used to suppress duplicate user notifications. */
   #lastValue = "";
   #observer = null;
   #connected = false;
   #domDirty = false;
-  /** Seeds state from the DOM, renders canonical ARIA, and starts morph observation. */
   connect() {
     this.#connected = true;
-    this.#reconcile.activate();
+    this.#reconcile.observe(this.element);
     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.#reconcile.disconnect();
     this.element.removeEventListener("focusout", this.#onFocusOut);
     this.#observer?.disconnect();
     this.#observer = null;
@@ -101,45 +196,37 @@ var TimePickerController = class extends Controller {
     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 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']"
+      targetSelector(this.identifier, "segment")
     );
     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;
+    if (this.#adoptPendingDom()) this.#reconcile.schedule();
     switch (key) {
       case "ArrowUp":
         event.preventDefault();
@@ -177,21 +264,18 @@ var TimePickerController = class extends Controller {
     }
     this.#clearTypeBuffer();
   }
-  /** 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']"
+      targetSelector(this.identifier, "segment")
     );
     if (!segment || !this.segmentTargets.includes(segment)) return;
     this.#clearTypeBuffer();
   };
-  /** Uses the normalized positive-integer minute step; other segments step by one. */
   #delta(kind) {
     if (kind !== "minute") return 1;
-    const step = Math.trunc(this.stepValue);
-    return Number.isFinite(step) && step > 0 ? step : 1;
+    const step = Math.trunc(this.#safeStep);
+    return step > 0 ? step : 1;
   }
-  /** Mutates one complete action and then renders/notifies its final value once. */
   #step(kind, delta) {
     if (kind === "meridiem" && this.wrapValue) {
       this.#state.hour = modulo(this.#state.hour + 12, 24);
@@ -207,7 +291,6 @@ var TimePickerController = class extends Controller {
     }
     this.#commitRender();
   }
-  /** Accumulates a typed digit, rendering once and advancing after completion. */
   #typeDigit(segment, kind, digit) {
     if (this.#typeSegment !== kind) this.#typeBuffer = "";
     this.#typeSegment = kind;
@@ -221,27 +304,30 @@ var TimePickerController = class extends Controller {
       this.#focusSibling(segment, 1);
     }
   }
-  /** Moves focus to the previous/next valid segment, if one exists. */
   #focusSibling(segment, direction) {
     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();
+  #adoptPendingDom() {
+    const pending = this.#observer?.takeRecords() ?? [];
+    if (pending.some(({ target }) => this.segmentTargets.includes(target))) {
+      this.#domDirty = true;
     }
+    if (!this.#domDirty) return false;
+    this.#domDirty = false;
+    this.#clearTypeBuffer();
+    this.#adoptDomState();
+    return true;
+  }
+  #reconcileDom() {
+    this.#adoptPendingDom();
     this.#render();
   }
-  /** Rebuilds canonical state from the targets; an absent hour represents midnight. */
   #adoptDomState() {
     let displayedHour = 0;
     let meridiem = AM;
@@ -257,51 +343,39 @@ var TimePickerController = class extends Controller {
       else meridiem = value;
     }
     this.#state = {
-      hour: this.hourCycleValue === 12 ? displayedHour % 12 + (meridiem === PM ? 12 : 0) : displayedHour,
+      hour: this.#safeHourCycle === 12 ? displayedHour % 12 + (meridiem === PM ? 12 : 0) : displayedHour,
       minute,
       second
     };
   }
-  /** 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;
+      this.#state.hour = this.#safeHourCycle === 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;
@@ -309,19 +383,21 @@ var TimePickerController = class extends Controller {
     this.#writeField(value);
     this.#lastValue = value;
     if (previous !== "" && value !== previous) {
+      this.#move = this.#moves.record();
       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 } });
+    const changed = value !== this.#lastValue;
     this.#lastValue = value;
+    if (changed) this.#move = this.#moves.record();
+    const move = this.#move;
+    if (this.#writeField(value)) commitField(this.fieldTarget);
+    if (!this.#moves.isLatest(move)) return;
+    if (changed) this.dispatch("change", { detail: { value } });
   }
-  /** Reflects one segment's value and controller-owned ARIA bounds/text. */
   #renderSegment(segment) {
     const kind = this.#kindOf(segment);
     if (!kind) return;
@@ -334,31 +410,25 @@ var TimePickerController = class extends Controller {
     segment.setAttribute("aria-valuemax", String(max));
     segment.textContent = text;
   }
-  /** 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;
+    return this.hasFieldTarget && writeField(this.fieldTarget, value);
   }
-  /** 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));
     return parts.join(":");
   }
-  /** 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;
+      return this.#safeHourCycle === 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 controller-owned bounds for a segment kind. */
   #bounds(kind) {
     switch (kind) {
       case "hour":
-        return this.hourCycleValue === 12 ? { min: 1, max: 12 } : { min: 0, max: 23 };
+        return this.#safeHourCycle === 12 ? { min: 1, max: 12 } : { min: 0, max: 23 };
       case "minute":
       case "second":
         return { min: 0, max: 59 };
@@ -366,7 +436,6 @@ 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(
@@ -374,13 +443,11 @@ var TimePickerController = class extends Controller {
       );
       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,
@@ -388,7 +455,6 @@ var TimePickerController = class extends Controller {
       attributeFilter: ["aria-valuenow", "data-segment"]
     });
   }
-  /** Temporarily pauses observation so derived ARIA writes cannot become DOM input. */
   #withoutObservation(run) {
     const observer = this.#observer;
     observer?.disconnect();
@@ -398,7 +464,6 @@ var TimePickerController = class extends Controller {
       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");
     if (kind === "hour" || kind === "minute" || kind === "second" || kind === "meridiem") {
@@ -406,10 +471,27 @@ 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;
   }
+  get #safeHourCycle() {
+    return this.#numbers.read(
+      this,
+      "hourCycle",
+      this.hourCycleValue,
+      _TimePickerController.values.hourCycle.default,
+      _TimePickerController.valueConstraints.hourCycle
+    );
+  }
+  get #safeStep() {
+    return this.#numbers.read(
+      this,
+      "step",
+      this.stepValue,
+      _TimePickerController.values.step.default,
+      _TimePickerController.valueConstraints.step
+    );
+  }
 };
 function modulo(value, modulus) {
   return (value % modulus + modulus) % modulus;
@@ -419,5 +501,4 @@ function pad(value) {
 }
 
 export { TimePickerController };
-//# sourceMappingURL=time_picker_controller.js.map
 //# sourceMappingURL=time_picker_controller.js.map