stimeo-ui 0.16.0 → 0.18.0

package/dist/controllers/overflow_indicator_controller.d.ts

@@ -50,6 +50,11 @@ declare class OverflowIndicatorController extends Controller<HTMLElement> {
             default: number;
         };
     };
+    static valueConstraints: {
+        threshold: {
+            readonly finite: true;
+        };
+    };
     static actions: readonly ["scrollByPage"];
     static events: readonly ["change"];
     readonly viewportTarget: HTMLElement;

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,14 +43,8 @@ var BlurDeferral = class {
   }
 };
 
-// src/utils/frame_coalescer.ts
 var FrameCoalescer = class {
   #frame = null;
-  /**
-   * Runs `run` on the next frame, unless a frame is already pending — the first
-   * request of a burst wins and the rest are dropped. The pending frame is
-   * released before `run`, so `run` may request the next one.
-   */
   schedule(run) {
     if (this.#frame !== null) return;
     this.#frame = requestAnimationFrame(() => {
@@ -72,14 +52,6 @@ var FrameCoalescer = class {
       run();
     });
   }
-  /**
-   * Drops the pending frame, and reaches the platform only when there is one.
-   *
-   * There is no handle value that stands for "nothing pending":
-   * `cancelAnimationFrame` takes an `unsigned long`, so a negative placeholder
-   * arrives as a large positive number that the same allocator can hand out, and
-   * an idle cancel would then drop a frame belonging to someone else.
-   */
   cancel() {
     if (this.#frame === null) return;
     cancelAnimationFrame(this.#frame);
@@ -87,18 +59,15 @@ var FrameCoalescer = class {
   }
 };
 
-// src/utils/layout_observer.ts
 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();
   };
@@ -106,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) {
@@ -120,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;
@@ -169,31 +114,17 @@ var LayoutObserver = class {
   }
 };
 
-// src/utils/listener_set.ts
 var ListenerSet = class {
-  /** The generation every `add` joins until the next `dispose()`. */
   #abort = new AbortController();
-  /**
-   * Attaches `handler` to the open generation, exactly as the caller spelled it.
-   *
-   * The set supplies the signal, so `options` carries everything else the DOM
-   * accepts — `capture` included, which has to match at release time and no
-   * longer has a second place to drift from.
-   */
   add(target, type, handler, options) {
     target.addEventListener(type, handler, { ...options, signal: this.#abort.signal });
   }
-  /**
-   * Releases every listener of the open generation, synchronously, and opens the
-   * next one. Idempotent, and safe before anything has been added.
-   */
   dispose() {
     this.#abort.abort();
     this.#abort = new AbortController();
   }
 };
 
-// src/utils/logical_scroll.ts
 function isRtl(element) {
   return window.getComputedStyle(element).direction === "rtl";
 }
@@ -210,19 +141,119 @@ 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;
+  }
+  get pending() {
+    return this.#queued;
+  }
+  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();
+  }
+  get pending() {
+    return this.#pass.pending;
+  }
+  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_PARAM = "direction-param";
-var OverflowIndicatorController = class extends Controller {
-  /** The direction param above, in the namespace this controller is registered under. */
+var OverflowIndicatorController = class _OverflowIndicatorController extends Controller {
+  #numbers = new NumberValueReader();
   get #directionParam() {
     return `data-${this.identifier}-${DIRECTION_PARAM}`;
   }
-  /** Selects every button carrying that param. */
   get #directionButtonSelector() {
     return `[${this.#directionParam}]`;
   }
@@ -231,37 +262,34 @@ var OverflowIndicatorController = class extends Controller {
     orientation: { type: String, default: "horizontal" },
     threshold: { type: Number, default: 1 }
   };
+  static valueConstraints = {
+    threshold: NUMBER_BOUNDS.finite
+  };
   static actions = ["scrollByPage"];
   static events = ["change"];
   #layout = new LayoutObserver(() => {
     if (this.#connected) this.#refresh();
   });
-  /** Folds a burst of scrolls into one measurement per frame. */
   #frames = new FrameCoalescer();
-  /** Holds the viewport's scroll listener for exactly as long as that viewport. */
   #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();
@@ -281,11 +309,6 @@ var OverflowIndicatorController = class extends Controller {
   thresholdValueChanged() {
     if (this.#connected) this.#refresh();
   }
-  /**
-   * Re-measures remaining scroll room and reflects the state hooks.
-   *
-   * @stimeoRenderRoot
-   */
   #refresh() {
     if (!this.hasViewportTarget) return;
     const vp = this.viewportTarget;
@@ -302,7 +325,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);
@@ -320,7 +342,6 @@ 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~='${this.identifier}']`) !== this.element) {
@@ -337,12 +358,6 @@ var OverflowIndicatorController = class extends Controller {
       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);
@@ -362,10 +377,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", "");
@@ -380,18 +391,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");
@@ -408,7 +411,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;
@@ -438,7 +440,6 @@ var OverflowIndicatorController = class extends Controller {
     this.#state = null;
     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) {
@@ -467,16 +468,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