stimeo-ui 0.15.0 → 0.16.0

data/dist/controllers/range_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");
   };
 };
 
@@ -232,7 +234,7 @@ var END_PROPERTY = "--stimeo--range-slider-end";
 var DEFAULT_MIN = 0;
 var DEFAULT_MAX = 100;
 var RangeSliderController = class extends Controller {
-  static targets = ["track", "startThumb", "endThumb"];
+  static targets = ["track", "startThumb", "endThumb", "startField", "endField"];
   static values = {
     min: { type: Number, default: DEFAULT_MIN },
     max: { type: Number, default: DEFAULT_MAX },
@@ -242,9 +244,14 @@ var RangeSliderController = 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;
+  /**
+   * The pair last published: taken on connect, then moved by each user commit
+   * and by each repaint that reports a page-driven move.
+   */
+  #settled = { start: DEFAULT_MIN, end: DEFAULT_MAX };
   /** Whether the consumer declared a mirroring track and the direction mirrors it. */
   get #mirrored() {
     return this.logicalTrackValue && isRtl(this.element);
@@ -254,11 +261,14 @@ var RangeSliderController = class extends Controller {
    * pass Stimulus delivers before `connect()`.
    */
   #repaint = new MicrotaskCoalescer(() => this.#render());
+  /**
+   * Renders the normalized, ordered pair without writing it back, and takes it
+   * as the baseline, so connecting reports nothing.
+   */
   connect() {
     this.#repaint.activate();
-    const range = this.#effectiveRange;
-    const pair = this.#currentPair(range);
-    this.#commit(pair.start, pair.end, null, false);
+    this.#settled = this.#currentPair(this.#effectiveRange);
+    this.#render();
   }
   /** Cancels any active pointer drag so document listeners never leak. */
   disconnect() {
@@ -313,6 +323,14 @@ var RangeSliderController = class extends Controller {
     }
     this.#repaint.schedule();
   }
+  /** Fills a start field inserted or replaced at runtime on the next repaint. */
+  startFieldTargetConnected() {
+    this.#repaint.schedule();
+  }
+  /** Fills an end field inserted or replaced at runtime on the next repaint. */
+  endFieldTargetConnected() {
+    this.#repaint.schedule();
+  }
   /** Drops a stale end-thumb reference without orphaning the track gesture. */
   endThumbTargetDisconnected(thumb) {
     if (this.#drag?.kind === "end" && this.#drag.thumb === thumb) this.#drag.thumb = null;
@@ -439,44 +457,72 @@ var RangeSliderController = class extends Controller {
   #moveThumb(kind, raw) {
     const pair = this.#currentPair(this.#effectiveRange);
     if (kind === "start") {
-      this.#commit(raw, pair.end, "start", true);
+      this.#commit(raw, pair.end, "start");
     } else {
-      this.#commit(pair.start, raw, "end", true);
+      this.#commit(pair.start, raw, "end");
     }
   }
   /**
-   * Clamps and snaps `start`/`end`, enforces `start ≤ end`, stores the pair, and
-   * reflects it onto the thumbs' ARIA attributes and the range custom
-   * properties. Dispatches `stimeo--range-slider:change` only when a
-   * user-driven update changes the normalized pair, with
-   * `{ start: number, end: number }` in `detail`.
+   * Clamps and snaps the pair a user's move of the `moving` thumb produced,
+   * stops that thumb at its partner, stores the pair, and reflects it onto the
+   * thumbs' ARIA attributes and the range custom properties. The pair is
+   * reported as `change` when it differs from the pair last published — not from
+   * the pair the move started from — so a page write no repaint has published
+   * yet is reported once, as this change, and a move that ends on the pair last
+   * published reports nothing. The baseline moves before any report goes out,
+   * so the repaint the Value writes schedule — and any move a subscriber makes
+   * while the report is dispatched — is measured from this pair.
    */
-  #commit(start, end, moving, notify) {
+  #commit(start, end, moving) {
     const range = this.#effectiveRange;
-    const previous = this.#currentPair(range);
     let nextStart = snapSteppedValue(start, range);
     let nextEnd = snapSteppedValue(end, range);
     if (nextStart > nextEnd) {
       if (moving === "start") nextStart = nextEnd;
-      else if (moving === "end") nextEnd = nextStart;
-      else [nextStart, nextEnd] = [nextEnd, nextStart];
+      else nextEnd = nextStart;
     }
+    const pair = { start: nextStart, end: nextEnd };
+    const reported = this.#settled;
+    this.#settled = pair;
     if (!Object.is(this.startValue, nextStart)) this.startValue = nextStart;
     if (!Object.is(this.endValue, nextEnd)) this.endValue = nextEnd;
-    const pair = { start: nextStart, end: nextEnd };
     this.#renderPair(pair, range);
-    if (notify && (nextStart !== previous.start || nextEnd !== previous.end)) {
+    this.#mirrorFields(pair, true);
+    if (nextStart !== reported.start || nextEnd !== reported.end) {
       this.dispatch("change", { detail: { start: nextStart, end: nextEnd } });
     }
   }
   /**
-   * Reflects morph-supplied Values without writing them back or dispatching.
+   * Reflects the Values the page supplied without writing them back. A published
+   * pair that moved from the last one is reported once as `reconcile`; the
+   * fields follow without a native `change`.
    *
    * @stimeoRenderRoot
    */
   #render() {
     const range = this.#effectiveRange;
-    this.#renderPair(this.#currentPair(range), range);
+    const pair = this.#currentPair(range);
+    this.#renderPair(pair, range);
+    this.#mirrorFields(pair, false);
+    const settled = this.#settled;
+    if (pair.start === settled.start && pair.end === settled.end) return;
+    this.#settled = pair;
+    this.dispatch("reconcile", { detail: { start: pair.start, end: pair.end } });
+  }
+  /**
+   * Mirrors the pair into the optional form fields, reporting only a user's
+   * move. Each end is compared on its own, so dragging one thumb never reports
+   * a commit from the field the other thumb owns.
+   */
+  #mirrorFields(pair, notify) {
+    if (this.hasStartFieldTarget) {
+      const field = this.startFieldTarget;
+      if (writeField(field, String(pair.start)) && notify) commitField(field);
+    }
+    if (this.hasEndFieldTarget) {
+      const field = this.endFieldTarget;
+      if (writeField(field, String(pair.end)) && notify) commitField(field);
+    }
   }
   /** Reflects one normalized pair onto both thumbs and CSS properties. */
   #renderPair(pair, range) {

data/dist/controllers/rating_controller.js

@@ -83,6 +83,16 @@ var BeforeCacheReset = class _BeforeCacheReset {
   }
 };
 
+// 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;
@@ -201,11 +211,14 @@ var RatingController = class extends Controller {
   #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
   #connected = false;
   #rescuedFocus = false;
+  /** The rating shown last, which the next move is measured from. */
+  #shown = 0;
   /** Reflects declarative state without announcing an initial user change. */
   connect() {
     this.#repaint.activate();
     this.#beforeCache.activate();
-    this.#apply(this.#normalize(this.valueValue), { focus: false });
+    this.#shown = this.#normalize(this.valueValue);
+    this.#apply(this.#shown, { focus: false });
     this.#connected = true;
   }
   /** Drops a queued reconciliation and hands every borrowed attribute back. */
@@ -306,29 +319,35 @@ var RatingController = class extends Controller {
     this.#commit(next, { focus: true });
   }
   /**
-   * Repaints one settled target/Value mutation batch and reports only a value
-   * this controller had to normalize.
+   * Repaints one settled target/Value mutation batch and reports a rating shown
+   * that moved from the one shown before it.
    *
    * @stimeoRenderRoot
    */
   #reconcileScale() {
-    const requested = this.valueValue;
-    const value = this.#normalize(requested);
+    const value = this.#normalize(this.valueValue);
+    const previous = this.#shown;
+    this.#shown = value;
     this.#apply(value, { focus: false });
-    if (!Object.is(value, requested)) {
-      this.dispatch("reconcile", { detail: { value } });
-    }
+    if (value !== previous) this.dispatch("reconcile", { detail: { value } });
   }
-  /** Applies one user operation and emits only when its committed value changes. */
+  /**
+   * Applies one user operation and emits only when the rating shown changes.
+   *
+   * The user's value is written into `value` before anything reports it, so a
+   * listener of the field's native `change` already reads it there, and the pass
+   * that the write starts finds nothing left to report.
+   */
   #commit(raw, { focus }) {
-    const previous = this.#normalize(this.valueValue);
+    const previous = this.#shown;
     const value = this.#normalize(raw);
-    this.#apply(value, { focus });
+    if (!Object.is(this.valueValue, value)) this.valueValue = value;
+    this.#shown = value;
+    this.#apply(value, { focus, notify: true });
     if (value !== previous) this.dispatch("change", { detail: { value } });
   }
-  /** Synchronizes value, ARIA, roving focus, form state, and the visual fill hook. */
-  #apply(value, { focus }) {
-    if (!Object.is(this.valueValue, value)) this.valueValue = value;
+  /** Synchronizes ARIA, roving focus, form state, and the visual fill hook. */
+  #apply(value, { focus, notify = false }) {
     this.symbolTargets.forEach((symbol, index) => {
       symbol.setAttribute("aria-checked", value > 0 && index + 1 === value ? "true" : "false");
     });
@@ -338,9 +357,14 @@ var RatingController = class extends Controller {
       const returning = this.#releaseReadonly();
       this.#roving.setActive(value > 0 ? value - 1 : 0, { focus: focus || returning });
     }
-    if (this.hasFieldTarget) this.fieldTarget.value = String(value);
+    this.#mirrorField(value, notify);
     this.#setFillRange(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);
+  }
   /** Marks the first `range` symbols with the consumer-owned fill hook. */
   #setFillRange(range) {
     this.symbolTargets.forEach((symbol, index) => {

data/dist/controllers/read_more_controller.js

@@ -139,13 +139,65 @@ var LayoutObserver = class {
   }
 };
 
+// src/utils/state_reason.ts
+var FOCUS_EVENTS = /* @__PURE__ */ new Set(["blur", "focus", "focusin", "focusout"]);
+var POINTER_EVENTS = /* @__PURE__ */ new Set(["mouseenter", "mouseleave", "pointerenter", "pointerleave"]);
+function stateReasonFor(event) {
+  if (!event) return "api";
+  if (FOCUS_EVENTS.has(event.type)) return "focus";
+  if (POINTER_EVENTS.has(event.type)) return "pointer";
+  return "user";
+}
+
+// src/utils/state_regions.ts
+var StateRegions = class {
+  #whenTrue;
+  #whenFalse;
+  #taken = /* @__PURE__ */ new WeakSet();
+  constructor(options) {
+    this.#whenTrue = options.whenTrue;
+    this.#whenFalse = options.whenFalse ?? null;
+  }
+  /** Shows the regions inside `host` that belong to `isTrue` and hides the others. */
+  reflect(host, isTrue) {
+    const shown = this.#inside(host, this.#whenTrue());
+    if (!this.#whenFalse) {
+      for (const region of shown) this.#write(region, !isTrue);
+      return;
+    }
+    const hiddenSide = this.#inside(host, this.#whenFalse());
+    if (shown.length === 0 || hiddenSide.length === 0) {
+      for (const region of shown) this.#give(region);
+      for (const region of hiddenSide) this.#give(region);
+      return;
+    }
+    for (const region of shown) this.#write(region, !isTrue);
+    for (const region of hiddenSide) this.#write(region, isTrue);
+  }
+  /** Writes `hidden` where it moves, noting which regions it takes out of view. */
+  #write(region, hidden) {
+    if (hidden) this.#taken.add(region);
+    else this.#taken.delete(region);
+    if (region.hidden !== hidden) region.hidden = hidden;
+  }
+  /** Returns a region this instance hid; one it never hid keeps what it carries. */
+  #give(region) {
+    if (this.#taken.delete(region)) region.hidden = false;
+  }
+  /** The declared regions that sit within `host`, which may be the host itself. */
+  #inside(host, regions) {
+    return regions.filter((region) => host.contains(region));
+  }
+};
+
 // src/controllers/read_more_controller.ts
 var ReadMoreController = class extends Controller {
-  static targets = ["content", "trigger"];
+  static targets = ["content", "trigger", "expandedLabel", "collapsedLabel"];
   static values = {
     collapsed: { type: Boolean, default: true }
   };
   static actions = ["toggle"];
+  static events = ["close", "open"];
   #connected = false;
   #collapsed = true;
   #observedContent = null;
@@ -154,6 +206,11 @@ var ReadMoreController = class extends Controller {
     if (this.#connected) this.#evaluateOverflow();
   };
   #layout = new LayoutObserver(this.#update);
+  /** Owns `hidden` on the trigger's two labels. */
+  #labels = new StateRegions({
+    whenTrue: () => this.expandedLabelTargets,
+    whenFalse: () => this.collapsedLabelTargets
+  });
   /** Holds the trigger's hide back while it has focus; re-evaluates on blur. */
   #deferredHide = new BlurDeferral(() => {
     this.#update();
@@ -181,12 +238,21 @@ var ReadMoreController = class extends Controller {
     this.#deferredHide.release(trigger);
     this.#syncTargets();
   }
+  expandedLabelTargetConnected() {
+    this.#syncTargets();
+  }
+  collapsedLabelTargetConnected() {
+    this.#syncTargets();
+  }
   /** Toggles between the collapsed (clamped) and expanded states. */
-  toggle() {
+  toggle(event) {
     if (!this.#connected) return;
     this.#collapsed = !this.#collapsed;
     this.#reflect();
     this.#evaluateOverflow();
+    const detail = { reason: stateReasonFor(event) };
+    if (this.#collapsed) this.dispatch("close", { detail, cancelable: false });
+    else this.dispatch("open", { detail, cancelable: false });
   }
   #initialCollapsed() {
     if (this.hasContentTarget) {
@@ -202,6 +268,7 @@ var ReadMoreController = class extends Controller {
     }
     if (this.hasTriggerTarget) {
       this.triggerTarget.setAttribute("aria-expanded", this.#collapsed ? "false" : "true");
+      this.#labels.reflect(this.triggerTarget, !this.#collapsed);
     }
   }
   #syncTargets() {

data/dist/controllers/resizable_controller.js

@@ -107,7 +107,20 @@ var TabindexLoan = 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/resizable_controller.ts
+var TRANSIENT = new TransientHooks({ attributes: ["data-dragging"] });
 var DEFAULT_MIN = 0;
 var DEFAULT_MAX = 100;
 var DEFAULT_VALUE = 50;
@@ -121,9 +134,20 @@ var ResizableController = class extends Controller {
     value: { type: Number, default: DEFAULT_VALUE }
   };
   static actions = ["onKeydown", "onPointerDown", "toggle"];
-  static events = ["change"];
+  static events = ["change", "reconcile"];
   /** Where the divider sat before the current collapse; `null` when unknown. */
   #valueBeforeCollapse = null;
+  /**
+   * The position last painted: moved by each move the user makes — every step of
+   * a drag included — and by each repaint that finds a page-driven move.
+   */
+  #painted = DEFAULT_VALUE;
+  /**
+   * The position last confirmed: the one connecting published, then moved by
+   * each `change` and `reconcile`. A drag moves the painted position step by
+   * step and this one only when it ends.
+   */
+  #confirmed = DEFAULT_VALUE;
   /** Aborts in-progress pointer-drag listeners when the drag ends or on teardown. */
   #dragAbort = null;
   /** `tabindex` lent to a pane so `F6` can put focus on it; panes carry none. */
@@ -133,8 +157,9 @@ var ResizableController = class extends Controller {
   /** Folds the range and position inputs of one morph batch into a single paint. */
   #repaint = new MicrotaskCoalescer(() => this.#render());
   connect() {
-    this.element.removeAttribute("data-dragging");
+    TRANSIENT.reset(this.element);
     this.#repaint.activate();
+    this.#confirmed = this.#position;
     this.#render();
     this.#cycleAbort = new AbortController();
     this.element.addEventListener("keydown", this.#onCycleKeydown, {
@@ -251,9 +276,7 @@ var ResizableController = class extends Controller {
     }
     if (handled) {
       event.preventDefault();
-      this.valueValue = Math.max(min, Math.min(nextValue, max));
-      this.#render();
-      this.#dispatchChange();
+      this.#commit(nextValue);
     }
   }
   /** Collapses the primary pane to its minimum, or returns it to the last position. */
@@ -261,22 +284,19 @@ var ResizableController = class extends Controller {
     const { min, max } = this.#range;
     if (this.#position > min) {
       this.#valueBeforeCollapse = this.#position;
-      this.valueValue = min;
+      this.#commit(min);
     } else {
-      this.valueValue = this.#valueBeforeCollapse ?? max;
+      const restored = this.#valueBeforeCollapse ?? max;
       this.#valueBeforeCollapse = null;
+      this.#commit(restored);
     }
-    this.#render();
-    this.#dispatchChange();
   }
   #onPointerMove = (event) => {
     if (!this.hasSeparatorTarget) return;
     const rect = this.element.getBoundingClientRect();
     const raw = this.#isVertical ? (event.clientX - rect.left) / rect.width : (event.clientY - rect.top) / rect.height;
     const fraction = Number.isFinite(raw) ? Math.max(0, Math.min(raw, 1)) : 0;
-    const { min, max } = this.#range;
-    this.valueValue = Math.max(min, Math.min(Math.round(fraction * 100), max));
-    this.#render();
+    this.#move(Math.round(fraction * 100));
   };
   #onPointerUp = (event) => {
     this.element.removeAttribute("data-dragging");
@@ -285,21 +305,50 @@ var ResizableController = class extends Controller {
     if (this.hasSeparatorTarget) {
       this.separatorTarget.releasePointerCapture(event.pointerId);
     }
-    this.#dispatchChange();
+    this.#confirm();
   };
+  /** Moves to a position the user chose and reports it if it moved. */
+  #commit(raw) {
+    this.#move(raw);
+    this.#confirm();
+  }
   /**
-   * Publishes the position: the fraction consumer CSS multiplies a pane by, and
-   * the range assistive tech reads off the separator. The clamped position is
-   * written back to the Value so it, ARIA, CSS, and dispatched events agree.
+   * Stores the clamped position the user moved to and paints it. The painted
+   * position moves with it before anything is reported, so the repaint the Value
+   * write schedules — and any move a subscriber makes while `change` is
+   * dispatched — is measured from this position.
+   */
+  #move(raw) {
+    const { min, max } = this.#range;
+    const position = Math.max(min, Math.min(raw, max));
+    this.valueValue = position;
+    this.#painted = position;
+    this.#paint();
+  }
+  /**
+   * Publishes the position the Values declare without writing it back. A
+   * position the user did not paint is the page's move, reported once as
+   * `reconcile` unless it lands on the position last confirmed — a drag the page
+   * puts back where it started has nothing new to report.
    *
    * @stimeoRenderRoot
    */
   #render() {
+    this.#paint();
+    const position = this.#position;
+    if (position === this.#painted) return;
+    this.#painted = position;
+    if (position === this.#confirmed) return;
+    this.#confirmed = position;
+    this.dispatch("reconcile", { detail: this.#detail(position) });
+  }
+  /**
+   * Publishes the position: the fraction consumer CSS multiplies a pane by, and
+   * the range assistive tech reads off the separator.
+   */
+  #paint() {
     const { min, max } = this.#range;
     const position = this.#position;
-    if (this.valueValue !== position) {
-      this.valueValue = position;
-    }
     this.element.style.setProperty("--stimeo--resizable-fraction", String(position / 100));
     if (this.hasSeparatorTarget) {
       this.separatorTarget.setAttribute("aria-valuenow", String(position));
@@ -307,9 +356,20 @@ var ResizableController = class extends Controller {
       this.separatorTarget.setAttribute("aria-valuemax", String(max));
     }
   }
-  #dispatchChange() {
-    const fraction = this.valueValue / 100;
-    this.dispatch("change", { detail: { value: this.valueValue, fraction } });
+  /**
+   * Reports the published position as `change` when the user's operation moved
+   * it from the position last confirmed. A key at an edge, a press released
+   * without moving and a drag released where it started report nothing.
+   */
+  #confirm() {
+    const position = this.#position;
+    if (position === this.#confirmed) return;
+    this.#confirmed = position;
+    this.dispatch("change", { detail: this.#detail(position) });
+  }
+  /** The detail both events carry for `position`. */
+  #detail(position) {
+    return { value: position, fraction: position / 100 };
   }
   /** The declared range after validation; an unreadable bound uses its default. */
   get #range() {

data/dist/controllers/scroll_area_controller.js

@@ -518,7 +518,11 @@ var ScrollAreaController = class extends Controller {
     this.#overflowing = false;
     this.#lastEdge = null;
   }
-  /** Runs the full structural and positional measurement pass. */
+  /**
+   * Runs the full structural and positional measurement pass.
+   *
+   * @stimeoRenderRoot
+   */
   #refresh() {
     const viewport = this.#viewport;
     if (!viewport) return;

data/dist/controllers/scroll_visibility_controller.js

@@ -332,7 +332,6 @@ var ScrollVisibilityController = class extends Controller {
     this.element.setAttribute("data-state", next ? "visible" : "hidden");
     if (notify) this.dispatch("change", { detail: { visible: next } });
   }
-  /** Resolves the scroll source from `root` (falling back to the window). */
   /**
    * The focus owner inside the target, or `null` when focus is elsewhere.
    *

data/dist/controllers/scrollspy_controller.js

@@ -422,6 +422,10 @@ var ScrollspyController = class extends Controller {
     this.#scrollSource?.removeEventListener("scroll", this.#onScroll);
     this.#scrollSource = null;
   }
+  /**
+   * @stimeoRuntimeOnly `rootMargin` wires the observer this call installs; the active section it
+   *   republishes is the one already recorded.
+   */
   #initializeObserver() {
     this.#watcher.stop();
     this.#intersectionStates.clear();
@@ -467,6 +471,8 @@ var ScrollspyController = class extends Controller {
    * threshold) against a freshly computed trigger line mixes two moments in
    * time, which would make the result depend on how the reader arrived at a
    * position — a smooth scroll and an instant jump to the same offset disagree.
+   *
+   * @stimeoRenderRoot
    */
   #evaluateActiveSection() {
     const rootEl = this.#scrollRoot();