stimeo-ui 0.16.0 → 0.17.0

data/dist/controllers/breadcrumb_controller.js

@@ -1,30 +1,20 @@
 import { Controller } from '@hotwired/stimulus';
 
-// src/controllers/breadcrumb_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,15 @@ var BlurDeferral = 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();
   };
@@ -76,11 +59,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 +68,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,30 +98,23 @@ var LayoutObserver = class {
   }
 };
 
-// src/controllers/breadcrumb_controller.ts
 var OVERFLOW_EPSILON = 1;
 var BreadcrumbController = class extends Controller {
   static targets = ["list", "collapsible", "ellipsis", "trigger"];
   static actions = ["toggle", "update"];
   static events = ["toggle"];
-  /** Guards target callbacks that can fire outside the connected window. */
   #connected = false;
-  /** Whether the trail currently overflows its container. */
   #overflowing = false;
-  /** Whether the user has expanded the collapsed items via the disclosure. */
   #expanded = false;
-  /** The list element currently observed (resize + mutations), if any. */
   #observedList = null;
   #listMutations = null;
   #layout = new LayoutObserver(() => this.update());
   #onListMutation = () => {
     this.update();
   };
-  /** Holds the ellipsis hide back while it contains focus; re-renders on blur. */
   #deferredHide = new BlurDeferral(() => {
     this.#render();
   });
-  /** Starts observing for overflow and renders the initial state. */
   connect() {
     this.#connected = true;
     this.#expanded = this.#initialExpanded();
@@ -170,7 +122,6 @@ var BreadcrumbController = class extends Controller {
     this.#syncListObservation();
     this.update();
   }
-  /** Releases the resize/mutation observation (Turbo navigation included). */
   disconnect() {
     this.#connected = false;
     this.#deferredHide.releaseAll();
@@ -186,91 +137,42 @@ var BreadcrumbController = class extends Controller {
   collapsibleTargetConnected() {
     this.#resync();
   }
-  /**
-   * Re-measures when an `ellipsis` target arrives. The `ellipsis` and `trigger`
-   * targets form the disclosure set, a precondition for collapsing at all, so they
-   * need the same watching the list and items get: without their callbacks a swap
-   * that breaks or completes the set would only take effect at the next resize or
-   * list mutation, which may never come.
-   */
   ellipsisTargetConnected() {
     this.#resync();
   }
-  /** Re-measures when an `ellipsis` target leaves the disclosure set. */
   ellipsisTargetDisconnected() {
     this.#resync();
   }
-  /** Re-measures when a `trigger` target joins the disclosure set. */
   triggerTargetConnected() {
     this.#resync();
   }
-  /** Re-measures when a `trigger` target leaves the disclosure set. */
   triggerTargetDisconnected() {
     this.#resync();
   }
-  /**
-   * Hands `hidden` back when an element stops being a `collapsible` target.
-   *
-   * The marker is the source of truth for what may be collapsed, so an element
-   * that loses it while the controller is live is an always-visible item again —
-   * and rendering only walks the *current* targets, so nothing else would ever
-   * clear the `hidden` this controller put there.
-   *
-   * The `#connected` guard is load-bearing, not defensive. Stimulus fires this
-   * callback for **every** target during teardown as well (`Context.disconnect()`
-   * stops the target observer after `disconnect()` has run), and there the
-   * collapsed DOM must survive untouched so Turbo's cache restores the trail in
-   * the state the user left it (see the ownership note in {@link BreadcrumbController}).
-   *
-   * @param element - the element that just left the `collapsible` target set
-   */
   collapsibleTargetDisconnected(element) {
     if (this.#connected) element.hidden = false;
     this.#resync();
   }
-  /**
-   * Expands or re-collapses the trail and dispatches `toggle`.
-   *
-   * No-op while the trail fits: there is nothing collapsed to reveal, and the
-   * (hidden) trigger would otherwise keep a stale `aria-expanded="true"` that
-   * surfaces pre-expanded the next time the trail overflows. No event is
-   * dispatched in that case.
-   */
   toggle() {
     if (!this.#connected || !this.#overflowing) return;
     this.#expanded = !this.#expanded;
     this.#render();
     this.dispatch("toggle", { detail: { expanded: this.#expanded } });
   }
-  /**
-   * Re-measures overflow and re-renders. Wired to resizes and list mutations;
-   * exposed as an action so consumers can re-measure after a change the
-   * observers cannot see (e.g. a web font swap that only alters text width).
-   */
   update() {
     if (!this.#connected) return;
     this.#overflowing = this.#measureOverflow();
     if (!this.#overflowing) this.#expanded = false;
     this.#render();
   }
-  /** Re-attaches the list observation (targets may have been swapped) and re-measures. */
   #resync() {
     if (!this.#connected) return;
     this.#syncListObservation();
     this.update();
   }
-  /** Reads the expanded state back from its DOM home (the trigger's `aria-expanded`). */
   #initialExpanded() {
     return this.hasTriggerTarget && this.triggerTarget.getAttribute("aria-expanded") === "true";
   }
-  /**
-   * Points the resize + mutation observation at the current `list` target.
-   *
-   * The list is re-resolved rather than captured at connect so a target swapped
-   * at runtime (Turbo Stream replacement of the `<ol>`) is observed too. Only
-   * `childList` / `subtree` / `characterData` are watched — deliberately **not**
-   * `attributes`, which the controller's own `hidden` writes would re-trigger.
-   */
   #syncListObservation() {
     const next = this.hasListTarget ? this.listTarget : null;
     if (next === this.#observedList) return;
@@ -289,26 +191,6 @@ var BreadcrumbController = class extends Controller {
     this.#listMutations?.disconnect();
     this.#listMutations = null;
   }
-  /**
-   * Measures overflow against the **fully expanded** layout so hiding items does
-   * not make the condition oscillate. Reveals every item, then compares the list's
-   * own scroll width to its own client width; `#render` immediately re-applies
-   * the correct hidden state afterward.
-   *
-   * Both widths are read from the list element itself (not the host `nav`) so the
-   * check is independent of any padding/border on the host — comparing against the
-   * host's `clientWidth` would over-report the available space by its padding and
-   * miss real overflow in a padded container.
-   *
-   * With no `collapsible` items there is nothing to collapse, so the trail is
-   * never reported as overflowing (which also keeps the disclosure out of the
-   * tab order — a button controlling nothing).
-   *
-   * The full disclosure set is a precondition: collapsing without an `ellipsis`
-   * *and* a `trigger` would hide items behind a control that does not exist, so
-   * an incomplete set reports "not overflowing" and `#render` degrades the trail
-   * to a plain breadcrumb. Losing layout is recoverable; losing the path is not.
-   */
   #measureOverflow() {
     if (!this.hasListTarget || this.collapsibleTargets.length === 0) return false;
     if (!this.hasEllipsisTarget || !this.hasTriggerTarget) return false;
@@ -316,9 +198,6 @@ var BreadcrumbController = class extends Controller {
     this.ellipsisTarget.hidden = true;
     return this.listTarget.scrollWidth > this.listTarget.clientWidth + OVERFLOW_EPSILON;
   }
-  /**
-   * Applies the collapsed/expanded state to the items, ellipsis, and trigger.
-   */
   #render() {
     const collapsed = this.#overflowing && !this.#expanded;
     const showEllipsis = this.#overflowing && this.collapsibleTargets.length > 0;
@@ -331,13 +210,6 @@ var BreadcrumbController = class extends Controller {
     }
     if (rescueFocus) this.triggerTarget.focus();
   }
-  /**
-   * Shows or hides the ellipsis item, deferring a hide that would blur the user.
-   *
-   * Hiding the element that currently holds focus drops focus to `<body>`, so the
-   * hide waits for that element's `blur` and is re-applied then (the shared
-   * `BlurDeferral` registry).
-   */
   #applyEllipsisVisibility(show) {
     const ellipsis = this.ellipsisTarget;
     if (show) {
@@ -354,7 +226,6 @@ var BreadcrumbController = class extends Controller {
     this.#deferredHide.releaseAll();
     ellipsis.hidden = true;
   }
-  /** Whether `element` contains (or is) the currently focused element. */
   #holdsFocus(element) {
     const active = document.activeElement;
     return active instanceof HTMLElement && element.contains(active);
@@ -362,5 +233,4 @@ var BreadcrumbController = class extends Controller {
 };
 
 export { BreadcrumbController };
-//# sourceMappingURL=breadcrumb_controller.js.map
 //# sourceMappingURL=breadcrumb_controller.js.map