stimeo-ui 0.5.0 → 0.7.0

package/dist/controllers/number_input_controller.js

@@ -8,6 +8,123 @@ 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/attribute_lease.ts
+var AttributeLease = class {
+  #attribute;
+  #records = /* @__PURE__ */ new Map();
+  /** @param attribute - The attribute whose temporary values this lease owns. */
+  constructor(attribute) {
+    this.#attribute = attribute;
+  }
+  /** Writes or removes the leased attribute while preserving its authored value. */
+  write(element, value) {
+    const existing = this.#records.get(element);
+    if (existing) {
+      existing.written = value;
+    } else {
+      this.#records.set(element, {
+        original: element.getAttribute(this.#attribute),
+        written: value
+      });
+    }
+    this.#reflect(element, value);
+  }
+  /** Returns one lease without overwriting a value subsequently authored by a consumer. */
+  return(element) {
+    const record = this.#records.get(element);
+    if (!record) return;
+    this.#records.delete(element);
+    const stillOwned = element.getAttribute(this.#attribute) === record.written;
+    if (stillOwned) this.#reflect(element, record.original);
+  }
+  /** Reflects only a real value transition, avoiding self-triggered mutation work. */
+  #reflect(element, value) {
+    if (element.getAttribute(this.#attribute) === value) return;
+    if (value === null) element.removeAttribute(this.#attribute);
+    else element.setAttribute(this.#attribute, value);
+  }
+  /** Returns every outstanding lease using the same ownership check as {@link return}. */
+  returnAll() {
+    for (const element of Array.from(this.#records.keys())) this.return(element);
+  }
+};
+
+// 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/composition_tracker.ts
+var CompositionTracker = class {
+  #observedTargets = /* @__PURE__ */ new Set();
+  #activeTargets = /* @__PURE__ */ new Set();
+  #onStart;
+  #onEnd;
+  constructor(options = {}) {
+    this.#onStart = options.onStart;
+    this.#onEnd = options.onEnd;
+  }
+  /** Starts lifecycle tracking for `target`; repeated calls are idempotent. */
+  observe(target) {
+    if (this.#observedTargets.has(target)) return;
+    target.addEventListener("compositionstart", this.#handleStart);
+    target.addEventListener("compositionend", this.#handleEnd);
+    this.#observedTargets.add(target);
+  }
+  /** Stops tracking one target and clears any active composition it owned. */
+  unobserve(target) {
+    if (!this.#observedTargets.delete(target)) return;
+    target.removeEventListener("compositionstart", this.#handleStart);
+    target.removeEventListener("compositionend", this.#handleEnd);
+    this.#activeTargets.delete(target);
+  }
+  /** Releases every listener and clears state so reconnect starts cleanly. */
+  disconnect() {
+    for (const target of this.#observedTargets) {
+      target.removeEventListener("compositionstart", this.#handleStart);
+      target.removeEventListener("compositionend", this.#handleEnd);
+    }
+    this.#observedTargets.clear();
+    this.#activeTargets.clear();
+  }
+  /** True when lifecycle tracking or the current event reports composition. */
+  isComposing(event) {
+    return this.#activeTargets.size > 0 || event?.isComposing === true;
+  }
+  #handleStart = (event) => {
+    if (event.currentTarget) this.#activeTargets.add(event.currentTarget);
+    this.#onStart?.(event);
+  };
+  #handleEnd = (event) => {
+    if (event.currentTarget) this.#activeTargets.delete(event.currentTarget);
+    this.#onEnd?.(event);
+  };
+};
+
 // src/utils/microtask_coalescer.ts
 var MicrotaskCoalescer = class {
   #run;
@@ -215,6 +332,7 @@ function finiteFallback(min, max) {
 }
 
 // src/controllers/number_input_controller.ts
+var OWNED_DISABLED = "data-number-input-disabled";
 var NumberInputController = class _NumberInputController extends Controller {
   static targets = ["input", "increment", "decrement"];
   static values = {
@@ -224,7 +342,7 @@ var NumberInputController = class _NumberInputController extends Controller {
     pageStep: { type: Number, default: 0 }
   };
   static actions = ["decrement", "increment", "onInput", "onKeydown"];
-  static events = ["change"];
+  static events = ["change", "reconcile"];
   /** Delay (ms) a button must be held before auto-repeat starts. */
   static #HOLD_DELAY_MS = 400;
   /** Interval (ms) between auto-repeat steps once a hold has started. */
@@ -236,8 +354,19 @@ var NumberInputController = class _NumberInputController extends Controller {
    * of poisoning the next legitimate click.
    */
   static #SUPPRESS_RESET_MS = 250;
-  /** Aborts the pointer listeners on disconnect so none outlive the element. */
-  #guards = null;
+  /** Aborts global pointer guards on disconnect so none outlive the element. */
+  #globalGuards = null;
+  /** Per-target guards allow an old button to be released without touching its replacement. */
+  #buttonGuards = /* @__PURE__ */ new Map();
+  /** Tracks IME lifecycle on the current input, including confirming keys without a signal. */
+  #composition = new CompositionTracker();
+  /** Restores authored custom-spinbutton ARIA when a target leaves or the controller stops. */
+  #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
+  #ariaValueNow = new AttributeLease("aria-valuenow");
+  #ariaValueMin = new AttributeLease("aria-valuemin");
+  #ariaValueMax = new AttributeLease("aria-valuemax");
+  /** Last reconciled or user-committed numeric value. */
+  #lastValue = null;
   /** Timers for the hold delay and the suppress-reset safety net. */
   #holdTimeouts = new SafeTimeout();
   /** The running auto-repeat interval (one at a time). */
@@ -248,63 +377,122 @@ var NumberInputController = class _NumberInputController extends Controller {
   #repeatedDuringHold = false;
   /** True when the next `click` is the trailing one after a hold and must be ignored. */
   #suppressNextClick = false;
-  /** Collapses runtime range/step changes into one silent input reconciliation. */
+  /** Button and pointer that own the current hold, so other instances/pointers cannot end it. */
+  #holdButton = null;
+  #holdPointerId = null;
+  /** Collapses runtime range/step changes into one input reconciliation. */
   #repaint = new MicrotaskCoalescer(() => this.#reconcile());
   /** Normalizes any initial value and wires the focus/hold pointer guards. */
   connect() {
     this.#repaint.activate();
-    if (!this.hasInputTarget) return;
+    this.#beforeCache.activate();
+    this.#globalGuards = new AbortController();
+    const { signal } = this.#globalGuards;
+    for (const button of this.incrementTargets) this.#wireButton(button, 1);
+    for (const button of this.decrementTargets) this.#wireButton(button, -1);
+    window.addEventListener("pointerup", this.#onPointerEnd, { signal });
+    window.addEventListener("pointercancel", this.#onPointerEnd, { signal });
+    window.addEventListener("blur", this.#onWindowBlur, { signal });
     this.#reconcile();
-    this.#guards = new AbortController();
-    const { signal } = this.#guards;
-    if (this.hasIncrementTarget) this.#wireButton(this.incrementTarget, 1, signal);
-    if (this.hasDecrementTarget) this.#wireButton(this.decrementTarget, -1, signal);
-    window.addEventListener("pointerup", this.#stopHold, { signal });
-    window.addEventListener("pointercancel", this.#stopHold, { signal });
-    window.addEventListener("blur", this.#stopHold, { signal });
-  }
-  /** Releases the pointer guards and tears down every pending timer and hold state. */
+  }
+  /** Releases listeners, derived attributes, timers, and transient value state. */
   disconnect() {
     this.#repaint.cancel();
-    this.#guards?.abort();
-    this.#guards = null;
-    this.#holdActive = false;
+    this.#composition.disconnect();
+    this.#beforeCache.deactivate();
+    this.#globalGuards?.abort();
+    this.#globalGuards = null;
+    const buttons = /* @__PURE__ */ new Set([
+      ...this.#buttonGuards.keys(),
+      ...this.incrementTargets,
+      ...this.decrementTargets
+    ]);
+    for (const guard of this.#buttonGuards.values()) guard.abort();
+    this.#buttonGuards.clear();
+    for (const button of buttons) this.#releaseButtonState(button);
+    this.#stopHold(false);
     this.#repeatedDuringHold = false;
     this.#suppressNextClick = false;
     this.#holdTimeouts.clearAll();
     this.#holdIntervals.clearAll();
+    this.#ariaValueNow.returnAll();
+    this.#ariaValueMin.returnAll();
+    this.#ariaValueMax.returnAll();
+    this.#lastValue = null;
   }
-  /** Silently reconciles a minimum changed by application code or a Turbo morph. */
+  /** Reconciles the value against a minimum changed by application code or a Turbo morph. */
   minValueChanged() {
     this.#repaint.schedule();
   }
-  /** Silently reconciles a maximum changed by application code or a Turbo morph. */
+  /** Reconciles the value against a maximum changed by application code or a Turbo morph. */
   maxValueChanged() {
     this.#repaint.schedule();
   }
-  /** Silently reconciles a step changed by application code or a Turbo morph. */
+  /** Reconciles the value against a step changed by application code or a Turbo morph. */
   stepValueChanged() {
     this.#repaint.schedule();
   }
+  /** Tracks and reconciles an input inserted or replaced at runtime. */
+  inputTargetConnected(input) {
+    this.#composition.observe(input);
+    this.#repaint.schedule();
+  }
+  /** Releases ARIA and composition state owned by an input that left the controller. */
+  inputTargetDisconnected(input) {
+    this.#composition.unobserve(input);
+    this.#releaseInputAria(input);
+    this.#stopHold(false);
+    this.#lastValue = null;
+    this.#repaint.schedule();
+  }
+  /** Wires focus preservation and hold behavior on a runtime increment target. */
+  incrementTargetConnected(button) {
+    this.#wireButton(button, 1);
+    this.#repaint.schedule();
+  }
+  /** Releases only the increment target that actually disconnected. */
+  incrementTargetDisconnected(button) {
+    this.#unwireButton(button);
+    this.#repaint.schedule();
+  }
+  /** Wires focus preservation and hold behavior on a runtime decrement target. */
+  decrementTargetConnected(button) {
+    this.#wireButton(button, -1);
+    this.#repaint.schedule();
+  }
+  /** Releases only the decrement target that actually disconnected. */
+  decrementTargetDisconnected(button) {
+    this.#unwireButton(button);
+    this.#repaint.schedule();
+  }
   /** Increases by one step. Bound via `data-action` (click). */
   increment() {
     if (this.#consumeSuppressedClick()) return;
+    if (!this.hasInputTarget) return;
     this.#commitStep(1);
     this.inputTarget.focus();
   }
   /** Decreases by one step. Bound via `data-action` (click). */
   decrement() {
     if (this.#consumeSuppressedClick()) return;
+    if (!this.hasInputTarget) return;
     this.#commitStep(-1);
     this.inputTarget.focus();
   }
   /** Clamps and snaps a typed value. Bound via `data-action` (change). */
   onInput() {
-    if (this.inputTarget.value.trim() === "") return;
+    if (!this.hasInputTarget) return;
+    if (this.inputTarget.value.trim() === "") {
+      this.#lastValue = null;
+      this.#reflectEmpty();
+      return;
+    }
     this.#commit(this.#currentValue());
   }
   /** Keyboard stepping per the APG spinbutton model. */
   onKeydown(event) {
+    if (!this.hasInputTarget) return;
+    if (this.#composition.isComposing(event)) return;
     if (isReservedArrowChord(event)) return;
     let next = null;
     switch (event.key) {
@@ -339,21 +527,39 @@ var NumberInputController = class _NumberInputController extends Controller {
    * hold; leaving the button while held stops it (the global listeners cover
    * release/cancel/blur).
    */
-  #wireButton(button, direction, signal) {
+  #wireButton(button, direction) {
+    if (this.#buttonGuards.has(button)) return;
+    const guard = new AbortController();
+    this.#buttonGuards.set(button, guard);
     button.addEventListener("pointerdown", (event) => this.#armHold(event, button, direction), {
-      signal
+      signal: guard.signal
     });
-    button.addEventListener("pointerleave", this.#stopHold, { signal });
+    button.addEventListener(
+      "pointerleave",
+      (event) => {
+        if (this.#holdButton === button && this.#ownsPointer(event)) this.#stopHold();
+      },
+      { signal: guard.signal }
+    );
+  }
+  /** Aborts one target's listeners and returns any state derived onto that button. */
+  #unwireButton(button) {
+    this.#buttonGuards.get(button)?.abort();
+    this.#buttonGuards.delete(button);
+    if (this.#holdButton === button) this.#stopHold(false);
+    this.#releaseButtonState(button);
   }
   /** Starts a hold: focus the input, then schedule the first repeat after a delay. */
   #armHold(event, button, direction) {
     const pointerButton = event.button;
     if (typeof pointerButton === "number" && pointerButton !== 0) return;
-    if (button.disabled) return;
+    if (button.disabled || !this.hasInputTarget) return;
     event.preventDefault();
     this.inputTarget.focus();
-    this.#stopHold();
+    this.#stopHold(false);
     this.#holdActive = true;
+    this.#holdButton = button;
+    this.#holdPointerId = this.#pointerId(event);
     this.#repeatedDuringHold = false;
     this.#suppressNextClick = false;
     this.#holdTimeouts.set(() => {
@@ -372,18 +578,39 @@ var NumberInputController = class _NumberInputController extends Controller {
    * trailing synthetic `click` must be ignored, so it is suppressed until the
    * click consumes it or a short safety-net timeout clears it.
    */
-  #stopHold = () => {
+  #stopHold(suppressTrailingClick = true) {
     if (!this.#holdActive) return;
     this.#holdActive = false;
+    this.#holdButton = null;
+    this.#holdPointerId = null;
     this.#holdTimeouts.clearAll();
     this.#holdIntervals.clearAll();
-    if (this.#repeatedDuringHold) {
+    if (suppressTrailingClick && this.#repeatedDuringHold) {
       this.#suppressNextClick = true;
       this.#holdTimeouts.set(() => {
         this.#suppressNextClick = false;
       }, _NumberInputController.#SUPPRESS_RESET_MS);
+    } else if (!suppressTrailingClick) {
+      this.#suppressNextClick = false;
     }
+  }
+  /** Ends a hold only for its initiating pointer (legacy/synthetic events remain accepted). */
+  #onPointerEnd = (event) => {
+    if (this.#ownsPointer(event)) this.#stopHold();
+  };
+  /** Window deactivation is global and always ends the active hold. */
+  #onWindowBlur = () => {
+    this.#stopHold();
   };
+  /** Extracts pointer identity when the runtime event exposes it. */
+  #pointerId(event) {
+    return event.pointerId ?? null;
+  }
+  /** Whether `event` belongs to the active pointer, with a synthetic-event fallback. */
+  #ownsPointer(event) {
+    const pointerId = this.#pointerId(event);
+    return this.#holdActive && (this.#holdPointerId === null || pointerId === null || pointerId === this.#holdPointerId);
+  }
   /** Consumes a pending trailing-click suppression; returns true if the click was swallowed. */
   #consumeSuppressedClick() {
     if (!this.#suppressNextClick) return false;
@@ -392,53 +619,80 @@ var NumberInputController = class _NumberInputController extends Controller {
     return true;
   }
   /**
-   * Normalizes `raw`, reflects it, and dispatches `change` only when the
-   * displayed value actually changes.
+   * Normalizes `raw`, reflects it, and dispatches `{ value: number }` only when
+   * the committed numeric value differs from the last reconciled value.
    *
    * @returns Whether the value changed (drives the auto-repeat's bound stop).
    */
   #commit(raw) {
     const value = this.#normalize(raw);
-    const changed = this.inputTarget.value !== String(value);
+    const changed = this.#lastValue === null || value !== this.#lastValue;
     this.#write(value);
+    this.#lastValue = value;
     if (changed) this.dispatch("change", { detail: { value } });
     return changed;
   }
   /** Commits an adjacent endpoint/grid value and reports whether it moved. */
   #commitStep(count) {
+    if (!this.hasInputTarget) return false;
     return this.#commit(stepSteppedValue(this.#currentValue(), count, this.#steppedRange));
   }
   /**
-   * Silently reflects the current value after a range or step morph.
+   * Reflects the current value after a range or step morph, reporting a moved
+   * value as `reconcile`.
    *
    * @stimeoRenderRoot
    */
   #reconcile() {
-    if (!this.hasInputTarget) return;
+    if (!this.hasInputTarget) {
+      this.#lastValue = null;
+      return;
+    }
     if (this.inputTarget.value.trim() !== "") {
-      this.#write(this.#normalize(this.#currentValue()));
+      const previous = this.#lastValue;
+      const value = this.#normalize(this.#currentValue());
+      this.#write(value);
+      this.#lastValue = value;
+      if (previous !== null && value !== previous) {
+        this.dispatch("reconcile", { detail: { value } });
+      }
     } else {
-      this.#updateButtons(this.#currentValue());
+      this.#lastValue = null;
+      this.#reflectEmpty();
     }
   }
   /** Reflects `value` on the input (and ARIA for non-native hosts) and the buttons. */
   #write(value) {
-    this.inputTarget.value = String(value);
-    if (this.inputTarget.getAttribute("role") === "spinbutton") {
-      this.inputTarget.setAttribute("aria-valuenow", String(value));
-      if (Number.isFinite(this.minValue)) {
-        this.inputTarget.setAttribute("aria-valuemin", String(this.minValue));
-      }
-      if (Number.isFinite(this.maxValue)) {
-        this.inputTarget.setAttribute("aria-valuemax", String(this.maxValue));
-      }
-    }
+    const input = this.inputTarget;
+    input.value = String(value);
+    this.#syncInputAria(input, value);
     this.#updateButtons(value);
   }
+  /** Reflects a blank value without inventing a numeric `aria-valuenow`. */
+  #reflectEmpty() {
+    this.#syncInputAria(this.inputTarget, null);
+    this.#updateButtons(this.#currentValue());
+  }
+  /** Synchronizes controller-derived ARIA while preserving authored teardown values. */
+  #syncInputAria(input, value) {
+    if (input.getAttribute("role") !== "spinbutton") {
+      this.#releaseInputAria(input);
+      return;
+    }
+    this.#ariaValueNow.write(input, value === null ? null : String(value));
+    this.#ariaValueMin.write(input, Number.isFinite(this.minValue) ? String(this.minValue) : null);
+    this.#ariaValueMax.write(input, Number.isFinite(this.maxValue) ? String(this.maxValue) : null);
+  }
+  /** Returns all custom-spinbutton ARIA leased on `input`. */
+  #releaseInputAria(input) {
+    this.#ariaValueNow.return(input);
+    this.#ariaValueMin.return(input);
+    this.#ariaValueMax.return(input);
+  }
   /** Disables a step button at its bound, returning focus to the input first. */
   #updateButtons(value) {
-    if (this.hasIncrementTarget) this.#toggleButton(this.incrementTarget, value < this.maxValue);
-    if (this.hasDecrementTarget) this.#toggleButton(this.decrementTarget, value > this.minValue);
+    for (const button of this.incrementTargets) this.#toggleButton(button, value < this.maxValue);
+    for (const button of this.decrementTargets) this.#toggleButton(button, value > this.minValue);
   }
   /**
    * Enables or disables a step button at its bound, never disabling one while it
@@ -448,16 +702,22 @@ var NumberInputController = class _NumberInputController extends Controller {
    */
   #toggleButton(button, enabled) {
     if (enabled) {
-      if (button.hasAttribute("data-number-input-disabled")) {
+      if (button.hasAttribute(OWNED_DISABLED)) {
         button.disabled = false;
-        button.removeAttribute("data-number-input-disabled");
+        button.removeAttribute(OWNED_DISABLED);
       }
       return;
     }
     if (button.disabled) return;
-    if (document.activeElement === button) this.inputTarget.focus();
+    if (document.activeElement === button && this.hasInputTarget) this.inputTarget.focus();
     button.disabled = true;
-    button.setAttribute("data-number-input-disabled", "");
+    button.setAttribute(OWNED_DISABLED, "");
+  }
+  /** Returns `disabled` only when its explicit marker still identifies controller ownership. */
+  #releaseButtonState(button) {
+    if (!button.hasAttribute(OWNED_DISABLED)) return;
+    button.disabled = false;
+    button.removeAttribute(OWNED_DISABLED);
   }
   /** The current numeric value, falling back to a finite min (else 0) when blank. */
   #currentValue() {
@@ -473,6 +733,12 @@ var NumberInputController = class _NumberInputController extends Controller {
   get #steppedRange() {
     return { min: this.minValue, max: this.maxValue, step: this.stepValue };
   }
+  /** Returns borrowed range ARIA before Turbo snapshots the page. */
+  #rewindForCache() {
+    this.#ariaValueNow.returnAll();
+    this.#ariaValueMin.returnAll();
+    this.#ariaValueMax.returnAll();
+  }
 };
 
 export { NumberInputController };