stimeo-ui 0.4.0 → 0.5.0

data/dist/controllers/skeleton_controller.js

@@ -19,6 +19,61 @@ function fillTemplate(template, values) {
   });
 }
 
+// src/utils/detach_gate.ts
+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
+   * means ambiguous (in-page move or observed-root exit), NOT "alive".
+   */
+  static isDetached(host) {
+    if (!host.element.isConnected) return true;
+    const tokens = (host.element.getAttribute("data-controller") ?? "").split(/\s+/);
+    return !tokens.includes(host.identifier);
+  }
+  /**
+   * Call from `disconnect()`: runs `teardown` synchronously on a definite
+   * detach (fast path), otherwise defers it one microtask — a reconnect
+   * ({@link cancel} from `connect()`) keeps the state, no reconnect runs it.
+   * One microtask is the whole probe window: Stimulus reconnects a moved
+   * element within the same mutation batch, before the checkpoint drains.
+   */
+  disconnected(host, teardown) {
+    if (_DetachGate.isDetached(host)) {
+      this.#pending = false;
+      teardown();
+      return;
+    }
+    this.#pending = true;
+    queueMicrotask(() => {
+      if (!this.#pending) return;
+      this.#pending = false;
+      teardown();
+    });
+  }
+  /**
+   * Disarms a pending probe. Call from `connect()` (the reconnect that proves
+   * an in-page move) and from the head of any teardown path not routed through
+   * {@link disconnected} (disabled-toggle, Escape), so an orphaned probe can
+   * never run the teardown a second time.
+   */
+  cancel() {
+    this.#pending = false;
+  }
+};
+
 // src/utils/min_duration_floor.ts
 var MinDurationFloor = class {
   #timers;
@@ -131,14 +186,16 @@ var SkeletonController = class extends Controller {
   static events = ["ready"];
   #timers = new SafeTimeout();
   #floor = new MinDurationFloor(this.#timers);
+  #gate = new DetachGate();
   connect() {
-    if (this.#state !== "ready") {
+    const moved = this.#gate.pending;
+    this.#gate.cancel();
+    if (!moved && this.#state !== "ready") {
       this.#enterLoading();
     }
   }
   disconnect() {
-    this.#timers.clearAll();
-    this.#floor.cancel();
+    this.#gate.disconnected(this, () => this.#teardown());
   }
   /** Swaps to the real content. Honors `minDuration` to prevent a flash. */
   ready() {
@@ -167,6 +224,17 @@ var SkeletonController = class extends Controller {
     this.dispatch("ready", { detail: {} });
     announce(fillTemplate(this.announceReadyTextValue, {}));
   }
+  /**
+   * Drops the held reveal on a real detach. The markup keeps whatever it last
+   * held: an element on its way out of the document has no reader left, and one
+   * whose `data-controller` dropped the identifier no longer resolves its own
+   * targets, so the rollback could only ever be partial.
+   */
+  #teardown() {
+    this.#gate.cancel();
+    this.#timers.clearAll();
+    this.#floor.cancel();
+  }
   /** Current lifecycle phase as reflected on `data-state`. */
   get #state() {
     return this.element.getAttribute("data-state") ?? "loading";

data/dist/controllers/slider_controller.js

@@ -18,6 +18,92 @@ 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/owned_pointer_session.ts
+var OwnedPointerSession = class {
+  pointerId;
+  #owner;
+  #handlers;
+  #abort = new AbortController();
+  #active = true;
+  constructor(start, owner, handlers) {
+    this.pointerId = start.pointerId;
+    this.#owner = owner;
+    this.#handlers = handlers;
+    const { signal } = this.#abort;
+    owner.ownerDocument.addEventListener("pointermove", this.#onMove, { signal });
+    owner.ownerDocument.addEventListener("pointerup", this.#onEndEvent, { signal });
+    owner.ownerDocument.addEventListener("pointercancel", this.#onEndEvent, { signal });
+    owner.addEventListener("lostpointercapture", this.#onLostCapture, { signal });
+    try {
+      owner.setPointerCapture?.(this.pointerId);
+    } catch {
+    }
+  }
+  /** Whether this session still owns its pointer and listeners. */
+  get active() {
+    return this.#active;
+  }
+  /** Whether `event` belongs to the initiating pointer of the live session. */
+  owns(event) {
+    return this.#active && event.pointerId === this.pointerId;
+  }
+  /** Releases capture/listeners and invokes the end callback exactly once. */
+  end() {
+    if (!this.#active) return;
+    this.#active = false;
+    this.#abort.abort();
+    try {
+      this.#owner.releasePointerCapture?.(this.pointerId);
+    } catch {
+    }
+    this.#handlers.end?.();
+  }
+  #onMove = (event) => {
+    if (this.owns(event)) this.#handlers.move(event);
+  };
+  #onEndEvent = (event) => {
+    if (this.owns(event)) this.end();
+  };
+  #onLostCapture = (event) => {
+    const pointerId = event.pointerId;
+    if (typeof pointerId === "number" && pointerId !== this.pointerId) return;
+    this.end();
+  };
+};
+
 // src/utils/range.ts
 function rangeFraction(value, min, max) {
   const span = max - min;
@@ -34,6 +120,112 @@ function rangeFraction(value, min, max) {
   return Math.min(1, Math.max(0, fraction));
 }
 
+// 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/slider_controller.ts
 var FRACTION_PROPERTY = "--stimeo--slider-fraction";
 var SliderController = class extends Controller {
@@ -47,40 +239,79 @@ var SliderController = class extends Controller {
   };
   static actions = ["onKeydown", "onPointerDown"];
   static events = ["change"];
-  /** Aborts in-progress pointer-drag listeners when the drag ends or on teardown. */
-  #dragAbort = null;
+  /** One initiating pointer owns each live drag and its stable target snapshot. */
+  #drag = null;
+  /** Collapses a morph that swaps several render Values into one silent repaint. */
+  #repaint = new MicrotaskCoalescer(() => this.#render());
   /** Whether the consumer declared a mirroring track and the direction mirrors it. */
   get #mirrored() {
     return this.logicalTrackValue && isRtl(this.element);
   }
   /** Clamps the initial value and renders the starting position. */
   connect() {
-    this.#setValue(this.valueValue, { silent: true });
+    this.#repaint.activate();
+    this.#commit(this.valueValue, false);
   }
   /** Cancels any active pointer drag so document listeners never leak. */
   disconnect() {
-    this.#dragAbort?.abort();
-    this.#dragAbort = null;
+    this.#repaint.cancel();
+    this.#endDrag();
+  }
+  /** Silently repaints a minimum changed by application code or a Turbo morph. */
+  minValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Silently repaints a maximum changed by application code or a Turbo morph. */
+  maxValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Silently repaints a step changed by application code or a Turbo morph. */
+  stepValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Silently repaints a value changed by application code or a Turbo morph. */
+  valueValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Hydrates a thumb inserted or replaced at runtime with the current ARIA state. */
+  thumbTargetConnected(thumb) {
+    const value = this.#currentValue();
+    this.#renderThumb(thumb, value);
+    this.#renderFraction(value);
+    if (this.#drag && this.#drag.thumb === null) {
+      this.#drag.thumb = thumb;
+      thumb.focus();
+    }
+    this.#repaint.schedule();
+  }
+  /** Drops the stale focus owner while allowing a live track gesture to continue. */
+  thumbTargetDisconnected(thumb) {
+    if (this.#drag?.thumb === thumb) this.#drag.thumb = null;
+  }
+  /** Ends a gesture whose geometry target disappeared or ceased being a target. */
+  trackTargetDisconnected(track) {
+    if (this.#drag?.track === track) this.#endDrag();
   }
   /** Handles keyboard stepping per the APG slider model. */
   onKeydown(event) {
     if (isReservedArrowChord(event)) return;
-    const big = this.stepValue * 10;
     let next = null;
+    const current = this.#currentValue();
+    const range = this.#steppedRange;
     switch (this.#mirrored ? logicalArrowKey(event.key, this.element) : event.key) {
       case "ArrowRight":
       case "ArrowUp":
-        next = this.valueValue + this.stepValue;
+        next = stepSteppedValue(current, 1, range);
         break;
       case "ArrowLeft":
       case "ArrowDown":
-        next = this.valueValue - this.stepValue;
+        next = stepSteppedValue(current, -1, range);
         break;
       case "PageUp":
-        next = this.valueValue + big;
+        next = stepSteppedValue(current, 10, range);
         break;
       case "PageDown":
-        next = this.valueValue - big;
+        next = stepSteppedValue(current, -10, range);
         break;
       case "Home":
         next = this.minValue;
@@ -92,56 +323,102 @@ var SliderController = class extends Controller {
         return;
     }
     event.preventDefault();
-    this.#setValue(next);
+    this.#commit(next, true);
   }
   /** Begins a pointer drag: sets the value and tracks subsequent movement. */
   onPointerDown(event) {
-    if (!this.hasTrackTarget) return;
-    event.preventDefault();
+    if (event.button !== 0 || this.#drag || !this.hasTrackTarget || !this.hasThumbTarget) return;
+    const track = this.trackTarget;
+    const thumb = this.thumbTarget;
     const mirrored = this.#mirrored;
-    this.#updateFromClientX(event.clientX, mirrored);
-    if (this.hasThumbTarget) this.thumbTarget.focus();
-    this.#dragAbort?.abort();
-    const abort = new AbortController();
-    this.#dragAbort = abort;
-    const onMove = (move) => this.#updateFromClientX(move.clientX, mirrored);
-    const onUp = () => {
-      abort.abort();
-      this.#dragAbort = null;
-    };
-    document.addEventListener("pointermove", onMove, { signal: abort.signal });
-    document.addEventListener("pointerup", onUp, { signal: abort.signal });
-    document.addEventListener("pointercancel", onUp, { signal: abort.signal });
-  }
-  /** Maps a pointer X coordinate to a value using the track's geometry. */
-  #updateFromClientX(clientX, mirrored) {
-    const rect = this.trackTarget.getBoundingClientRect();
-    if (rect.width === 0) return;
+    const value = this.#valueFromClientX(event.clientX, mirrored, track);
+    if (value === null) return;
+    event.preventDefault();
+    this.#commit(value, true);
+    thumb.focus();
+    const drag = { pointer: null, track, thumb };
+    drag.pointer = new OwnedPointerSession(event, track, {
+      move: (move) => {
+        if (!track.isConnected) {
+          this.#endDrag();
+          return;
+        }
+        const moved = this.#valueFromClientX(move.clientX, mirrored, track);
+        if (moved !== null) this.#commit(moved, true);
+      },
+      end: () => {
+        if (this.#drag === drag) this.#drag = null;
+      }
+    });
+    this.#drag = drag;
+  }
+  /** Maps a pointer X coordinate to a raw value using a stable track snapshot. */
+  #valueFromClientX(clientX, mirrored, track) {
+    const rect = track.getBoundingClientRect();
+    if (rect.width === 0) return null;
     const offset = (clientX - rect.left) / rect.width;
     const fraction = mirrored ? 1 - offset : offset;
-    this.#setValue(this.minValue + fraction * (this.maxValue - this.minValue));
+    return this.minValue + fraction * (this.maxValue - this.minValue);
+  }
+  /**
+   * Stores a normalized value and renders synchronously for responsive input.
+   * Morph callbacks use {@link #render} instead, so they never write Values back
+   * or dispatch a user-facing change event.
+   */
+  #commit(raw, notify) {
+    const previous = this.#currentValue();
+    const value = snapSteppedValue(raw, this.#steppedRange);
+    if (!Object.is(this.valueValue, value)) this.valueValue = value;
+    this.#renderValue(value);
+    if (notify && value !== previous) this.dispatch("change", { detail: { value } });
   }
   /**
-   * Clamps `raw` to `[min, max]`, snaps it to the nearest step, stores it, and
-   * reflects the new state on the thumb's ARIA attributes and the fraction
-   * custom property. Dispatches `change` (detail `{ value }`) on a real value
-   * change — symmetric with `range-slider` — unless `silent` (the initial
-   * connect render, which is not a user edit).
+   * Reflects the normalized current Value without mutating or dispatching it.
+   *
+   * @stimeoRenderRoot
    */
-  #setValue(raw, { silent = false } = {}) {
-    const clamped = Math.min(this.maxValue, Math.max(this.minValue, raw));
-    const stepped = this.stepValue > 0 ? Math.round((clamped - this.minValue) / this.stepValue) * this.stepValue + this.minValue : clamped;
-    const value = Math.min(this.maxValue, Math.max(this.minValue, stepped));
-    const changed = value !== this.valueValue;
-    this.valueValue = value;
+  #render() {
+    this.#renderValue(this.#currentValue());
+  }
+  /** Reflects one normalized value on the current target and CSS output. */
+  #renderValue(value) {
     if (this.hasThumbTarget) {
-      this.thumbTarget.setAttribute("aria-valuemin", String(this.minValue));
-      this.thumbTarget.setAttribute("aria-valuemax", String(this.maxValue));
-      this.thumbTarget.setAttribute("aria-valuenow", String(value));
+      this.#renderThumb(this.thumbTarget, value);
     }
+    this.#renderFraction(value);
+  }
+  /** Writes only ARIA values that differ, including on a replacement target. */
+  #renderThumb(thumb, value) {
+    const attributes = {
+      "aria-valuemin": String(this.minValue),
+      "aria-valuemax": String(this.maxValue),
+      "aria-valuenow": String(value)
+    };
+    for (const [name, next] of Object.entries(attributes)) {
+      if (thumb.getAttribute(name) !== next) thumb.setAttribute(name, next);
+    }
+  }
+  /** Writes the behavior-only positioning hook only when its value changed. */
+  #renderFraction(value) {
     const fraction = rangeFraction(value, this.minValue, this.maxValue);
-    this.element.style.setProperty(FRACTION_PROPERTY, String(fraction));
-    if (changed && !silent) this.dispatch("change", { detail: { value } });
+    const next = String(fraction);
+    if (this.element.style.getPropertyValue(FRACTION_PROPERTY) !== next) {
+      this.element.style.setProperty(FRACTION_PROPERTY, next);
+    }
+  }
+  /** Current normalized value derived from the live declarative inputs. */
+  #currentValue() {
+    return snapSteppedValue(this.valueValue, this.#steppedRange);
+  }
+  /** Shared range configuration; finite endpoints remain allowed off the grid. */
+  get #steppedRange() {
+    return { min: this.minValue, max: this.maxValue, step: this.stepValue };
+  }
+  /** Ends the current pointer session without dispatching another change. */
+  #endDrag() {
+    const drag = this.#drag;
+    this.#drag = null;
+    drag?.pointer?.end();
   }
 };
 

data/dist/controllers/spinner_controller.js

@@ -48,10 +48,27 @@ var BeforeCacheReset = class _BeforeCacheReset {
   }
 };
 
+// src/utils/default_attribute.ts
+function setDefaultAttribute(element, name, value) {
+  if (element.hasAttribute(name)) return false;
+  element.setAttribute(name, value);
+  return true;
+}
+
 // src/utils/detach_gate.ts
 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
@@ -222,9 +239,7 @@ var SpinnerController = class extends Controller {
       this.element.setAttribute("data-state", "idle");
       return;
     }
-    if (!this.element.hasAttribute("data-state")) {
-      this.element.setAttribute("data-state", "idle");
-    }
+    setDefaultAttribute(this.element, "data-state", "idle");
   }
   /**
    * Re-applies the current phase to an indicator that arrived after `connect()`.

data/dist/controllers/step_indicator_controller.js

@@ -99,6 +99,8 @@ var StepIndicatorController = class extends Controller {
    * A pure function of the step set and `current`, so running it again writes the
    * same values — which is what lets the action path paint synchronously (the event
    * goes out after the DOM is updated) while a coalesced pass may still follow.
+   *
+   * @stimeoRenderRoot
    */
   #render() {
     const total = this.stepTargets.length;
@@ -112,7 +114,7 @@ var StepIndicatorController = class extends Controller {
       }
     });
     const ratio = total > 1 ? current / (total - 1) : 0;
-    this.element.style.setProperty("--stimeo-step-indicator-ratio", String(ratio));
+    this.element.style.setProperty("--stimeo--step-indicator-ratio", String(ratio));
   }
   /**
    * Constrains an index to `[0, total-1]` (or `0` when there are no steps). A

data/dist/controllers/stepper_controller.js

@@ -68,6 +68,8 @@ var StepperController = class extends Controller {
    * `aria-current="step"` is placed on the step's **first** `<button>`; the markup
    * contract assumes one operable button per step. If a step needs multiple
    * buttons, mark the navigational one first (or this would target the wrong one).
+   *
+   * @stimeoRenderRoot
    */
   #render(current) {
     this.stepTargets.forEach((step, index) => {