stimeo-ui 0.15.0 → 0.16.0

data/dist/controllers/slider_controller.js

@@ -18,6 +18,16 @@ 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/field_mirror.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 }));
+}
+
 // src/utils/microtask_coalescer.ts
 var MicrotaskCoalescer = class {
   #run;
@@ -53,54 +63,46 @@ var MicrotaskCoalescer = class {
 
 // src/utils/owned_pointer_session.ts
 var OwnedPointerSession = class {
-  pointerId;
+  #pointerId;
   #owner;
   #handlers;
   #abort = new AbortController();
   #active = true;
   constructor(start, owner, handlers) {
-    this.pointerId = start.pointerId;
+    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);
+      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. */
+  /** Releases capture and listeners, then reports the end exactly once. */
   end() {
+    this.#finish("teardown");
+  }
+  #finish(kind) {
     if (!this.#active) return;
     this.#active = false;
     this.#abort.abort();
     try {
-      this.#owner.releasePointerCapture?.(this.pointerId);
+      this.#owner.releasePointerCapture?.(this.#pointerId);
     } catch {
     }
-    this.#handlers.end?.();
+    this.#handlers.end?.(kind);
+  }
+  #owns(event) {
+    return this.#active && event.pointerId === this.#pointerId;
   }
   #onMove = (event) => {
-    if (this.owns(event)) this.#handlers.move(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();
+    if (this.#owns(event)) this.#finish(event.type === "pointerup" ? "up" : "cancel");
   };
 };
 
@@ -229,7 +231,7 @@ function finiteFallback(min, max) {
 // src/controllers/slider_controller.ts
 var FRACTION_PROPERTY = "--stimeo--slider-fraction";
 var SliderController = class extends Controller {
-  static targets = ["track", "thumb"];
+  static targets = ["track", "thumb", "field"];
   static values = {
     min: { type: Number, default: 0 },
     max: { type: Number, default: 100 },
@@ -238,38 +240,47 @@ var SliderController = class extends Controller {
     logicalTrack: { type: Boolean, default: false }
   };
   static actions = ["onKeydown", "onPointerDown"];
-  static events = ["change"];
+  static events = ["change", "reconcile"];
   /** 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. */
+  /**
+   * The value last published: taken on connect, then moved by each user commit
+   * and by each repaint that reports a page-driven move.
+   */
+  #settled = 0;
+  /** Collapses a morph that swaps several render Values into one 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. */
+  /**
+   * Renders the normalized value as the starting position without writing it
+   * back, and takes it as the baseline, so connecting reports nothing.
+   */
   connect() {
     this.#repaint.activate();
-    this.#commit(this.valueValue, false);
+    this.#settled = this.#currentValue();
+    this.#render();
   }
   /** Cancels any active pointer drag so document listeners never leak. */
   disconnect() {
     this.#repaint.cancel();
     this.#endDrag();
   }
-  /** Silently repaints a minimum changed by application code or a Turbo morph. */
+  /** 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. */
+  /** 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. */
+  /** 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. */
+  /** Repaints a value changed by application code or a Turbo morph. */
   valueValueChanged() {
     this.#repaint.schedule();
   }
@@ -284,6 +295,10 @@ var SliderController = class extends Controller {
     }
     this.#repaint.schedule();
   }
+  /** Fills a form field inserted or replaced at runtime on the next repaint. */
+  fieldTargetConnected() {
+    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;
@@ -296,22 +311,22 @@ var SliderController = class extends Controller {
   onKeydown(event) {
     if (isReservedArrowChord(event)) return;
     let next = null;
-    const current = this.#currentValue();
+    const declared = this.valueValue;
     const range = this.#steppedRange;
     switch (this.#mirrored ? logicalArrowKey(event.key, this.element) : event.key) {
       case "ArrowRight":
       case "ArrowUp":
-        next = stepSteppedValue(current, 1, range);
+        next = stepSteppedValue(declared, 1, range);
         break;
       case "ArrowLeft":
       case "ArrowDown":
-        next = stepSteppedValue(current, -1, range);
+        next = stepSteppedValue(declared, -1, range);
         break;
       case "PageUp":
-        next = stepSteppedValue(current, 10, range);
+        next = stepSteppedValue(declared, 10, range);
         break;
       case "PageDown":
-        next = stepSteppedValue(current, -10, range);
+        next = stepSteppedValue(declared, -10, range);
         break;
       case "Home":
         next = this.minValue;
@@ -323,7 +338,7 @@ var SliderController = class extends Controller {
         return;
     }
     event.preventDefault();
-    this.#commit(next, true);
+    this.#commit(next);
   }
   /** Begins a pointer drag: sets the value and tracks subsequent movement. */
   onPointerDown(event) {
@@ -334,7 +349,7 @@ var SliderController = class extends Controller {
     const value = this.#valueFromClientX(event.clientX, mirrored, track);
     if (value === null) return;
     event.preventDefault();
-    this.#commit(value, true);
+    this.#commit(value);
     thumb.focus();
     const drag = { pointer: null, track, thumb };
     drag.pointer = new OwnedPointerSession(event, track, {
@@ -344,7 +359,7 @@ var SliderController = class extends Controller {
           return;
         }
         const moved = this.#valueFromClientX(move.clientX, mirrored, track);
-        if (moved !== null) this.#commit(moved, true);
+        if (moved !== null) this.#commit(moved);
       },
       end: () => {
         if (this.#drag === drag) this.#drag = null;
@@ -361,24 +376,44 @@ var SliderController = class extends Controller {
     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.
+   * Stores the normalized value the user moved to, renders it synchronously for
+   * responsive input, and reports it as `change` when it differs from the value
+   * last published. The comparison is with the value last published, not with
+   * the value the move started from, so a page write no repaint has published
+   * yet is reported once, as this change, and a move that ends where the value
+   * was last published reports nothing. The baseline moves before either report
+   * goes out, so the repaint the Value write schedules — and any move a
+   * subscriber makes while the report is dispatched — is measured from this
+   * value.
    */
-  #commit(raw, notify) {
-    const previous = this.#currentValue();
+  #commit(raw) {
     const value = snapSteppedValue(raw, this.#steppedRange);
+    const reported = this.#settled;
+    this.#settled = value;
     if (!Object.is(this.valueValue, value)) this.valueValue = value;
     this.#renderValue(value);
-    if (notify && value !== previous) this.dispatch("change", { detail: { value } });
+    this.#mirrorField(value, true);
+    if (value !== reported) this.dispatch("change", { detail: { value } });
+  }
+  /** Mirrors `value` into the optional form field, reporting only a user's move. */
+  #mirrorField(value, notify) {
+    if (!this.hasFieldTarget) return;
+    if (writeField(this.fieldTarget, String(value)) && notify) commitField(this.fieldTarget);
   }
   /**
-   * Reflects the normalized current Value without mutating or dispatching it.
+   * Reflects the normalized current Value without writing it back. A published
+   * value that moved from the last one is reported once as `reconcile`; the
+   * field follows without a native `change`.
    *
    * @stimeoRenderRoot
    */
   #render() {
-    this.#renderValue(this.#currentValue());
+    const value = this.#currentValue();
+    this.#renderValue(value);
+    this.#mirrorField(value, false);
+    if (value === this.#settled) return;
+    this.#settled = value;
+    this.dispatch("reconcile", { detail: { value } });
   }
   /** Reflects one normalized value on the current target and CSS output. */
   #renderValue(value) {

data/dist/controllers/smart_sticky_header_controller.js

@@ -121,6 +121,7 @@ var SmartStickyHeaderController = class extends Controller {
     this.element.removeEventListener("focusin", this.#onFocusin);
     this.#frames.cancel();
   }
+  /** @stimeoRenderRoot */
   #measure() {
     const y = scrollOffset(this.#scrollerEl);
     if (y <= this.#offset) {
@@ -129,10 +130,19 @@ var SmartStickyHeaderController = class extends Controller {
       return;
     }
     const delta = y - this.#lastY;
-    if (Math.abs(delta) < this.toleranceValue) return;
+    if (this.#isJitter(delta)) return;
     this.#lastY = y;
     this.#apply(delta > 0);
   }
+  /**
+   * Whether one scroll step is too small to act on.
+   *
+   * @stimeoRuntimeOnly `tolerance` is the allowance one scroll step is compared against; the
+   *   header's state at rest does not depend on it.
+   */
+  #isJitter(delta) {
+    return Math.abs(delta) < this.toleranceValue;
+  }
   /**
    * Reflects the state onto the hook and emits `change` on transitions.
    *

data/dist/controllers/sortable_controller.js

@@ -57,7 +57,20 @@ var MicrotaskCoalescer = class {
   }
 };
 
+// src/utils/transient_hooks.ts
+var TransientHooks = class {
+  #attributes;
+  constructor(options) {
+    this.#attributes = options.attributes;
+  }
+  /** Drops the declared hooks from `element`; what it carries besides stays. */
+  reset(element) {
+    for (const attribute of this.#attributes) element.removeAttribute(attribute);
+  }
+};
+
 // src/controllers/sortable_controller.ts
+var TRANSIENT = new TransientHooks({ attributes: ["data-sortable-dragging"] });
 var SortableController = class extends Controller {
   static targets = ["list", "item"];
   static values = {
@@ -72,7 +85,7 @@ var SortableController = class extends Controller {
   /** Defers the lost-item check to after the mutation batch (see below). */
   #settle = new MicrotaskCoalescer(() => this.#dropLostSession());
   connect() {
-    this.element.removeAttribute("data-sortable-dragging");
+    TRANSIENT.reset(this.element);
     this.#settle.activate();
     this.element.addEventListener("stimeo--pointer-drag:start", this.#onDragStart);
     this.element.addEventListener("stimeo--pointer-drag:move", this.#onDragMove);
@@ -295,6 +308,8 @@ var SortableController = class extends Controller {
    * Only transitions reach here — the pickup, a step that actually changed the
    * landing slot, and the single end of the session — so a pointer crossing the
    * same slot twice or an arrow clamped at an end stays silent.
+   *
+   * @stimeoRuntimeOnly The texts word the steps of one reorder, spoken as they happen.
    */
   #announce(key, item) {
     const template = this.#announceTemplate(key);
@@ -323,7 +338,7 @@ var SortableController = class extends Controller {
   }
   /** The announced item name: the authored override, else its collapsed text. */
   #nameOf(item) {
-    const authored = item.getAttribute("data-stimeo--sortable-name");
+    const authored = item.getAttribute(`data-${this.identifier}-name`);
     if (authored) return authored;
     return (item.textContent ?? "").replace(/\s+/g, " ").trim();
   }

data/dist/controllers/spinner_controller.js

@@ -292,7 +292,11 @@ var SpinnerController = class extends Controller {
     this.#setBusy(false);
     this.#floor.schedule(this.minDurationValue, () => this.#hide());
   }
-  /** Reveals the indicator, marks the moment shown, and announces via the live region. */
+  /**
+   * Reveals the indicator, marks the moment shown, and announces via the live region.
+   *
+   * @stimeoRuntimeOnly `announceText` is the wording of the one announcement this show makes.
+   */
   #show() {
     this.#floor.begin();
     this.#setBusy(true);
@@ -301,7 +305,11 @@ var SpinnerController = class extends Controller {
     this.dispatch("show", { detail: {} });
     announce(fillTemplate(this.announceTextValue, {}));
   }
-  /** Hides the indicator and returns to the idle state. */
+  /**
+   * Hides the indicator and returns to the idle state.
+   *
+   * @stimeoRuntimeOnly `announceReadyText` is the wording of the one announcement this hide makes.
+   */
   #hide() {
     if (this.hasIndicatorTarget) this.indicatorTarget.hidden = true;
     this.element.setAttribute("data-state", "idle");

data/dist/controllers/step_indicator_controller.js

@@ -39,17 +39,17 @@ var MicrotaskCoalescer = class {
 var StepIndicatorController = class extends Controller {
   static targets = ["step"];
   static values = {
-    current: { type: Number, default: 0 }
+    index: { type: Number, default: 0 }
   };
-  static actions = ["setCurrent"];
+  static actions = ["setIndex"];
   static events = ["change"];
   /**
-   * Collapses a batch of step callbacks — and a morph that swaps `current` with
+   * Collapses a batch of step callbacks — and a morph that swaps `index` with
    * them — into one repaint. Replacing a list of N steps delivers N callbacks, and
    * each one would otherwise rewrite every step's state.
    */
   #repaint = new MicrotaskCoalescer(() => this.#render());
-  /** Renders the initial state from the `current` value. */
+  /** Renders the initial state from the `index` value. */
   connect() {
     this.#repaint.activate();
     this.#render();
@@ -66,32 +66,33 @@ var StepIndicatorController = class extends Controller {
   stepTargetDisconnected() {
     this.#repaint.schedule();
   }
-  /** Repaints when application code (or a Turbo morph) changes `current` at runtime. */
-  currentValueChanged() {
+  /** Repaints when application code (or a Turbo morph) changes `index` at runtime. */
+  indexValueChanged() {
     this.#repaint.schedule();
   }
   /**
-   * Updates the current step from an external event (`detail.current`, 0-based)
-   * and dispatches `change`. Out-of-range indices are clamped to the step set,
+   * Moves the indicator from an external event (`detail.index`, 0-based) and
+   * dispatches `change`. Out-of-range positions are clamped to the step set,
    * and both sides of the no-op test are clamped, so moving onto the step an
-   * out-of-range `current` already renders is not reported as a change.
+   * out-of-range `index` already renders is not reported as a change.
    */
-  setCurrent(event) {
-    const next = event.detail?.current;
+  setIndex(event) {
+    const next = event.detail?.index;
     if (typeof next !== "number" || !Number.isFinite(next)) return;
     const clamped = this.#clamp(next);
-    const moved = clamped !== this.#clamp(this.currentValue);
-    this.currentValue = clamped;
+    const previous = this.#clamp(this.indexValue);
+    const moved = clamped !== previous;
+    this.indexValue = clamped;
     if (!moved) return;
     this.#render();
     this.dispatch("change", {
-      detail: { current: clamped, total: this.stepTargets.length }
+      detail: { index: clamped, previous, total: this.stepTargets.length }
     });
   }
   /**
    * Applies `data-state`, `aria-current`, and the progress ratio custom property.
    *
-   * A pure function of the step set and `current`, so running it again writes the
+   * A pure function of the step set and `index`, 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.
    *
@@ -99,7 +100,7 @@ var StepIndicatorController = class extends Controller {
    */
   #render() {
     const total = this.stepTargets.length;
-    const current = this.#clamp(this.currentValue);
+    const current = this.#clamp(this.indexValue);
     this.stepTargets.forEach((step, index) => {
       step.dataset.state = index < current ? "complete" : index === current ? "current" : "upcoming";
       if (index === current) {
@@ -113,7 +114,7 @@ var StepIndicatorController = class extends Controller {
   }
   /**
    * Constrains an index to `[0, total-1]` (or `0` when there are no steps). A
-   * non-finite index falls back to the first step: `current` is read from markup,
+   * non-finite index falls back to the first step: `index` is read from markup,
    * so an unparsable attribute arrives as `NaN` and would otherwise propagate
    * into every state hook.
    */

data/dist/controllers/stepper_controller.js

@@ -1,5 +1,40 @@
 import { Controller } from '@hotwired/stimulus';
 
+// src/controllers/stepper_controller.ts
+
+// src/utils/microtask_coalescer.ts
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  /** @param run - the single reconciliation pass, invoked at most once per batch. */
+  constructor(run) {
+    this.#run = run;
+  }
+  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
+  activate() {
+    this.#active = true;
+  }
+  /** Closes the window and drops any pending pass; call from `disconnect()`. */
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */
+  schedule() {
+    if (!this.#active || this.#queued) return;
+    this.#queued = true;
+    const generation = this.#generation;
+    queueMicrotask(() => {
+      if (generation !== this.#generation || !this.#queued || !this.#active) return;
+      this.#queued = false;
+      this.#run();
+    });
+  }
+};
+
 // src/controllers/stepper_controller.ts
 var StepperController = class extends Controller {
   static targets = ["step"];
@@ -8,20 +43,39 @@ var StepperController = class extends Controller {
     linear: { type: Boolean, default: false }
   };
   static actions = ["goto", "next", "prev"];
-  static events = ["change"];
-  #isConnected = false;
-  /** Normalizes an out-of-range initial `index` and renders the initial state. */
+  static events = ["change", "reconcile"];
+  /**
+   * Collapses the Value and target callbacks of one mutation into one pass, and
+   * refuses the ones Stimulus delivers before `connect()`, which renders itself.
+   */
+  #repaint = new MicrotaskCoalescer(() => this.#reconcileStep());
+  /**
+   * The position shown current last, which the next move is measured from, or
+   * `null` before any step has been shown. While no step is present it keeps the
+   * last one.
+   */
+  #shown = null;
+  /** Renders the initial state from `index`, clamped into the step range. */
   connect() {
-    this.#isConnected = true;
-    this.#normalizeAndRender();
+    this.#repaint.activate();
+    this.#shown = this.#currentStep;
+    this.#render();
   }
+  /** Drops a pending pass, so nothing renders or reports for a stepper that left. */
   disconnect() {
-    this.#isConnected = false;
+    this.#repaint.cancel();
   }
   /** Re-renders when Turbo Morph or application code changes `index` at runtime. */
   indexValueChanged() {
-    if (!this.#isConnected) return;
-    this.#normalizeAndRender();
+    this.#repaint.schedule();
+  }
+  /** Re-derives every step's state for a step added at runtime. */
+  stepTargetConnected() {
+    this.#repaint.schedule();
+  }
+  /** Re-derives every step's state for a step removed at runtime. */
+  stepTargetDisconnected() {
+    this.#repaint.schedule();
   }
   /** Advances to the next step (ignored at the last step). */
   next() {
@@ -31,9 +85,16 @@ var StepperController = class extends Controller {
   prev() {
     this.#moveTo(this.#clampIndex(this.indexValue) - 1);
   }
-  /** Jumps to the step carried in the action's `index` param. */
+  /**
+   * Jumps to the step carried in the action's `index` param. A param that is empty,
+   * or that Stimulus parses into anything but a number or a string, is no index,
+   * so it jumps nowhere.
+   */
   goto(event) {
-    const target = Number(event.params.index);
+    const { index } = event.params;
+    if (index === "") return;
+    if (typeof index !== "number" && typeof index !== "string") return;
+    const target = Number(index);
     if (!Number.isFinite(target) || !Number.isInteger(target)) return;
     this.#moveTo(target);
   }
@@ -51,19 +112,39 @@ var StepperController = class extends Controller {
     if (this.linearValue && target > current + 1) return;
     const previous = current;
     this.indexValue = target;
-    this.#render(target);
+    this.#shown = target;
+    this.#render();
     this.dispatch("change", {
-      detail: { index: target, previous, step: this.stepTargets[target] }
+      detail: { index: target, previous, total, step: this.stepTargets[target] }
     });
   }
-  /** Normalizes the public Value and reflects it without dispatching an action event. */
-  #normalizeAndRender() {
-    const normalized = this.#clampIndex(this.indexValue);
-    if (!Object.is(normalized, this.indexValue)) this.indexValue = normalized;
-    this.#render(normalized);
+  /**
+   * Re-derives one settled batch of Value and target changes, and reports a
+   * current position that moved from the one shown before as `reconcile`. With no
+   * step present there is nothing to report, and the position shown last stays the
+   * one the next move is measured from.
+   */
+  #reconcileStep() {
+    const previous = this.#shown;
+    const index = this.#currentStep;
+    if (index !== null) this.#shown = index;
+    this.#render();
+    if (index === null || previous === null || index === previous) return;
+    const steps = this.stepTargets;
+    this.dispatch("reconcile", {
+      detail: { index, previous, total: steps.length, step: steps[index] }
+    });
+  }
+  /** The current position, clamped into the step range, or `null` when there is no step. */
+  get #currentStep() {
+    return this.stepTargets.length > 0 ? this.#clampIndex(this.indexValue) : null;
   }
   /**
-   * Derives each step's `data-state` and the current button's `aria-current`.
+   * Derives each step's `data-state` and the current button's `aria-current` from
+   * `index`, clamped into the step range, without dispatching an action event.
+   *
+   * The clamp decides only what is shown. This body never writes `index`, so an
+   * out-of-range declaration stays in the attribute as the page wrote it.
    *
    * `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
@@ -71,7 +152,8 @@ var StepperController = class extends Controller {
    *
    * @stimeoRenderRoot
    */
-  #render(current) {
+  #render() {
+    const current = this.#clampIndex(this.indexValue);
     this.stepTargets.forEach((step, index) => {
       step.dataset.state = index < current ? "complete" : index === current ? "current" : "upcoming";
       const button = step.querySelector("button");