stimeo-ui 0.15.0 → 0.17.0

package/dist/controllers/overflow_indicator_controller.js

@@ -1,30 +1,20 @@
 import { Controller } from '@hotwired/stimulus';
 
-// src/controllers/overflow_indicator_controller.ts
-
-// src/utils/blur_deferral.ts
 var BlurDeferral = class {
-  /** Elements currently holding an update back, mapped to their `blur` listener. */
   #pending = /* @__PURE__ */ new Map();
-  /** Called after a pending element blurs and has been detached. */
   #onRelease;
-  /** @param onRelease - Invoked once `element` actually blurs; never on `release`. */
   constructor(onRelease) {
     this.#onRelease = onRelease;
   }
-  /** Number of elements currently holding an update back. */
   get size() {
     return this.#pending.size;
   }
-  /** Snapshot of the pending elements, safe to iterate while releasing them. */
   get elements() {
     return [...this.#pending.keys()];
   }
-  /** Whether `element` is currently holding an update back. */
   has(element) {
     return this.#pending.has(element);
   }
-  /** Holds an update back until `element` blurs. Idempotent (no stacked listeners). */
   defer(element) {
     if (this.#pending.has(element)) return;
     const onBlur = () => {
@@ -34,22 +24,18 @@ var BlurDeferral = class {
     this.#pending.set(element, onBlur);
     element.addEventListener("blur", onBlur);
   }
-  /** Defers `element` as the only pending entry, cancelling any others. */
   deferOnly(element) {
     for (const pending of this.elements) {
       if (pending !== element) this.#detach(pending);
     }
     this.defer(element);
   }
-  /** Cancels `element`'s deferral without completing it; no-ops when not pending. */
   release(element) {
     this.#detach(element);
   }
-  /** Cancels every deferral without completing any of them. */
   releaseAll() {
     for (const element of this.elements) this.#detach(element);
   }
-  /** Removes the `blur` listener for `element` and forgets it. */
   #detach(element) {
     const onBlur = this.#pending.get(element);
     if (onBlur) element.removeEventListener("blur", onBlur);
@@ -57,18 +43,31 @@ var BlurDeferral = class {
   }
 };
 
-// src/utils/layout_observer.ts
+var FrameCoalescer = class {
+  #frame = null;
+  schedule(run) {
+    if (this.#frame !== null) return;
+    this.#frame = requestAnimationFrame(() => {
+      this.#frame = null;
+      run();
+    });
+  }
+  cancel() {
+    if (this.#frame === null) return;
+    cancelAnimationFrame(this.#frame);
+    this.#frame = null;
+  }
+};
+
 var LayoutObserver = class {
   #callback;
   #resizeObserverFactory;
   #resizeObserver = null;
   #observingViewport = false;
   #loadContainer = null;
-  /** Stable bound handler so add/removeEventListener target the same reference. */
   #handleViewportResize = () => {
     this.#callback();
   };
-  /** Stable bound handler for the capture-phase `load`; see {@link observeDescendantLoads}. */
   #handleDescendantLoad = () => {
     this.#callback();
   };
@@ -76,11 +75,6 @@ var LayoutObserver = class {
     this.#callback = callback;
     this.#resizeObserverFactory = options.resizeObserverFactory ?? (typeof ResizeObserver === "undefined" ? null : (cb) => new ResizeObserver(cb));
   }
-  /**
-   * Starts observing an element's size. Repeated calls observe additional
-   * elements through the same shared observer. No-ops when no
-   * `ResizeObserver` implementation is available.
-   */
   observe(element) {
     if (!this.#resizeObserverFactory) return;
     if (!this.#resizeObserver) {
@@ -90,47 +84,28 @@ var LayoutObserver = class {
     }
     this.#resizeObserver.observe(element);
   }
-  /** Stops observing a single element while leaving any others in place. */
   unobserve(element) {
     this.#resizeObserver?.unobserve(element);
   }
-  /** Starts observing viewport resizes. Idempotent: the listener is added once. */
   observeViewport() {
     if (this.#observingViewport) return;
     this.#observingViewport = true;
     window.addEventListener("resize", this.#handleViewportResize);
   }
-  /** Stops observing viewport resizes without affecting element observation. */
   unobserveViewport() {
     if (!this.#observingViewport) return;
     this.#observingViewport = false;
     window.removeEventListener("resize", this.#handleViewportResize);
   }
-  /**
-   * Starts reporting a `load` from anywhere inside `container` — an image or a
-   * frame settling changes the box it sits in, and it measures as zero high until
-   * then. `load` does not bubble, so the subscription is a capture-phase listener
-   * on the container itself and nothing the caller spells.
-   *
-   * **One container at a time.** A further call moves the observation, so a widget
-   * whose content element is swapped at runtime releases the element it let go by
-   * naming the new one — there is no second place for the release to drift from.
-   */
   observeDescendantLoads(container) {
     this.unobserveDescendantLoads();
     this.#loadContainer = container;
     container.addEventListener("load", this.#handleDescendantLoad, true);
   }
-  /** Stops reporting descendant loads without affecting element or viewport observation. */
   unobserveDescendantLoads() {
     this.#loadContainer?.removeEventListener("load", this.#handleDescendantLoad, true);
     this.#loadContainer = null;
   }
-  /**
-   * Releases every observation: disconnects the {@link ResizeObserver} and removes
-   * the viewport and descendant-load listeners. Safe to call multiple times. Call
-   * this from a controller's `disconnect()`.
-   */
   disconnect() {
     this.#resizeObserver?.disconnect();
     this.#resizeObserver = null;
@@ -139,7 +114,17 @@ var LayoutObserver = class {
   }
 };
 
-// src/utils/logical_scroll.ts
+var ListenerSet = class {
+  #abort = new AbortController();
+  add(target, type, handler, options) {
+    target.addEventListener(type, handler, { ...options, signal: this.#abort.signal });
+  }
+  dispose() {
+    this.#abort.abort();
+    this.#abort = new AbortController();
+  }
+};
+
 function isRtl(element) {
   return window.getComputedStyle(element).direction === "rtl";
 }
@@ -156,45 +141,149 @@ function physicalScrollDelta(element, horizontal, logicalDelta) {
   return horizontal && isRtl(element) ? -logicalDelta : logicalDelta;
 }
 
-// src/utils/reduced_motion.ts
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  constructor(run) {
+    this.#run = run;
+  }
+  activate() {
+    this.#active = true;
+  }
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  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();
+    });
+  }
+};
+
+var MorphRenderWatcher = class {
+  #listeners = new ListenerSet();
+  #pass;
+  #element = null;
+  #onMorph = () => this.#pass.schedule();
+  constructor(run) {
+    this.#pass = new MicrotaskCoalescer(run);
+  }
+  observe(element) {
+    if (this.#element === element) return;
+    this.disconnect();
+    this.#element = element;
+    this.#pass.activate();
+    this.#listeners.add(element, "turbo:morph-element", this.#onMorph);
+  }
+  schedule() {
+    this.#pass.schedule();
+  }
+  disconnect() {
+    this.#listeners.dispose();
+    this.#pass.cancel();
+    this.#element = null;
+  }
+};
+
+var NUMBER_BOUNDS = {
+  finite: { finite: true }};
+function matchesNumberBounds(value, bounds) {
+  if (!Number.isFinite(value)) {
+    const direction = value === Infinity ? "positive" : value === -Infinity ? "negative" : null;
+    if (direction === null) return false;
+    if (bounds.allowInfinity !== "both" && bounds.allowInfinity !== direction) return false;
+  }
+  if (bounds.min !== void 0 && value < bounds.min) return false;
+  if (bounds.max !== void 0 && value > bounds.max) return false;
+  if (bounds.exclusiveMin !== void 0 && value <= bounds.exclusiveMin) return false;
+  if (bounds.integer && !Number.isInteger(value)) return false;
+  if (bounds.allowedValues !== void 0 && !bounds.allowedValues.includes(value)) return false;
+  return true;
+}
+
+function readNumber(raw, fallback, bounds) {
+  return matchesNumberBounds(raw, bounds) ? raw : fallback;
+}
+
+var NumberValueReader = class {
+  #lastRejected = /* @__PURE__ */ new Map();
+  read(owner, name, raw, fallback, bounds) {
+    const resolved = readNumber(raw, fallback, bounds);
+    if (matchesNumberBounds(raw, bounds)) {
+      this.#lastRejected.delete(name);
+      return resolved;
+    }
+    const attribute = `data-${owner.identifier}-${name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}-value`;
+    const literal = owner.element.getAttribute(attribute);
+    if (literal === null) {
+      this.#lastRejected.delete(name);
+      return resolved;
+    }
+    if (this.#lastRejected.get(name) !== literal) {
+      this.#lastRejected.set(name, literal);
+      console.warn(
+        `Stimeo UI: "${owner.identifier}" has an invalid number Value "${name}" declaration ${JSON.stringify(literal)}; using ${fallback}.`
+      );
+    }
+    return resolved;
+  }
+};
+
 function prefersReducedMotion() {
   return typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
 }
 
-// src/controllers/overflow_indicator_controller.ts
-var DIRECTION_BUTTON_SELECTOR = "[data-stimeo--overflow-indicator-direction-param]";
-var OverflowIndicatorController = class extends Controller {
+var DIRECTION_PARAM = "direction-param";
+var OverflowIndicatorController = class _OverflowIndicatorController extends Controller {
+  #numbers = new NumberValueReader();
+  get #directionParam() {
+    return `data-${this.identifier}-${DIRECTION_PARAM}`;
+  }
+  get #directionButtonSelector() {
+    return `[${this.#directionParam}]`;
+  }
   static targets = ["viewport"];
   static values = {
     orientation: { type: String, default: "horizontal" },
     threshold: { type: Number, default: 1 }
   };
-  static actions = ["scrollByPage", "update"];
+  static valueConstraints = {
+    threshold: NUMBER_BOUNDS.finite
+  };
+  static actions = ["scrollByPage"];
   static events = ["change"];
   #layout = new LayoutObserver(() => {
-    if (this.#connected) this.update();
+    if (this.#connected) this.#refresh();
   });
+  #frames = new FrameCoalescer();
+  #viewportListeners = new ListenerSet();
+  #onScroll = () => this.#frames.schedule(() => this.#refresh());
   #connected = false;
   #observedViewport = null;
   #observedContent = /* @__PURE__ */ new Set();
   #mutationObserver = null;
-  /**
-   * Boundary buttons whose native `disabled` is held back while they hold focus.
-   *
-   * Completing the deferral is what actually disables the button, so the release
-   * callback — unlike {@link #cancelPendingButtonDisable} — applies it.
-   */
   #pendingButtonDisables = new BlurDeferral((button) => {
     this.#restorePendingMarkers(button);
     if (!button.disabled) this.#disableButton(button);
   });
-  /** Last reported room, so `change` fires only on transitions. */
   #state = null;
+  #morphRender = new MorphRenderWatcher(() => this.#refresh());
   connect() {
+    this.#morphRender.observe(this.element);
     this.#connected = true;
     this.#syncViewport();
   }
   disconnect() {
+    this.#morphRender.disconnect();
     this.#connected = false;
     this.#stopObservingViewport();
     this.#layout.disconnect();
@@ -209,16 +298,12 @@ var OverflowIndicatorController = class extends Controller {
     this.#syncViewport();
   }
   orientationValueChanged() {
-    if (this.#connected) this.update();
+    if (this.#connected) this.#refresh();
   }
   thresholdValueChanged() {
-    if (this.#connected) this.update();
+    if (this.#connected) this.#refresh();
   }
-  /**
-   * Re-measures remaining scroll room and reflects the state hooks.
-   * Public so it can be wired to the viewport's `scroll`.
-   */
-  update() {
+  #refresh() {
     if (!this.hasViewportTarget) return;
     const vp = this.viewportTarget;
     const horizontal = this.orientationValue !== "vertical";
@@ -234,7 +319,6 @@ var OverflowIndicatorController = class extends Controller {
       this.dispatch("change", { detail: { start, end } });
     }
   }
-  /** Scrolls one viewport page toward the `direction` param (`start`/`end`). */
   scrollByPage(event) {
     if (!this.hasViewportTarget) return;
     const direction = this.#directionFromEvent(event);
@@ -252,29 +336,22 @@ var OverflowIndicatorController = class extends Controller {
       vp.scrollBy({ top: delta, behavior });
     }
   }
-  /** Mirrors remaining room onto any direction buttons by toggling `disabled`. */
   #syncButtons(start, end) {
     for (const button of this.#pendingButtonDisables.elements) {
-      if (!button.isConnected || button.closest("[data-controller~='stimeo--overflow-indicator']") !== this.element) {
+      if (!button.isConnected || button.closest(`[data-controller~='${this.identifier}']`) !== this.element) {
         this.#cancelPendingButtonDisable(button);
       }
     }
-    const buttons = this.element.querySelectorAll(DIRECTION_BUTTON_SELECTOR);
+    const buttons = this.element.querySelectorAll(this.#directionButtonSelector);
     for (const button of buttons) {
-      if (button.closest("[data-controller~='stimeo--overflow-indicator']") !== this.element) {
+      if (button.closest(`[data-controller~='${this.identifier}']`) !== this.element) {
         continue;
       }
-      const direction = button.getAttribute("data-stimeo--overflow-indicator-direction-param");
+      const direction = button.getAttribute(this.#directionParam);
       if (direction === "start") this.#toggleButton(button, start);
       else if (direction === "end") this.#toggleButton(button, end);
     }
   }
-  /**
-   * Reflects the remaining room onto a page button's `disabled`, owning only the
-   * `disabled` it sets itself via a marker (`data-overflow-indicator-disabled`,
-   * like `number-input`/`conditional-fields`). An author-disabled button (e.g. the
-   * whole control disabled) is therefore never blindly re-enabled.
-   */
   #toggleButton(button, hasRoom) {
     if (!this.#pendingButtonDisables.has(button) && button.hasAttribute("data-overflow-indicator-pending-disabled")) {
       this.#cancelPendingButtonDisable(button);
@@ -294,10 +371,6 @@ var OverflowIndicatorController = class extends Controller {
       this.#disableButton(button);
     }
   }
-  /**
-   * Keeps a boundary button focusable until native blur, exposing its temporary
-   * inoperability with `aria-disabled` and making its action a no-op meanwhile.
-   */
   #deferButtonDisable(button) {
     if (this.#pendingButtonDisables.has(button)) return;
     button.setAttribute("data-overflow-indicator-pending-disabled", "");
@@ -312,18 +385,10 @@ var OverflowIndicatorController = class extends Controller {
     button.disabled = true;
     button.setAttribute("data-overflow-indicator-disabled", "");
   }
-  /** Cancels a pending disable without applying it, restoring the displaced state. */
   #cancelPendingButtonDisable(button) {
     this.#pendingButtonDisables.release(button);
     this.#restorePendingMarkers(button);
   }
-  /**
-   * Drops the pending marker and gives back the `aria-disabled` it displaced.
-   *
-   * Reads the displaced value from the DOM rather than memory: a Turbo snapshot is
-   * cloned before `disconnect()` runs, so a restored page can arrive with markers
-   * this instance never wrote.
-   */
   #restorePendingMarkers(button) {
     button.removeAttribute("data-overflow-indicator-pending-disabled");
     const displaced = button.getAttribute("data-overflow-indicator-aria-disabled");
@@ -340,7 +405,6 @@ var OverflowIndicatorController = class extends Controller {
       this.#cancelPendingButtonDisable(button);
     }
   }
-  /** Moves resize/mutation/load observation to the current viewport target. */
   #syncViewport() {
     if (!this.#connected) return;
     const next = this.hasViewportTarget ? this.viewportTarget : null;
@@ -348,6 +412,7 @@ var OverflowIndicatorController = class extends Controller {
     this.#stopObservingViewport();
     if (!next) return;
     this.#observedViewport = next;
+    this.#viewportListeners.add(next, "scroll", this.#onScroll, { passive: true });
     this.#layout.observe(next);
     this.#layout.observeViewport();
     this.#layout.observeDescendantLoads(next);
@@ -356,7 +421,7 @@ var OverflowIndicatorController = class extends Controller {
       this.#mutationObserver = new MutationObserver(() => {
         if (!this.#connected || this.#observedViewport !== next) return;
         this.#syncContentObservation();
-        this.update();
+        this.#refresh();
       });
       this.#mutationObserver.observe(this.element, {
         childList: true,
@@ -367,9 +432,8 @@ var OverflowIndicatorController = class extends Controller {
       });
     }
     this.#state = null;
-    this.update();
+    this.#refresh();
   }
-  /** Observes direct content boxes whose resize can change the viewport's scroll extent. */
   #syncContentObservation() {
     const next = new Set(this.#observedViewport?.children ?? []);
     for (const content of this.#observedContent) {
@@ -386,6 +450,8 @@ var OverflowIndicatorController = class extends Controller {
     }
   }
   #stopObservingViewport() {
+    this.#frames.cancel();
+    this.#viewportListeners.dispose();
     this.#mutationObserver?.disconnect();
     this.#mutationObserver = null;
     this.#layout.unobserveDescendantLoads();
@@ -396,16 +462,24 @@ var OverflowIndicatorController = class extends Controller {
     this.#layout.unobserveViewport();
   }
   get #threshold() {
-    const value = this.thresholdValue;
-    return Number.isFinite(value) ? Math.max(0, value) : 1;
+    const value = this.#safeThreshold;
+    return Math.max(0, value);
   }
   #directionFromEvent(event) {
     const params = event.params;
     const direction = params?.direction;
     return direction === "start" || direction === "end" ? direction : null;
   }
+  get #safeThreshold() {
+    return this.#numbers.read(
+      this,
+      "threshold",
+      this.thresholdValue,
+      _OverflowIndicatorController.values.threshold.default,
+      _OverflowIndicatorController.valueConstraints.threshold
+    );
+  }
 };
 
 export { OverflowIndicatorController };
-//# sourceMappingURL=overflow_indicator_controller.js.map
 //# sourceMappingURL=overflow_indicator_controller.js.map