stimeo-ui 0.16.0 → 0.18.0

package/dist/controllers/stick_to_bottom_controller.js

@@ -1,19 +1,14 @@
 import { Controller } from '@hotwired/stimulus';
 
-// src/controllers/stick_to_bottom_controller.ts
-
-// 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();
   };
@@ -21,11 +16,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) {
@@ -35,47 +25,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;
@@ -84,21 +55,155 @@ var LayoutObserver = class {
   }
 };
 
-// src/utils/reduced_motion.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();
+  }
+};
+
+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 = {
+  nonNegative: { finite: true, min: 0 }};
+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/utils/state_regions.ts
-var StateRegions = class {
+function setAttributeIfChanged(element, name, value, beforeWrite) {
+  if (element.getAttribute(name) === value) return false;
+  if (value === null) element.removeAttribute(name);
+  else element.setAttribute(name, value);
+  return true;
+}
+
+function sharedRegistry(key, create) {
+  const symbol = Symbol.for(key);
+  const scope = globalThis;
+  const existing = scope[symbol];
+  if (existing !== void 0) return existing;
+  const registry = create();
+  Object.defineProperty(globalThis, symbol, { value: registry });
+  return registry;
+}
+
+var StateRegions = class _StateRegions {
+  static #registry = sharedRegistry(
+    "stimeo-ui.state-regions.registry.v1",
+    () => ({ stacks: /* @__PURE__ */ new WeakMap(), names: /* @__PURE__ */ new Set() })
+  );
   #whenTrue;
   #whenFalse;
-  #taken = /* @__PURE__ */ new WeakSet();
-  constructor(options) {
+  #record;
+  constructor(options, owner) {
     this.#whenTrue = options.whenTrue;
     this.#whenFalse = options.whenFalse ?? null;
+    this.#record = `data-${owner}-hidden-region`;
+    _StateRegions.#registry.names.add(this.#record);
   }
-  /** 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) {
@@ -114,112 +219,192 @@ var StateRegions = class {
     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. */
+  release(host) {
+    for (const region of [host, ...host.querySelectorAll("*")]) {
+      if (!(region instanceof HTMLElement)) continue;
+      const stack = this.#held(region);
+      const hold = stack && this.#take(stack);
+      if (!stack || !hold) continue;
+      const owns = region.hidden === hold.written && !this.#covered(region, stack, hold);
+      const index = stack.indexOf(hold);
+      stack.splice(index, 1);
+      const above = stack[index];
+      if (above) above.linked &&= hold.linked;
+      if (owns) {
+        const below = hold.linked ? stack[index - 1] : void 0;
+        if (below) {
+          if (region.hidden !== below.written) region.hidden = below.written;
+        } else {
+          setAttributeIfChanged(region, "hidden", hold.authored);
+        }
+      }
+      this.#mark(region, stack);
+    }
+  }
   #write(region, hidden) {
-    if (hidden) this.#taken.add(region);
-    else this.#taken.delete(region);
-    if (region.hidden !== hidden) region.hidden = hidden;
+    const stack = this.#stack(region);
+    const hold = this.#take(stack) ?? this.#acquire(region, stack);
+    const shows = !this.#covered(region, stack, hold);
+    hold.written = hidden;
+    if (shows && region.hidden !== hidden) region.hidden = hidden;
+    this.#mark(region, stack);
   }
-  /** Returns a region this instance hid; one it never hid keeps what it carries. */
   #give(region) {
-    if (this.#taken.delete(region)) region.hidden = false;
+    const stack = this.#held(region);
+    if (stack && this.#take(stack)?.written) this.#write(region, false);
+  }
+  #held(region) {
+    return _StateRegions.#registry.stacks.has(region) || region.hasAttribute(this.#record) ? this.#stack(region) : void 0;
+  }
+  #stack(region) {
+    const stacks = _StateRegions.#registry.stacks;
+    const stack = stacks.get(region) ?? this.#seed(region);
+    stacks.set(region, stack);
+    return stack;
+  }
+  #seed(region) {
+    const found = [];
+    for (const record of _StateRegions.#registry.names) {
+      const read = this.#recorded(region, record);
+      if (read) found.push({ ...read, record });
+    }
+    const depth = ({ beneath }) => beneath.filter((name) => found.some((other) => other.record === name)).length;
+    return found.sort((one, other) => depth(one) - depth(other)).map(({ record, authored, written, linked }, index) => ({
+      instance: null,
+      record,
+      authored,
+      written,
+      linked: linked && index > 0
+    }));
+  }
+  #take(stack) {
+    const hold = stack.find((held) => held.instance === this) ?? stack.find((held) => held.instance === null && held.record === this.#record);
+    if (hold) hold.instance = this;
+    return hold;
+  }
+  #covered(region, stack, hold) {
+    return stack.slice(stack.indexOf(hold) + 1).some((above) => above.written === region.hidden);
+  }
+  #acquire(region, stack) {
+    const top = stack.at(-1);
+    const over = top && region.hidden === top.written ? top : void 0;
+    const hold = {
+      instance: this,
+      record: this.#record,
+      authored: over ? over.authored : region.getAttribute("hidden"),
+      written: false,
+      linked: over !== void 0
+    };
+    stack.push(hold);
+    return hold;
+  }
+  #mark(region, stack) {
+    const records = /* @__PURE__ */ new Map([[this.#record, null]]);
+    stack.forEach((hold, index) => {
+      const names = stack.slice(0, index).map((under) => under.record);
+      const beneath = [...new Set(names.reverse())].filter((name) => name !== hold.record);
+      const marker = hold.linked || beneath.length === 0 ? [] : [false];
+      records.set(
+        hold.record,
+        region.getAttribute("hidden") === hold.authored && beneath.length === 0 && index === stack.length - 1 ? null : JSON.stringify([hold.authored, hold.written, ...marker, ...beneath])
+      );
+    });
+    for (const [name, recorded] of records) {
+      setAttributeIfChanged(region, name, recorded);
+    }
+  }
+  #recorded(region, name) {
+    try {
+      const parsed = JSON.parse(region.getAttribute(name) ?? "null");
+      if (!Array.isArray(parsed)) return null;
+      const [authored, written, ...rest] = parsed;
+      if (authored !== null && typeof authored !== "string") return null;
+      const linked = rest[0] !== false;
+      const beneath = linked ? rest : rest.slice(1);
+      if (!beneath.every((under) => typeof under === "string")) return null;
+      return typeof written === "boolean" ? { authored, written, linked, beneath } : null;
+    } catch {
+      return null;
+    }
   }
-  /** 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/stick_to_bottom_controller.ts
 var DEFAULT_THRESHOLD = 80;
 var countElements = (nodes) => {
   let n = 0;
   for (const node of nodes) if (node.nodeType === Node.ELEMENT_NODE) n += 1;
   return n;
 };
-var StickToBottomController = class extends Controller {
+var StickToBottomController = class _StickToBottomController extends Controller {
+  #numbers = new NumberValueReader();
   static targets = ["content", "hasNew"];
   static values = {
     threshold: { type: Number, default: DEFAULT_THRESHOLD },
     behavior: { type: String, default: "auto" },
     pinOnConnect: { type: Boolean, default: false }
   };
+  static valueConstraints = {
+    threshold: NUMBER_BOUNDS.nonNegative
+  };
   static actions = ["scrollToBottom"];
   static events = ["pin", "new"];
   #observer = null;
-  /** The element the append observer currently holds, so a swap can be detected. */
   #watched = null;
-  /** Watches for the box a container connected without one is still waiting on. */
   #layout = new LayoutObserver(() => this.#onLaidOut());
   #awaitingLayout = false;
   #connected = false;
   #pinned = false;
   #hasNew = false;
-  /** Owns `hidden` on the regions declared for the has-new state. */
-  #hasNewRegion = new StateRegions({ whenTrue: () => this.hasNewTargets });
+  #hasNewRegion = new StateRegions(
+    { whenTrue: () => this.hasNewTargets },
+    this.identifier
+  );
   #onScroll = () => this.#updatePinned();
+  #morphRender = new MorphRenderWatcher(() => {
+    this.#updatePinned();
+    this.#setHasNew(this.#hasNew);
+  });
+  #listeners = new ListenerSet();
   connect() {
+    this.#morphRender.observe(this.element);
     this.#connected = true;
     if (this.pinOnConnectValue && this.#measurable()) this.#scrollToBottom("instant");
     this.#setHasNew(false);
     this.#pinned = this.#isPinned();
     this.#reflectPinned();
-    this.element.addEventListener("scroll", this.#onScroll, { passive: true });
+    this.#listeners.add(this.element, "scroll", this.#onScroll, { passive: true });
     this.#syncWatched();
     if (!this.#measurable()) this.#waitForLayout();
   }
   disconnect() {
+    this.#morphRender.disconnect();
     this.#connected = false;
-    this.element.removeEventListener("scroll", this.#onScroll);
+    this.#listeners.dispose();
     this.#stopWatching();
     this.#stopWaitingForLayout();
   }
-  /** Moves the append watch onto a `content` target that arrived at runtime. */
   contentTargetConnected() {
     this.#syncWatched();
   }
-  /** Moves the append watch off a `content` target that left, back onto the container. */
   contentTargetDisconnected() {
     this.#syncWatched();
   }
-  /**
-   * Settles a has-new region that arrived at runtime on the side the flag is currently
-   * on, the way a region present at connect is settled by the connect-time normalization.
-   *
-   * Stimulus attaches targets before `connect()`, and a container that leaves the document
-   * and comes back keeps its controller, so in that window the flag still reads the
-   * arrival of the connection that ended. A region attached there is left to the
-   * connect-time normalization, which drops the flag and settles the region in one write.
-   */
   hasNewTargetConnected() {
     if (!this.#connected) return;
     this.#hasNewRegion.reflect(this.element, this.#hasNew);
   }
-  /**
-   * Re-derives pinned when the distance that counts as the bottom is changed at runtime
-   * (a morph that swaps the attribute on a retained element).
-   */
   thresholdValueChanged() {
     if (!this.#connected) return;
     this.#updatePinned();
   }
-  /**
-   * Jumps to the bottom and re-pins (wired to a "new messages" button).
-   *
-   * The has-new flag clears on request — the user has acknowledged the arrival — while
-   * pinned is read back from where the scroll landed: a jump that arrives by the time
-   * this returns pins immediately, an animated one settles from its own scroll events,
-   * and a jump the engine cannot honor leaves the container unpinned, so the next append
-   * flags it again instead of being swallowed by a pinned state that does not hold.
-   *
-   * Which of those happens is not this method's to decide — see {@link behaviorValue}.
-   */
   scrollToBottom() {
     this.#scrollToBottom();
     this.#setHasNew(false);
     this.#updatePinned();
   }
-  /** Follows appended children while pinned; otherwise flags new content. */
   #onMutations(mutations) {
     let added = 0;
     for (const mutation of mutations) added += countElements(mutation.addedNodes);
@@ -231,19 +416,13 @@ var StickToBottomController = class extends Controller {
       this.dispatch("new", { detail: { count: added } });
     }
   }
-  /**
-   * Recomputes pinned from the scroll position and reflects it on a transition.
-   *
-   * @stimeoRenderRoot
-   */
   #updatePinned() {
     const pinned = this.#isPinned();
-    if (pinned === this.#pinned) return;
+    const changed = pinned !== this.#pinned;
     this.#pinned = pinned;
     this.#reflectPinned();
-    this.dispatch("pin", { detail: { pinned } });
+    if (changed) this.dispatch("pin", { detail: { pinned } });
   }
-  /** Mirrors the current `#pinned` onto the state hooks (clearing has-new once pinned). */
   #reflectPinned() {
     if (this.#pinned) {
       this.element.setAttribute("data-pinned", "true");
@@ -252,10 +431,6 @@ var StickToBottomController = class extends Controller {
       this.element.removeAttribute("data-pinned");
     }
   }
-  /**
-   * Mirrors whether content has arrived that the container did not follow onto the state
-   * hook and onto the regions declared for that state.
-   */
   #setHasNew(hasNew) {
     this.#hasNew = hasNew;
     if (hasNew) {
@@ -265,61 +440,31 @@ var StickToBottomController = class extends Controller {
     }
     this.#hasNewRegion.reflect(this.element, hasNew);
   }
-  /** Whether the container currently sits within `threshold` of its bottom. */
   #isPinned() {
     if (!this.#measurable()) return false;
     const el = this.element;
     return el.scrollHeight - el.clientHeight - el.scrollTop <= this.#threshold;
   }
-  /**
-   * The distance from the bottom that counts as pinned: a finite, non-negative number of
-   * pixels. Anything else names no distance the container can be at, and settles the
-   * comparison the same way at every scroll position, so it falls back to the default.
-   * `Number` reads `"abc"` as `NaN` and every comparison against it is false; a negative
-   * distance sits below the closest the container ever gets; `Infinity` is never
-   * exceeded. The first two stop following and flag every append as new, and the last
-   * never stops following — it takes the reading position the flag exists to protect.
-   * Zero is a real declaration: it pins at the exact bottom only.
-   */
   get #threshold() {
-    const declared = this.thresholdValue;
-    return Number.isFinite(declared) && declared >= 0 ? declared : DEFAULT_THRESHOLD;
-  }
-  /**
-   * Whether the container has a box to scroll and to measure. One that is not rendered
-   * (inside a closed panel) reports every metric as 0, which reads as "already at the
-   * bottom" — a position describing no layout the user will ever see.
-   */
+    return this.#safeThreshold;
+  }
   #measurable() {
     return this.element.clientHeight > 0;
   }
-  /**
-   * Holds the pinned decision until the container is laid out — otherwise the panel opens
-   * at the top while the state claims the bottom, and the appends that arrived meanwhile
-   * were followed into a box that could not move rather than flagged.
-   */
   #waitForLayout() {
     this.#awaitingLayout = true;
     this.#layout.observe(this.element);
   }
-  /** Runs the held decision once the container has the box it was waiting for. */
   #onLaidOut() {
     if (!this.#awaitingLayout || !this.#measurable()) return;
     this.#stopWaitingForLayout();
     if (this.pinOnConnectValue) this.#scrollToBottom("instant");
     this.#updatePinned();
   }
-  /** Releases the layout watch, whether or not the held decision ever ran. */
   #stopWaitingForLayout() {
     this.#awaitingLayout = false;
     this.#layout.disconnect();
   }
-  /**
-   * Scrolls to the bottom, clamped by the engine to the maximum scroll offset — which is
-   * 0 for a container tall enough to hold its whole content, so the jump moves nothing
-   * there. `behavior` defaults to the configured follow behavior; pass `"instant"` for a
-   * jump that must not animate.
-   */
   #scrollToBottom(behavior = this.#behavior()) {
     const top = this.element.scrollHeight;
     if (typeof this.element.scrollTo === "function") {
@@ -328,17 +473,6 @@ var StickToBottomController = class extends Controller {
       this.element.scrollTop = top;
     }
   }
-  /**
-   * Points the append watch at the current `content` target, or at the container when
-   * there is none. Re-resolved whenever that target changes, so a swap does not leave the
-   * observer holding a detached node whose appends nobody sees.
-   *
-   * Stimulus runs the target callbacks outside the connected window too — before
-   * `connect()` for a target already in the DOM, and after `disconnect()` while the
-   * element is torn down — where this would arm an observer nothing releases. Re-syncing
-   * to the target already held is left alone, so an arrival still in flight is not
-   * dropped with the observer that was about to deliver it.
-   */
   #syncWatched() {
     if (!this.#connected) return;
     const next = this.hasContentTarget ? this.contentTarget : this.element;
@@ -349,24 +483,25 @@ var StickToBottomController = class extends Controller {
     this.#observer = new MutationObserver((mutations) => this.#onMutations(mutations));
     this.#observer.observe(next, { childList: true });
   }
-  /** Releases the append watch and the element it held. */
   #stopWatching() {
     this.#observer?.disconnect();
     this.#observer = null;
     this.#watched = null;
   }
-  /**
-   * The behavior a follow-scroll runs with. `"auto"` is **not** a request to arrive at
-   * once: it hands the decision to the element's computed `scroll-behavior`, so a
-   * consumer stylesheet saying `smooth` animates these scrolls too. Only `"instant"`
-   * overrides that CSS, which is why reduced motion and the `pinOnConnect` jump name it.
-   */
   #behavior() {
     if (prefersReducedMotion()) return "instant";
     return this.behaviorValue === "smooth" ? "smooth" : "auto";
   }
+  get #safeThreshold() {
+    return this.#numbers.read(
+      this,
+      "threshold",
+      this.thresholdValue,
+      _StickToBottomController.values.threshold.default,
+      _StickToBottomController.valueConstraints.threshold
+    );
+  }
 };
 
 export { StickToBottomController };
-//# sourceMappingURL=stick_to_bottom_controller.js.map
 //# sourceMappingURL=stick_to_bottom_controller.js.map