stimeo-ui 0.16.0 → 0.18.0

package/dist/controllers/pagination_controller.js

@@ -1,8 +1,27 @@
 import { Controller } from '@hotwired/stimulus';
 
-// src/controllers/pagination_controller.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";
+}
+
+function actionSource(source) {
+  if (source instanceof HTMLElement) {
+    return { event: null, host: source, origin: source, reason: "api" };
+  }
+  const event = source ?? null;
+  return {
+    event,
+    host: event?.currentTarget instanceof Element ? event.currentTarget : null,
+    origin: event?.target instanceof Element ? event.target : null,
+    reason: stateReasonFor(event)
+  };
+}
 
-// src/utils/focus_candidate.ts
 function inheritsFieldsetDisabled(control) {
   let fieldset = control.closest("fieldset[disabled]");
   while (fieldset) {
@@ -12,35 +31,60 @@ function inheritsFieldsetDisabled(control) {
   }
   return false;
 }
+function unslotted(element) {
+  return element.assignedSlot === null && element.parentElement?.shadowRoot != null;
+}
+function flatTreeParent(element) {
+  if (unslotted(element)) return null;
+  const parent = element.assignedSlot ?? element.parentNode;
+  if (parent instanceof ShadowRoot) return parent.host;
+  return parent instanceof Element ? parent : null;
+}
 function canTakeFocus(element) {
-  if (element.closest("[hidden], [inert]")) return false;
+  for (let node = element; node; node = flatTreeParent(node)) {
+    if (unslotted(node) || node.matches("[hidden], [inert]")) return false;
+  }
   if (element instanceof HTMLInputElement && element.type === "hidden") return false;
   if (!("disabled" in element)) return true;
   if (element.disabled) return false;
   return !inheritsFieldsetDisabled(element);
 }
+function deepActiveElement(ownerDocument) {
+  let active = ownerDocument.activeElement;
+  while (active?.shadowRoot?.activeElement) active = active.shadowRoot.activeElement;
+  return active;
+}
+
+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();
+  }
+};
 
-// src/utils/microtask_coalescer.ts
 var MicrotaskCoalescer = class {
   #run;
   #queued = false;
   #active = false;
   #generation = 0;
-  /** @param run - the single reconciliation pass, invoked at most once per batch. */
   constructor(run) {
     this.#run = run;
   }
-  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
   activate() {
     this.#active = true;
   }
-  /** Closes the window and drops any pending pass; call from `disconnect()`. */
   cancel() {
     this.#active = false;
     this.#queued = false;
     this.#generation += 1;
   }
-  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */
+  get pending() {
+    return this.#queued;
+  }
   schedule() {
     if (!this.#active || this.#queued) return;
     this.#queued = true;
@@ -53,171 +97,329 @@ var MicrotaskCoalescer = class {
   }
 };
 
-// src/utils/before_cache_reset.ts
-var BeforeCacheReset = class _BeforeCacheReset {
-  /** Every subscribed instance, iterated by the one shared document listener. */
-  static #subscribers = /* @__PURE__ */ new Set();
-  /** The shared listener; installed while at least one instance is subscribed. */
-  static #onBeforeCache = () => {
-    for (const subscriber of _BeforeCacheReset.#subscribers) subscriber.#rewind();
-  };
-  #rewind;
-  /** @param rewind - the pass that returns this controller's state to its initial form. */
-  constructor(rewind) {
-    this.#rewind = rewind;
+var MorphRenderWatcher = class {
+  #listeners = new ListenerSet();
+  #pass;
+  #element = null;
+  #onMorph = () => this.#pass.schedule();
+  constructor(run) {
+    this.#pass = new MicrotaskCoalescer(run);
   }
-  /** Subscribes to `turbo:before-cache`; call from `connect()`. Idempotent. */
-  activate() {
-    const first = _BeforeCacheReset.#subscribers.size === 0;
-    _BeforeCacheReset.#subscribers.add(this);
-    if (first) {
-      document.addEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
-    }
+  observe(element) {
+    if (this.#element === element) return;
+    this.disconnect();
+    this.#element = element;
+    this.#pass.activate();
+    this.#listeners.add(element, "turbo:morph-element", this.#onMorph);
   }
-  /** Unsubscribes; call from `disconnect()`. Safe when never subscribed. */
-  deactivate() {
-    _BeforeCacheReset.#subscribers.delete(this);
-    if (_BeforeCacheReset.#subscribers.size > 0) return;
-    document.removeEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
+  schedule() {
+    this.#pass.schedule();
+  }
+  get pending() {
+    return this.#pass.pending;
+  }
+  disconnect() {
+    this.#listeners.dispose();
+    this.#pass.cancel();
+    this.#element = null;
+  }
+};
+
+var MoveCounter = class {
+  #sequence = 0;
+  record() {
+    this.#sequence += 1;
+    return this.#sequence;
+  }
+  isLatest(token) {
+    return token === this.#sequence;
+  }
+};
+
+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;
   }
 };
 
-// src/utils/tabindex_loan.ts
-var TabindexLoan = 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 queryOpenDescendants(root, selector) {
+  const matches = [];
+  const roots = [root];
+  for (const scope of roots) {
+    matches.push(...scope.querySelectorAll(selector));
+    if (scope.nodeType === Node.ELEMENT_NODE) {
+      const shadow = scope.shadowRoot;
+      if (shadow) roots.push(shadow);
+    }
+    for (const element of scope.querySelectorAll("*")) {
+      if (element.shadowRoot) roots.push(element.shadowRoot);
+    }
+  }
+  return matches;
+}
+
+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;
+}
+
+function holdsFocus(element) {
+  return element.matches(":focus") || deepActiveElement(element.ownerDocument) === element;
+}
+var TabindexLoan = class _TabindexLoan {
+  static #registry = sharedRegistry(
+    "stimeo-ui.tabindex-loan.registry.v1",
+    () => ({ stacks: /* @__PURE__ */ new WeakMap(), names: /* @__PURE__ */ new Set() })
+  );
   #value;
+  #record;
+  #preserveFocus;
   #lent = /* @__PURE__ */ new Set();
-  /** Returns live loans before Turbo can copy them into its page snapshot. */
-  #beforeCache = new BeforeCacheReset(() => this.returnAll());
-  /**
-   * @param value - the `tabindex` to lend. `"-1"` (the default) is
-   *   programmatically focusable but not a Tab stop; `"0"` is a real Tab stop,
-   *   which a scroll region with no focusable content of its own needs.
-   */
-  constructor(value = "-1") {
+  constructor(value, owner, options = {}) {
     this.#value = value;
-  }
-  /** Lends `element` the value; no-ops when it already carries a `tabindex`. */
-  lend(element) {
-    if (element.hasAttribute("tabindex")) return;
-    element.setAttribute("tabindex", this.#value);
+    this.#record = `data-${owner}-tabindex-loan`;
+    this.#preserveFocus = options.preserveFocus === true;
+    _TabindexLoan.#registry.names.add(this.#record);
+  }
+  lend(element, options = {}) {
+    const stack = this.#stack(element);
+    const current = element.getAttribute("tabindex");
+    const held = stack.find((hold) => hold.loan === this) ?? stack.find(
+      (hold) => hold.loan === null && hold.record === this.#record && hold.value === this.#value
+    );
+    const linked = stack.at(-1)?.value === current;
+    if (!held && options.onlyIfUnfocusable && (current !== null || element.tabIndex >= 0)) return;
+    if (!held && current !== null && !linked) return;
     this.#lent.add(element);
-    this.#beforeCache.activate();
+    if (held) held.loan = this;
+    else stack.push({ loan: this, record: this.#record, value: this.#value, linked });
+    this.#mark(element, stack);
+    if (current === null || !held && current !== this.#value) {
+      element.setAttribute("tabindex", this.#value);
+    }
+  }
+  return(element) {
+    const stack = this.#stack(element);
+    const hold = stack.find((held) => held.loan === this) ?? stack.find(
+      (held) => held.loan === null && held.record === this.#record && held.value === this.#value
+    );
+    if (!hold) return false;
+    if (!this.#release(element, stack, hold, this.#preserveFocus)) {
+      hold.loan = this;
+      this.#lent.add(element);
+      return false;
+    }
+    this.#lent.delete(element);
+    return true;
   }
-  /** Takes back every loan whose value is still the one that was lent. */
   returnAll() {
-    for (const element of this.#lent) {
-      if (element.getAttribute("tabindex") === this.#value) element.removeAttribute("tabindex");
+    for (const element of Array.from(this.#lent)) this.return(element);
+  }
+  reclaim(element) {
+    if (element.getAttribute(this.#record) !== this.#value) return;
+    const stack = this.#stack(element);
+    const hold = stack.find((held) => held.loan === null && held.record === this.#record);
+    if (hold && !holdsFocus(element)) this.#release(element, stack, hold);
+  }
+  reclaimWithin(root) {
+    for (const element of queryOpenDescendants(root, `[${this.#record}]`)) {
+      this.reclaim(element);
+    }
+  }
+  #stack(element) {
+    const stacks = _TabindexLoan.#registry.stacks;
+    const stack = stacks.get(element) ?? this.#seed(element);
+    stacks.set(element, stack);
+    return stack;
+  }
+  #seed(element) {
+    const current = element.getAttribute("tabindex");
+    const holds = [];
+    for (const record of _TabindexLoan.#registry.names) {
+      const value = element.getAttribute(record);
+      if (value !== null) holds.push({ loan: null, record, value, linked: true });
+    }
+    holds.sort((one, other) => Number(one.value === current) - Number(other.value === current));
+    for (const [index, hold] of holds.entries()) hold.linked = index > 0;
+    return holds;
+  }
+  #release(element, stack, hold, preserveFocus = false) {
+    const current = element.getAttribute("tabindex");
+    const index = stack.indexOf(hold);
+    const owns = current === hold.value && !stack.slice(index + 1).some((above2) => above2.value === current);
+    if (owns && preserveFocus && holdsFocus(element)) return false;
+    stack.splice(index, 1);
+    const above = stack[index];
+    if (above) above.linked &&= hold.linked;
+    this.#mark(element, stack);
+    if (!owns) return true;
+    const below = hold.linked ? stack[index - 1] : void 0;
+    if (!below) element.removeAttribute("tabindex");
+    else if (below.value !== current) element.setAttribute("tabindex", below.value);
+    return true;
+  }
+  #mark(element, stack) {
+    const records = /* @__PURE__ */ new Map([[this.#record, null]]);
+    for (const hold of stack) records.set(hold.record, hold.value);
+    for (const [name, recorded] of records) {
+      setAttributeIfChanged(element, name, recorded);
     }
-    this.#lent.clear();
-    this.#beforeCache.deactivate();
   }
 };
 
-// src/controllers/pagination_controller.ts
-var PaginationController = class extends Controller {
+function targetSelector(identifier, name) {
+  return `[data-${identifier}-target~="${name}"]`;
+}
+
+var PaginationController = class _PaginationController extends Controller {
+  #numbers = new NumberValueReader();
+  #moves = new MoveCounter();
+  #moveToken = 0;
   static targets = ["page", "prev", "next"];
   static values = {
     page: { type: Number, default: 1 },
     total: { type: Number, default: 1 }
   };
+  static valueConstraints = {
+    page: NUMBER_BOUNDS.finite,
+    total: NUMBER_BOUNDS.finite
+  };
   static actions = ["next", "prev", "select"];
   static events = ["change", "reconcile"];
-  /** Marks a `disabled` this controller applied at a boundary, in its own namespace. */
   get #boundaryAttribute() {
     return `data-${this.identifier}-boundary-disabled`;
   }
-  /** The `tabindex` this instance lends the root for the focus fallback. */
-  #tabindex = new TabindexLoan();
-  /**
-   * Collapses the Value and target callbacks of one mutation into one pass, and
-   * refuses the ones Stimulus delivers before `connect()`, which renders itself.
-   */
-  #repaint = new MicrotaskCoalescer(() => this.#reconcilePage());
-  /** The page shown last, which the next move of the current page is measured from. */
+  #tabindex = new TabindexLoan("-1", this.identifier);
+  #repaint = new MorphRenderWatcher(() => this.#reconcilePage());
   #shown = 1;
-  /** Renders the initial state from the clamped `page` and `total`. */
   connect() {
-    this.#repaint.activate();
+    this.#tabindex.reclaim(this.element);
+    this.#repaint.observe(this.element);
     this.#shown = this.#page;
     this.#render();
   }
-  /** Drops a pending pass and reverts the one attribute added outside the state hooks. */
   disconnect() {
-    this.#repaint.cancel();
+    this.#repaint.disconnect();
     this.#tabindex.returnAll();
   }
-  /** Re-renders when application code (or a Turbo morph) changes `page` at runtime. */
   pageValueChanged() {
     this.#repaint.schedule();
   }
-  /** Re-renders when application code (or a Turbo morph) changes `total` at runtime. */
   totalValueChanged() {
     this.#repaint.schedule();
   }
-  /** Syncs a page button appended/replaced at runtime (the consumer owns the list). */
   pageTargetConnected() {
     this.#repaint.schedule();
   }
-  /** Syncs a `prev` button appended/replaced at runtime. */
   prevTargetConnected() {
     this.#repaint.schedule();
   }
-  /** Syncs a `next` button appended/replaced at runtime. */
+  prevTargetDisconnected(button) {
+    this.#releaseDeparted(button, this.prevTargets);
+    this.#repaint.schedule();
+  }
   nextTargetConnected() {
     this.#repaint.schedule();
   }
-  /** Makes the clicked page button (its `data-page`) current. */
-  select(event) {
-    const button = event.currentTarget;
+  nextTargetDisconnected(button) {
+    this.#releaseDeparted(button, this.nextTargets);
+    this.#repaint.schedule();
+  }
+  select(source) {
+    const { host, origin, reason } = actionSource(source);
+    const button = host?.closest(targetSelector(this.identifier, "page"));
+    if (!button || !this.pageTargets.includes(button)) return;
+    if (origin && origin.closest(`[data-controller~="${this.identifier}"]`) !== this.element)
+      return;
     const raw = button.dataset.page;
     if (raw === void 0 || raw.trim() === "") return;
     const page = Number(raw);
     if (!Number.isInteger(page)) return;
-    this.#goto(page);
+    this.#goto(page, reason);
   }
-  /** Steps to the previous page. */
-  prev() {
-    this.#goto(this.#page - 1);
+  prev(event) {
+    this.#goto(this.#page - 1, stateReasonFor(event));
   }
-  /** Steps to the next page. */
-  next() {
-    this.#goto(this.#page + 1);
+  next(event) {
+    this.#goto(this.#page + 1, stateReasonFor(event));
   }
-  /** Moves to `page` (clamped to `[1, total]`), re-renders, and dispatches `change`. */
-  #goto(page) {
-    if (!Number.isFinite(page)) return;
-    const previous = this.#page;
+  #goto(page, reason) {
+    const previous = this.#shown;
     const target = this.#clamp(page);
-    if (target === previous) return;
+    if (target === previous && target === this.#page) return;
     this.pageValue = target;
     this.#shown = target;
+    const changed = target !== previous;
+    if (changed) this.#moveToken = this.#moves.record();
+    const token = this.#moveToken;
     this.#render();
+    if (!changed || !this.#moves.isLatest(token)) return;
     this.dispatch("change", {
-      detail: { page: target, total: this.#total, previous }
+      detail: { page: target, total: this.#total, previous, reason }
     });
   }
-  /**
-   * Renders one settled batch of Value and target changes, and reports a current
-   * page that moved from the one shown before as `reconcile`.
-   */
   #reconcilePage() {
     const previous = this.#shown;
     const page = this.#page;
     this.#shown = page;
+    const token = this.#moveToken;
     this.#render();
-    if (page !== previous) {
+    if (page !== previous && this.#moves.isLatest(token)) {
       this.dispatch("reconcile", { detail: { page, total: this.#total, previous } });
     }
   }
-  /**
-   * Syncs `aria-current` on the page buttons and the prev/next `disabled` state.
-   *
-   * It reads `page` and `total` through their clamps and never writes either Value,
-   * so a declaration outside the range stays in the attributes as the page wrote it.
-   *
-   * @stimeoRenderRoot
-   */
   #render() {
+    const token = this.#moveToken;
     const page = this.#page;
     for (const button of this.pageTargets) {
       if (Number(button.dataset.page) === page) {
@@ -230,40 +432,35 @@ var PaginationController = class extends Controller {
     const next = this.hasNextTarget ? this.nextTarget : null;
     const atStart = page <= 1;
     const atEnd = page >= this.#total;
-    const prevStaysDisabled = this.#disabledAfter(prev, atStart);
     const nextStaysDisabled = this.#disabledAfter(next, atEnd);
     this.#release(prev, atStart);
     this.#release(next, atEnd);
     this.#disable(prev, atStart, nextStaysDisabled ? null : next);
-    this.#disable(next, atEnd, prevStaysDisabled ? null : prev);
+    if (!this.#moves.isLatest(token)) return;
+    this.#disable(next, atEnd, prev);
   }
-  /** Whether a boundary button will still be `disabled` once this render applies. */
   #disabledAfter(button, atBoundary) {
     if (!button) return true;
     if (atBoundary) return true;
     return button.disabled && !this.#owns(button);
   }
-  /** Releases the boundary `disabled` this controller owns, once away from it. */
+  #releaseDeparted(button, targets) {
+    if (!targets.includes(button)) this.#release(button, false);
+  }
   #release(button, atBoundary) {
     if (!button || atBoundary || !this.#owns(button)) return;
     button.disabled = false;
     button.removeAttribute(this.#boundaryAttribute);
   }
-  /**
-   * Disables a boundary button, first moving focus off it when it is the active
-   * element so disabling never strands focus.
-   */
   #disable(button, atBoundary, opposite) {
     if (!button || !atBoundary) return;
     if (button.disabled && !this.#owns(button)) return;
+    const token = this.#moveToken;
     if (button === document.activeElement) this.#moveFocusAwayFrom(opposite);
+    if (!this.#moves.isLatest(token)) return;
     button.disabled = true;
     button.setAttribute(this.#boundaryAttribute, "");
   }
-  /**
-   * Moves focus to `opposite` (already resolved to `null` when it will stay
-   * disabled), else to the current page button, else to the landmark itself.
-   */
   #moveFocusAwayFrom(opposite) {
     const page = this.#page;
     const currentPage = this.pageTargets.find(
@@ -279,26 +476,38 @@ var PaginationController = class extends Controller {
     this.#tabindex.lend(this.element);
     this.element.focus();
   }
-  /** Total pages, normalized to a finite integer >= 1. */
   get #total() {
-    const total = this.totalValue;
-    return Number.isFinite(total) ? Math.max(1, Math.trunc(total)) : 1;
+    const total = this.#safeTotal;
+    return Math.max(1, Math.trunc(total));
   }
-  /** The current page, normalized into `[1, total]`. */
   get #page() {
-    return this.#clamp(this.pageValue);
+    return this.#clamp(this.#safePage);
   }
-  /** Constrains `page` to `[1, total]`; a non-finite page falls back to page 1. */
   #clamp(page) {
-    if (!Number.isFinite(page)) return 1;
     return Math.min(this.#total, Math.max(1, Math.trunc(page)));
   }
-  /** Whether the button's current `disabled` was applied by boundary control. */
   #owns(button) {
     return button.hasAttribute(this.#boundaryAttribute);
   }
+  get #safePage() {
+    return this.#numbers.read(
+      this,
+      "page",
+      this.pageValue,
+      _PaginationController.values.page.default,
+      _PaginationController.valueConstraints.page
+    );
+  }
+  get #safeTotal() {
+    return this.#numbers.read(
+      this,
+      "total",
+      this.totalValue,
+      _PaginationController.values.total.default,
+      _PaginationController.valueConstraints.total
+    );
+  }
 };
 
 export { PaginationController };
-//# sourceMappingURL=pagination_controller.js.map
 //# sourceMappingURL=pagination_controller.js.map