stimeo-ui 0.4.0 → 0.5.0

data/dist/controllers/form_validation_controller.js

@@ -2,6 +2,13 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/form_validation_controller.ts
 
+// src/utils/default_attribute.ts
+function setDefaultAttribute(element, name, value) {
+  if (element.hasAttribute(name)) return false;
+  element.setAttribute(name, value);
+  return true;
+}
+
 // src/utils/focus_trap.ts
 var FOCUSABLE = 'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
 
@@ -79,8 +86,7 @@ var FormValidationController = class _FormValidationController extends Controlle
   };
   /** Suppresses native bubbles and binds the submit / blur / input listeners. */
   connect() {
-    if (!this.element.hasAttribute("novalidate")) {
-      this.element.setAttribute("novalidate", "");
+    if (setDefaultAttribute(this.element, "novalidate", "")) {
       this.element.setAttribute(_FormValidationController.#NOVALIDATE_MARKER, "");
     }
     document.addEventListener("submit", this.#onSubmit, true);

data/dist/controllers/frame_loading_controller.js

@@ -52,6 +52,16 @@ var BeforeCacheReset = class _BeforeCacheReset {
 var DetachGate = class _DetachGate {
   /** Set while a probe is queued, waiting for a reconnect to cancel it. */
   #pending = false;
+  /**
+   * True while a probe is queued — the last disconnect was ambiguous and no
+   * reconnect has cancelled it yet. Read it from `connect()` to tell the
+   * reconnect half of an in-page move from a first connect: a controller whose
+   * initialisation restarts a measurement (a min-duration floor, an elapsed
+   * counter) must skip it for the move, where nothing actually restarted.
+   */
+  get pending() {
+    return this.#pending;
+  }
   /**
    * True when the disconnect is definitely a real detach — the element left
    * the document, or `data-controller` no longer lists the identifier. False
@@ -209,7 +219,17 @@ var FrameLoadingController = class extends Controller {
   #gate = new DetachGate();
   #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
   #loading = false;
-  #inertApplied = false;
+  /**
+   * The optional targets this controller revealed, and the content it marked inert.
+   * Held as references rather than re-resolved on the way out: a detach that keeps
+   * the element takes the identifier off `data-controller` first, and a scope
+   * without its identifier stops resolving targets — the elements to tidy would be
+   * unreachable exactly when the tidying matters. They double as the ownership
+   * marker, so a `hidden` or an `inert` the consumer wrote is never taken over.
+   */
+  #revealedSkeleton = null;
+  #revealedOverlay = null;
+  #inertTarget = null;
   #previousFocus = null;
   /** The id of the retreated element, used to re-find it if the load replaced it. */
   #previousFocusId = "";
@@ -236,40 +256,97 @@ var FrameLoadingController = class extends Controller {
     this.#gate.disconnected(this, () => this.#teardown());
   }
   /**
-   * Drops the held finish and the loading bookkeeping on a real detach. The markup
-   * keeps whatever it last held: the page being cached is rewound at
-   * `turbo:before-cache` instead, where the frame is still whole.
+   * Drops the held finish and the loading bookkeeping on a real detach, returning
+   * the frame to its idle form. No reconnect is coming, so nothing is left that
+   * could finish the load and clear the hooks — a detach that keeps the element
+   * (a morph dropping the identifier, an exit from a scoped observed root) would
+   * otherwise strand it busy and inert. Focus is left where it is: the element is
+   * leaving this controller's care, and moving it now would be an unexplained jump.
    */
   #teardown() {
     this.#gate.cancel();
     this.#timeouts.clearAll();
     this.#floor.cancel();
+    if (this.#loading) this.#rewindHooks();
     this.#loading = false;
     this.#previousFocus = null;
   }
   /**
-   * Returns the frame to its resting hooks for the snapshot Turbo is about to
-   * take, so a page reached with the Back button does not restore a frame that is
-   * busy and inert with nothing left to finish it. State only — no `end` event and
-   * no focus move, because the load did not actually complete. The live page keeps
-   * its held finish, so a navigation that never completes still ends properly.
+   * Returns the frame to its idle form for the snapshot Turbo is about to take, so
+   * a page reached with the Back button does not restore a frame that is busy and
+   * inert with nothing left to finish it. State only — no `end` event and no focus
+   * move, because the load did not actually complete.
+   *
+   * The load is abandoned rather than paused, so the flag and any finish the floor
+   * still holds drop along with the hooks. A kept finish would surface after the
+   * rewind as exactly the three things this pass exists to avoid — an `end`, a
+   * completion announcement, and a focus move — and a kept flag would leave the
+   * next fetch on a page that survives a cancelled visit skipping the loading
+   * state, its idempotence guard already satisfied.
    */
   #rewindForCache() {
     if (!this.#loading) return;
+    this.#loading = false;
+    this.#floor.cancel();
+    this.#rewindHooks();
+  }
+  /**
+   * Clears every hook the loading state writes. Shared by the three ways a load can
+   * stop — completion, detach, snapshot — so none of them can drift into tidying
+   * only part of it.
+   */
+  #rewindHooks() {
     this.element.removeAttribute("aria-busy");
     this.element.removeAttribute("data-frame-loading");
-    if (this.hasSkeletonTarget) this.skeletonTarget.hidden = true;
-    if (this.hasOverlayTarget) this.overlayTarget.hidden = true;
+    if (this.#revealedSkeleton) this.#revealedSkeleton.hidden = true;
+    if (this.#revealedOverlay) this.#revealedOverlay.hidden = true;
+    this.#revealedSkeleton = null;
+    this.#revealedOverlay = null;
     this.#clearInert();
   }
+  /**
+   * Re-shows a `skeleton` that arrived mid-load. Turbo's frame renderer empties the
+   * frame and re-inserts the response's children, so a response's authored (hidden)
+   * skeleton can land while a later fetch is still running, and only the controller
+   * knows the frame is still busy.
+   */
+  skeletonTargetConnected() {
+    if (this.#loading) this.#revealSkeleton();
+  }
+  /** Re-shows an `overlay` that arrived mid-load — the same swap as the skeleton. */
+  overlayTargetConnected() {
+    if (this.#loading) this.#revealOverlay();
+  }
+  /**
+   * Re-blocks a `content` that arrived mid-load, so the stale copy stays unusable.
+   * The element that left is released first and ownership is then decided afresh, so
+   * an `inert` the replacement authored stays the consumer's.
+   */
+  contentTargetConnected() {
+    if (!this.#loading) return;
+    this.#clearInert();
+    this.#applyInert();
+  }
+  /** Reveals the optional `skeleton`, noting it as this controller's to hide again. */
+  #revealSkeleton() {
+    if (!this.hasSkeletonTarget) return;
+    this.#revealedSkeleton = this.skeletonTarget;
+    this.skeletonTarget.hidden = false;
+  }
+  /** Reveals the optional `overlay`, noting it as this controller's to hide again. */
+  #revealOverlay() {
+    if (!this.hasOverlayTarget) return;
+    this.#revealedOverlay = this.overlayTarget;
+    this.overlayTarget.hidden = false;
+  }
   /** Enters the loading state: hooks, skeleton/overlay, inert content, focus retreat. */
   #begin() {
     this.#loading = true;
     this.#floor.begin();
     this.element.setAttribute("aria-busy", "true");
     this.element.setAttribute("data-frame-loading", "true");
-    if (this.hasSkeletonTarget) this.skeletonTarget.hidden = false;
-    if (this.hasOverlayTarget) this.overlayTarget.hidden = false;
+    this.#revealSkeleton();
+    this.#revealOverlay();
     this.#applyInert();
     this.#retreatFocus();
     this.dispatch("start", { detail: {} });
@@ -278,11 +355,7 @@ var FrameLoadingController = class extends Controller {
   /** Leaves the loading state: restore hooks, hide skeleton/overlay, restore focus. */
   #finish() {
     this.#loading = false;
-    this.element.removeAttribute("aria-busy");
-    this.element.removeAttribute("data-frame-loading");
-    if (this.hasSkeletonTarget) this.skeletonTarget.hidden = true;
-    if (this.hasOverlayTarget) this.overlayTarget.hidden = true;
-    this.#clearInert();
+    this.#rewindHooks();
     this.#restoreFocus();
     this.dispatch("end", { detail: {} });
     announce(fillTemplate(this.announceReadyTextValue, {}));
@@ -291,12 +364,11 @@ var FrameLoadingController = class extends Controller {
   #applyInert() {
     if (!this.hasContentTarget || this.contentTarget.hasAttribute("inert")) return;
     this.contentTarget.setAttribute("inert", "");
-    this.#inertApplied = true;
+    this.#inertTarget = this.contentTarget;
   }
   #clearInert() {
-    if (!this.#inertApplied) return;
-    this.#inertApplied = false;
-    if (this.hasContentTarget) this.contentTarget.removeAttribute("inert");
+    this.#inertTarget?.removeAttribute("inert");
+    this.#inertTarget = null;
   }
   /** Saves and blurs focus if it sits inside the frame about to go stale. */
   #retreatFocus() {

data/dist/controllers/highlight_controller.js

@@ -61,6 +61,7 @@ var SafeTimeout = class extends TimerRegistry {
 };
 
 // src/controllers/highlight_controller.ts
+var hookOwners = /* @__PURE__ */ new WeakMap();
 var HighlightController = class extends Controller {
   static values = {
     duration: { type: Number, default: 1500 },
@@ -68,9 +69,18 @@ var HighlightController = class extends Controller {
   };
   static events = ["start", "end"];
   #timeouts = new SafeTimeout();
+  /**
+   * The removal timer this connection has outstanding for an element. Held weakly so
+   * a row that leaves the DOM is not retained, and dropped wholesale on `disconnect()`
+   * so a cleared id can never be matched against a recycled one. Which connection owns
+   * an element's hook is answered by the shared owner registry above.
+   */
+  #pending = /* @__PURE__ */ new WeakMap();
   #observer = null;
   connect() {
+    this.#clearArrivedHook(this.element);
     if (this.observeValue) {
+      for (const child of this.element.children) this.#clearArrivedHook(child);
       if (typeof MutationObserver !== "undefined") {
         this.#observer = new MutationObserver((mutations) => this.#onMutations(mutations));
         this.#observer.observe(this.element, { childList: true });
@@ -83,6 +93,12 @@ var HighlightController = class extends Controller {
     this.#observer?.disconnect();
     this.#observer = null;
     this.#timeouts.clearAll();
+    this.#pending = /* @__PURE__ */ new WeakMap();
+  }
+  /** Drops a hook that arrived with the DOM, along with this connection's claim on it. */
+  #clearArrivedHook(el) {
+    if (hookOwners.get(el) === this) hookOwners.delete(el);
+    el.removeAttribute("data-highlight");
   }
   /** Highlights every element child added by a childList mutation. */
   #onMutations(mutations) {
@@ -95,12 +111,33 @@ var HighlightController = class extends Controller {
   /** Flags `el` with `data-highlight` and schedules its removal (unless reduced-motion). */
   #highlight(el) {
     if (prefersReducedMotion()) return;
+    this.#releasePending(el);
     el.setAttribute("data-highlight", "true");
     this.dispatch("start", { target: el, detail: { element: el } });
-    this.#timeouts.set(() => {
+    const id = this.#timeouts.set(() => {
+      this.#pending.delete(el);
+      hookOwners.delete(el);
       el.removeAttribute("data-highlight");
       this.dispatch("end", { target: el, detail: { element: el } });
     }, this.durationValue);
+    this.#pending.set(el, id);
+    hookOwners.set(el, this);
+  }
+  /**
+   * Releases whichever removal timer holds `el`'s hook. The row may have been
+   * highlighted inside a different watched container before it moved here, and that
+   * container's timer is reachable only through the shared owner registry.
+   */
+  #releasePending(el) {
+    const owner = hookOwners.get(el);
+    if (owner !== void 0 && owner !== this) owner.#cancelPending(el);
+    this.#cancelPending(el);
+  }
+  /** Releases `el`'s pending removal timer, if it has one. */
+  #cancelPending(el) {
+    this.#timeouts.clear(this.#pending.get(el) ?? -1);
+    this.#pending.delete(el);
+    hookOwners.delete(el);
   }
 };
 

data/dist/controllers/idle_controller.js

@@ -71,6 +71,12 @@ var IdleController = class extends Controller {
   #prompted = false;
   /** Timestamp of the last activity; the timers self-reschedule against it. */
   #lastActivity = 0;
+  /**
+   * Activity types actually registered on `document`, so `disconnect()` unbinds the
+   * same set even when `events` changed while connected (a Turbo morph can rewrite
+   * the Value in place, and the removal must match the registration, not the Value).
+   */
+  #boundEvents = [];
   #onActivity = () => {
     this.#lastActivity = Date.now();
     if (this.#idle || this.#prompted) {
@@ -85,16 +91,21 @@ var IdleController = class extends Controller {
     if (document.visibilityState === "visible") this.#onActivity();
   };
   connect() {
-    for (const type of this.eventsValue) {
+    this.#idle = false;
+    this.#prompted = false;
+    this.element.removeAttribute("data-idle");
+    this.#boundEvents = [...this.eventsValue];
+    for (const type of this.#boundEvents) {
       document.addEventListener(type, this.#onActivity, { passive: true, capture: true });
     }
     document.addEventListener("visibilitychange", this.#onVisibility);
     this.#arm();
   }
   disconnect() {
-    for (const type of this.eventsValue) {
+    for (const type of this.#boundEvents) {
       document.removeEventListener(type, this.#onActivity, { capture: true });
     }
+    this.#boundEvents = [];
     document.removeEventListener("visibilitychange", this.#onVisibility);
     this.#timeouts.clearAll();
   }

data/dist/controllers/local_time_controller.js

@@ -94,6 +94,8 @@ var LocalTimeController = class extends Controller {
    * its condition is that formatting was applied, and a repaint applies it with a
    * new result. A pass that cannot format writes nothing and emits nothing, so the
    * authored absolute text stays as the fallback.
+   *
+   * @stimeoRenderRoot
    */
   #render() {
     const date = this.#parse();

data/dist/controllers/masonry_controller.js

@@ -59,7 +59,7 @@ var LayoutObserver = class {
 };
 
 // src/controllers/masonry_controller.ts
-var COLUMNS_PROPERTY = "--stimeo-masonry-columns";
+var COLUMNS_PROPERTY = "--stimeo--masonry-columns";
 var MasonryController = class extends Controller {
   static targets = ["item"];
   static values = {

data/dist/controllers/meter_controller.js

@@ -173,6 +173,8 @@ var MeterController = class extends Controller {
    * Reflects value/range onto ARIA, the segment onto `data-state`, and the ratio.
    * The reading is derived once and returned, so the `change` detail reports the
    * same numbers the DOM just received.
+   *
+   * @stimeoRenderRoot
    */
   #render() {
     const value = this.#clamp(this.valueValue);
@@ -184,7 +186,7 @@ var MeterController = class extends Controller {
     this.element.setAttribute("aria-valuemin", String(this.minValue));
     this.element.setAttribute("aria-valuemax", String(this.maxValue));
     this.element.setAttribute("aria-valuenow", String(reading.value));
-    this.element.style.setProperty("--stimeo-meter-ratio", String(reading.ratio));
+    this.element.style.setProperty("--stimeo--meter-ratio", String(reading.ratio));
     this.element.setAttribute("data-state", reading.state);
     this.#applyValueText(reading);
     return reading;

data/dist/controllers/network_status_controller.js

@@ -124,9 +124,7 @@ var NetworkStatusController = class extends Controller {
   #showOffline() {
     this.#timers.clearAll();
     if (this.hasOnlineTarget) this.onlineTarget.hidden = true;
-    if (this.hasOfflineTarget) {
-      this.offlineTarget.hidden = false;
-    }
+    if (this.hasOfflineTarget) this.offlineTarget.hidden = false;
   }
   /** Shows the recovery banner, optionally auto-hiding it after `onlineAutoHide`. */
   #showOnline() {

data/dist/controllers/number_input_controller.js

@@ -8,6 +8,39 @@ 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/utils/safe_timeout.ts
 var TimerRegistry = class {
   /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
@@ -75,6 +108,112 @@ var SafeInterval = class extends TimerRegistry {
   }
 };
 
+// src/utils/stepped_value.ts
+function effectiveStep(step) {
+  return Number.isFinite(step) && step > 0 ? step : 1;
+}
+function snapSteppedValue(raw, range) {
+  if (!(range.min <= range.max)) return finiteFallback(range.min, range.max);
+  const input = Number.isNaN(raw) ? finiteFallback(range.min, range.max) : raw;
+  const clamped = Math.min(range.max, Math.max(range.min, input));
+  const step = effectiveStep(range.step);
+  const base = stepBase(range);
+  const candidates = [];
+  if (Number.isFinite(range.min)) candidates.push(range.min);
+  if (Number.isFinite(range.max)) candidates.push(range.max);
+  const gridPosition = (clamped - base) / step;
+  if (Number.isFinite(gridPosition)) {
+    addGridCandidate(candidates, Math.floor(gridPosition), range, base, step);
+    addGridCandidate(candidates, Math.ceil(gridPosition), range, base, step);
+  }
+  if (candidates.length === 0) return clamped;
+  let nearest = candidates[0];
+  let nearestDistance = Math.abs(clamped - nearest);
+  for (const candidate of candidates.slice(1)) {
+    const distance = Math.abs(clamped - candidate);
+    if (distance < nearestDistance || nearlyEqual(distance, nearestDistance) && candidate > nearest) {
+      nearest = candidate;
+      nearestDistance = distance;
+    }
+  }
+  return nearest;
+}
+function stepSteppedValue(current, count, range) {
+  const value = snapSteppedValue(current, range);
+  const distance = Math.abs(Math.trunc(count));
+  if (!Number.isFinite(distance) || distance === 0) return value;
+  const direction = Math.sign(count);
+  const adjacent = adjacentSteppedValue(value, direction, range);
+  const raw = adjacent + direction * (distance - 1) * effectiveStep(range.step);
+  return snapSteppedValue(raw, range);
+}
+function adjacentSteppedValue(current, direction, range) {
+  const step = effectiveStep(range.step);
+  const base = stepBase(range);
+  const candidates = [];
+  if (direction > 0) {
+    const position2 = (current - base) / step;
+    if (Number.isFinite(position2)) {
+      let gridIndex = Math.floor(position2) + 1;
+      let candidate = cleanGridValue(base + gridIndex * step, base, step);
+      if (candidate < current || nearlyEqual(candidate, current)) {
+        gridIndex += 1;
+        candidate = cleanGridValue(base + gridIndex * step, base, step);
+      }
+      if (candidate > current && !nearlyEqual(candidate, current) && within(candidate, range.min, range.max)) {
+        candidates.push(clamp(candidate, range));
+      }
+    }
+    return clamp(Math.min(...candidates), range);
+  }
+  const position = (current - base) / step;
+  if (Number.isFinite(position)) {
+    let gridIndex = Math.ceil(position) - 1;
+    let candidate = cleanGridValue(base + gridIndex * step, base, step);
+    if (candidate > current || nearlyEqual(candidate, current)) {
+      gridIndex -= 1;
+      candidate = cleanGridValue(base + gridIndex * step, base, step);
+    }
+    if (candidate < current && !nearlyEqual(candidate, current) && within(candidate, range.min, range.max)) {
+      candidates.push(clamp(candidate, range));
+    }
+  }
+  return clamp(Math.max(...candidates), range);
+}
+function addGridCandidate(candidates, index, range, base, step) {
+  const candidate = cleanGridValue(base + index * step, base, step);
+  if (within(candidate, range.min, range.max)) candidates.push(clamp(candidate, range));
+}
+function stepBase(range) {
+  if (range.base !== void 0 && Number.isFinite(range.base)) return range.base;
+  return Number.isFinite(range.min) ? range.min : 0;
+}
+function cleanGridValue(value, base, step) {
+  const precision = Math.max(decimalPlaces(base), decimalPlaces(step));
+  return precision <= 100 ? Number(value.toFixed(precision)) : value;
+}
+function decimalPlaces(value) {
+  const [coefficient = "", exponentText] = Math.abs(value).toString().toLowerCase().split("e");
+  const fractionLength = coefficient.split(".")[1]?.length ?? 0;
+  const exponent = exponentText === void 0 ? 0 : Number(exponentText);
+  return Math.max(0, fractionLength - exponent);
+}
+function within(value, min, max) {
+  return (value > min || nearlyEqual(value, min)) && (value < max || nearlyEqual(value, max));
+}
+function clamp(value, range) {
+  return Math.min(range.max, Math.max(range.min, value));
+}
+function nearlyEqual(left, right) {
+  const scale = Math.max(Math.abs(left), Math.abs(right));
+  return Number.isFinite(left) && Number.isFinite(right) && Math.abs(left - right) <= Number.EPSILON * scale;
+}
+function finiteFallback(min, max) {
+  if (Number.isFinite(min)) return min;
+  if (Number.isFinite(max)) return max;
+  return 0;
+}
+
 // src/controllers/number_input_controller.ts
 var NumberInputController = class _NumberInputController extends Controller {
   static targets = ["input", "increment", "decrement"];
@@ -109,24 +248,24 @@ 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. */
+  #repaint = new MicrotaskCoalescer(() => this.#reconcile());
   /** Normalizes any initial value and wires the focus/hold pointer guards. */
   connect() {
+    this.#repaint.activate();
     if (!this.hasInputTarget) return;
-    if (this.inputTarget.value.trim() !== "") {
-      this.#write(this.#normalize(this.#currentValue()));
-    } else {
-      this.#updateButtons(this.#currentValue());
-    }
+    this.#reconcile();
     this.#guards = new AbortController();
     const { signal } = this.#guards;
-    if (this.hasIncrementTarget) this.#wireButton(this.incrementTarget, this.stepValue, signal);
-    if (this.hasDecrementTarget) this.#wireButton(this.decrementTarget, -this.stepValue, signal);
+    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. */
   disconnect() {
+    this.#repaint.cancel();
     this.#guards?.abort();
     this.#guards = null;
     this.#holdActive = false;
@@ -135,16 +274,28 @@ var NumberInputController = class _NumberInputController extends Controller {
     this.#holdTimeouts.clearAll();
     this.#holdIntervals.clearAll();
   }
+  /** Silently reconciles 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. */
+  maxValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Silently reconciles a step changed by application code or a Turbo morph. */
+  stepValueChanged() {
+    this.#repaint.schedule();
+  }
   /** Increases by one step. Bound via `data-action` (click). */
   increment() {
     if (this.#consumeSuppressedClick()) return;
-    this.#commit(this.#currentValue() + this.stepValue);
+    this.#commitStep(1);
     this.inputTarget.focus();
   }
   /** Decreases by one step. Bound via `data-action` (click). */
   decrement() {
     if (this.#consumeSuppressedClick()) return;
-    this.#commit(this.#currentValue() - this.stepValue);
+    this.#commitStep(-1);
     this.inputTarget.focus();
   }
   /** Clamps and snaps a typed value. Bound via `data-action` (change). */
@@ -155,20 +306,19 @@ var NumberInputController = class _NumberInputController extends Controller {
   /** Keyboard stepping per the APG spinbutton model. */
   onKeydown(event) {
     if (isReservedArrowChord(event)) return;
-    const page = this.pageStepValue > 0 ? this.pageStepValue : this.stepValue * 10;
     let next = null;
     switch (event.key) {
       case "ArrowUp":
-        next = this.#currentValue() + this.stepValue;
+        next = stepSteppedValue(this.#currentValue(), 1, this.#steppedRange);
         break;
       case "ArrowDown":
-        next = this.#currentValue() - this.stepValue;
+        next = stepSteppedValue(this.#currentValue(), -1, this.#steppedRange);
         break;
       case "PageUp":
-        next = this.#currentValue() + page;
+        next = this.pageStepValue > 0 ? this.#currentValue() + this.pageStepValue : stepSteppedValue(this.#currentValue(), 10, this.#steppedRange);
         break;
       case "PageDown":
-        next = this.#currentValue() - page;
+        next = this.pageStepValue > 0 ? this.#currentValue() - this.pageStepValue : stepSteppedValue(this.#currentValue(), -10, this.#steppedRange);
         break;
       case "Home":
         if (!Number.isFinite(this.minValue)) return;
@@ -189,14 +339,14 @@ var NumberInputController = class _NumberInputController extends Controller {
    * hold; leaving the button while held stops it (the global listeners cover
    * release/cancel/blur).
    */
-  #wireButton(button, delta, signal) {
-    button.addEventListener("pointerdown", (event) => this.#armHold(event, button, delta), {
+  #wireButton(button, direction, signal) {
+    button.addEventListener("pointerdown", (event) => this.#armHold(event, button, direction), {
       signal
     });
     button.addEventListener("pointerleave", this.#stopHold, { signal });
   }
   /** Starts a hold: focus the input, then schedule the first repeat after a delay. */
-  #armHold(event, button, delta) {
+  #armHold(event, button, direction) {
     const pointerButton = event.button;
     if (typeof pointerButton === "number" && pointerButton !== 0) return;
     if (button.disabled) return;
@@ -207,13 +357,13 @@ var NumberInputController = class _NumberInputController extends Controller {
     this.#repeatedDuringHold = false;
     this.#suppressNextClick = false;
     this.#holdTimeouts.set(() => {
-      if (!this.#commit(this.#currentValue() + delta)) {
+      if (!this.#commitStep(direction)) {
         this.#stopHold();
         return;
       }
       this.#repeatedDuringHold = true;
       this.#holdIntervals.set(() => {
-        if (!this.#commit(this.#currentValue() + delta)) this.#stopHold();
+        if (!this.#commitStep(direction)) this.#stopHold();
       }, _NumberInputController.#HOLD_REPEAT_MS);
     }, _NumberInputController.#HOLD_DELAY_MS);
   }
@@ -254,6 +404,23 @@ var NumberInputController = class _NumberInputController extends Controller {
     if (changed) this.dispatch("change", { detail: { value } });
     return changed;
   }
+  /** Commits an adjacent endpoint/grid value and reports whether it moved. */
+  #commitStep(count) {
+    return this.#commit(stepSteppedValue(this.#currentValue(), count, this.#steppedRange));
+  }
+  /**
+   * Silently reflects the current value after a range or step morph.
+   *
+   * @stimeoRenderRoot
+   */
+  #reconcile() {
+    if (!this.hasInputTarget) return;
+    if (this.inputTarget.value.trim() !== "") {
+      this.#write(this.#normalize(this.#currentValue()));
+    } else {
+      this.#updateButtons(this.#currentValue());
+    }
+  }
   /** Reflects `value` on the input (and ARIA for non-native hosts) and the buttons. */
   #write(value) {
     this.inputTarget.value = String(value);
@@ -300,11 +467,11 @@ var NumberInputController = class _NumberInputController extends Controller {
   }
   /** Clamps to `[min, max]` and snaps to the step grid anchored at a finite min (else 0). */
   #normalize(raw) {
-    const clamped = Math.min(this.maxValue, Math.max(this.minValue, raw));
-    if (this.stepValue <= 0) return clamped;
-    const base = Number.isFinite(this.minValue) ? this.minValue : 0;
-    const stepped = Math.round((clamped - base) / this.stepValue) * this.stepValue + base;
-    return Math.min(this.maxValue, Math.max(this.minValue, stepped));
+    return snapSteppedValue(raw, this.#steppedRange);
+  }
+  /** Shared range configuration; finite endpoints remain allowed off the grid. */
+  get #steppedRange() {
+    return { min: this.minValue, max: this.maxValue, step: this.stepValue };
   }
 };