stimeo-ui 0.8.0 → 0.10.0

data/dist/controllers/scroll_visibility_controller.js

@@ -2,6 +2,61 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/scroll_visibility_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 = () => {
+      this.#detach(element);
+      this.#onRelease(element);
+    };
+    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);
+    this.#pending.delete(element);
+  }
+};
+
 // src/utils/reduced_motion.ts
 function prefersReducedMotion() {
   return typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
@@ -68,10 +123,11 @@ var TabindexLoan = class {
 };
 
 // src/controllers/scroll_visibility_controller.ts
+var DEFAULT_OFFSET = 400;
 var ScrollVisibilityController = class extends Controller {
   static targets = ["element"];
   static values = {
-    offset: { type: Number, default: 400 },
+    offset: { type: Number, default: DEFAULT_OFFSET },
     mode: { type: String, default: "offset" },
     focusSelector: { type: String, default: "" },
     root: { type: String, default: "" }
@@ -89,8 +145,32 @@ var ScrollVisibilityController = class extends Controller {
    * the window. Captured on connect so teardown detaches from the same source.
    */
   #scrollSource = window;
+  /**
+   * Gates the declaration callbacks to the connected window.
+   *
+   * Stimulus delivers a Value callback ahead of `connect()` and again for every
+   * runtime change; without the gate, merely connecting would evaluate — and
+   * announce — before `connect()` runs its own first reflection.
+   */
+  #connected = false;
+  /** Validated threshold; a non-finite declaration reads as the default. */
+  #offset = DEFAULT_OFFSET;
+  /** Validated `root` selector; an unparsable declaration reads as absent. */
+  #rootSelector = "";
+  /** Validated `focusSelector`; an unparsable declaration reads as absent. */
+  #focusSelector = "";
   /** Focus targets this instance lent a `tabindex` to. */
   #tabindex = new TabindexLoan();
+  /**
+   * The hide held back while the control itself owns focus.
+   *
+   * Completing the deferral re-runs the ordinary evaluation rather than applying
+   * the stale decision: by the time focus leaves, the scroll position may have
+   * moved back past the threshold.
+   */
+  #pendingHide = new BlurDeferral(() => {
+    if (this.#connected) this.#evaluate();
+  });
   #onScroll = () => {
     if (this.#rafId !== null) return;
     this.#rafId = requestAnimationFrame(() => {
@@ -102,61 +182,134 @@ var ScrollVisibilityController = class extends Controller {
     this.#scrollSource = this.#resolveScrollSource();
     this.#lastScrollY = this.#scrollY();
     this.#scrollSource.addEventListener("scroll", this.#onScroll, { passive: true });
-    this.#evaluate();
+    this.#evaluate(false);
+    this.#connected = true;
   }
   disconnect() {
+    this.#connected = false;
     this.#scrollSource.removeEventListener("scroll", this.#onScroll);
     if (this.#rafId !== null) {
       cancelAnimationFrame(this.#rafId);
       this.#rafId = null;
     }
+    this.#pendingHide.releaseAll();
     this.#tabindex.returnAll();
     this.#visible = null;
   }
+  /** Writes the current visibility onto a control that arrives after connect. */
+  elementTargetConnected(element) {
+    if (this.#visible !== null) element.hidden = !this.#visible;
+  }
+  /** Drops a held-back hide together with the control it was waiting on. */
+  elementTargetDisconnected() {
+    this.#pendingHide.releaseAll();
+  }
+  /**
+   * Validates `offset` once, then re-renders.
+   *
+   * Re-renders when application code (or a Turbo morph) changes `offset` at
+   * runtime. A declaration that is not a finite number reads as the default, so
+   * the comparison path never sees `NaN` — which would answer `false` to every
+   * comparison and strand the element (in `direction` mode, even the guarantee
+   * that the very top always reveals).
+   */
+  offsetValueChanged() {
+    this.#offset = Number.isFinite(this.offsetValue) ? this.offsetValue : DEFAULT_OFFSET;
+    if (this.#connected) this.#evaluate();
+  }
+  /** Re-renders when application code (or a Turbo morph) changes `mode` at runtime. */
+  modeValueChanged() {
+    if (this.#connected) this.#evaluate();
+  }
+  /** Validates `root` once so connect never parses a selector that throws. */
+  rootValueChanged() {
+    this.#rootSelector = this.#validSelector(this.rootValue);
+  }
+  /** Validates `focusSelector` once so `toTop` never parses a selector that throws. */
+  focusSelectorValueChanged() {
+    this.#focusSelector = this.#validSelector(this.focusSelectorValue);
+  }
   /** Scrolls the source to the top and, optionally, moves focus to a safe target. */
   toTop() {
     const behavior = prefersReducedMotion() ? "instant" : "smooth";
     this.#scrollSource.scrollTo({ top: 0, behavior });
-    if (this.focusSelectorValue) {
-      const target = document.querySelector(this.focusSelectorValue);
+    if (this.#focusSelector) {
+      const target = document.querySelector(this.#focusSelector);
       if (target) {
         this.#tabindex.lend(target);
-        target.focus();
+        target.focus({ preventScroll: true });
       }
     }
   }
-  /** Decides the next visibility from the current scroll state and applies it. */
-  #evaluate() {
+  /**
+   * Decides the next visibility from the current scroll state and applies it.
+   *
+   * @param notify - whether a transition announces itself. The reflection
+   *   `connect()` performs is the current state, not a change.
+   *
+   * @stimeoRenderRoot
+   */
+  #evaluate(notify = true) {
     const y = this.#scrollY();
     let nextVisible;
     if (this.modeValue === "direction") {
-      if (y <= this.offsetValue) {
+      if (y <= this.#offset) {
         nextVisible = true;
+      } else if (y === this.#lastScrollY) {
+        return;
       } else {
         nextVisible = y < this.#lastScrollY;
       }
     } else {
-      nextVisible = y > this.offsetValue;
+      nextVisible = y > this.#offset;
     }
     this.#lastScrollY = y;
-    this.#setVisible(nextVisible);
+    this.#setVisible(nextVisible, notify);
   }
   /** Applies visibility to the target, syncing `hidden`, `data-state`, `change`. */
-  #setVisible(next) {
+  #setVisible(next, notify) {
     if (next === this.#visible) return;
+    const focused = !next && this.hasElementTarget ? this.#focusedWithin() : null;
+    if (focused) {
+      this.#pendingHide.deferOnly(focused);
+      return;
+    }
     this.#visible = next;
     if (this.hasElementTarget) this.elementTarget.hidden = !next;
     this.element.setAttribute("data-state", next ? "visible" : "hidden");
-    this.dispatch("change", { detail: { visible: next } });
+    if (notify) this.dispatch("change", { detail: { visible: next } });
   }
   /** Resolves the scroll source from `root` (falling back to the window). */
   #resolveScrollSource() {
-    if (this.rootValue) {
-      const root = document.querySelector(this.rootValue);
+    if (this.#rootSelector) {
+      const root = document.querySelector(this.#rootSelector);
       if (root) return root;
     }
     return window;
   }
+  /**
+   * The focus owner inside the target, or `null` when focus is elsewhere.
+   *
+   * `blur` does not bubble, so the deferral has to ride the focused element
+   * itself: waiting on a container that never receives the event would hold the
+   * hide forever.
+   */
+  #focusedWithin() {
+    const focused = document.activeElement;
+    if (focused instanceof HTMLElement && this.elementTarget.contains(focused)) return focused;
+    return null;
+  }
+  /** Returns `declared` when it parses as a selector, and `""` when it does not. */
+  #validSelector(declared) {
+    if (declared.length > 0) {
+      try {
+        this.element.matches(declared);
+        return declared;
+      } catch {
+      }
+    }
+    return "";
+  }
   #scrollY() {
     if (this.#scrollSource === window) {
       return window.scrollY ?? window.pageYOffset ?? 0;

data/dist/controllers/sidebar_controller.js

@@ -315,15 +315,25 @@ var FocusTrap = class {
    * content cannot be focused or reached by assistive technology, honoring the
    * `aria-modal="true"` contract. An element that was *already* `inert` is left
    * untracked so `#releaseBackground` does not wrongly clear it.
+   *
+   * The walk climbs from the container to `body` and inerts each ancestor's other
+   * children. Scanning only `body`'s children would skip the branch the container
+   * sits in — everything beside it inside that branch is background too, and a
+   * nested container is the ordinary case.
    */
   #isolateBackground() {
     const container = this.#getContainer();
     this.#inertedSiblings = [];
-    for (const sibling of Array.from(document.body.children)) {
-      if (!(sibling instanceof HTMLElement)) continue;
-      if (sibling.contains(container) || sibling.inert) continue;
-      sibling.inert = true;
-      this.#inertedSiblings.push(sibling);
+    for (let node = container; node !== document.body; ) {
+      const parent = node.parentElement;
+      if (!parent) break;
+      for (const sibling of Array.from(parent.children)) {
+        if (!(sibling instanceof HTMLElement)) continue;
+        if (sibling === node || sibling.inert) continue;
+        sibling.inert = true;
+        this.#inertedSiblings.push(sibling);
+      }
+      node = parent;
     }
   }
   /** Reverts the `inert` flags applied by `#isolateBackground`. */

data/dist/controllers/step_indicator_controller.js

@@ -43,11 +43,6 @@ var StepIndicatorController = class extends Controller {
   };
   static actions = ["setCurrent"];
   static events = ["change"];
-  /**
-   * Whether the target callbacks may render. Stimulus reports the authored steps
-   * as connected before `connect()` and the remaining ones as disconnected after
-   * `disconnect()`, so this keeps a connect at one render pass, not one per step.
-   */
   /**
    * Collapses a batch of step callbacks — and a morph that swaps `current` with
    * them — into one repaint. Replacing a list of N steps delivers N callbacks, and

data/dist/controllers/theme_controller.js

@@ -19,6 +19,49 @@ function isReservedArrowChord(event, allow = []) {
   if (!event.key.startsWith("Arrow")) return false;
   return event.altKey && !allow.includes("alt") || event.ctrlKey && !allow.includes("ctrl") || event.metaKey && !allow.includes("meta") || event.shiftKey && !allow.includes("shift");
 }
+function hasModifierChord(event) {
+  return event.altKey || event.ctrlKey || event.metaKey || event.shiftKey;
+}
+
+// src/utils/roving_tabindex.ts
+var RovingTabindex = class {
+  /** Returns the current ordered item elements; called on every operation. */
+  #getItems;
+  /**
+   * @param getItems - Returns the current ordered item elements. Called on every
+   *   operation so the live target list is always used.
+   */
+  constructor(getItems) {
+    this.#getItems = getItems;
+  }
+  /** Index of the currently tabbable item (`tabindex="0"`), or `-1` if none. */
+  get activeIndex() {
+    return this.#getItems().findIndex((item) => item.tabIndex === 0);
+  }
+  /**
+   * Makes exactly the item at `index` tabbable (`tabindex="0"`) and removes every
+   * other item from the Tab sequence (`tabindex="-1"`). An out-of-range `index`
+   * (e.g. `-1`) leaves all items at `-1`, which a controller can use to express
+   * "nothing is currently tabbable".
+   *
+   * @param index - Position of the item to make tabbable.
+   * @param options - Pass `{ focus: true }` to also move DOM focus to that item,
+   *   and `items` to reuse an event-scoped collection snapshot.
+   */
+  setActive(index, options = {}) {
+    const { focus = false } = options;
+    const items = options.items ?? this.#getItems();
+    items.forEach((item, i) => {
+      item.tabIndex = i === index ? 0 : -1;
+    });
+    if (focus) items[index]?.focus();
+  }
+};
+function rovingMove(current, length, delta, wrap) {
+  if (length === 0) return -1;
+  const next = current + delta;
+  return (next + length) % length;
+}
 
 // src/utils/safe_storage.ts
 function readLocalStorage(key) {
@@ -40,35 +83,48 @@ function writeLocalStorage(key, value) {
 // src/controllers/theme_controller.ts
 var MODES = ["light", "dark", "system"];
 var isMode = (value) => typeof value === "string" && MODES.includes(value);
+var DEFAULT_MODE = "system";
+var DEFAULT_TARGET = "html";
 var ThemeController = class extends Controller {
   static targets = ["option"];
   static values = {
-    mode: { type: String, default: "system" },
+    mode: { type: String, default: DEFAULT_MODE },
     storageKey: { type: String, default: "stimeo-theme" },
-    target: { type: String, default: "html" }
+    target: { type: String, default: DEFAULT_TARGET }
   };
   static actions = ["set", "toggle"];
   static events = ["change"];
   /** The OS dark-mode query, watched so `system` tracks live changes. */
   #media = null;
+  /** Gate for the target callbacks, which Stimulus runs before `connect()`. */
+  #connected = false;
+  /** The `target` declaration after validation; the default when unparsable. */
+  #targetSelector = DEFAULT_TARGET;
+  /** Owns the single Tab stop across the option set (APG radiogroup). */
+  #roving = new RovingTabindex(() => this.optionTargets);
+  /**
+   * The pair last reported, so a move can be told from a repeat. Neither side is
+   * readable after the fact — assigning the Value updates the mode before any
+   * comparison, and the OS query has already flipped by the time it notifies —
+   * so what was reported has to be kept rather than recomputed.
+   */
+  #published = {
+    mode: DEFAULT_MODE,
+    resolved: "light"
+  };
   /** Re-resolves while in `system` mode when the OS preference flips. */
   #onMediaChange = () => {
-    if (this.modeValue === "system") {
-      this.#applyTheme();
-      this.#syncControls();
-      this.#dispatchChange();
-    }
+    if (this.#mode !== "system") return;
+    this.#commit();
   };
   /** Arrow/Home/End navigation for the radiogroup (APG radio pattern). */
   #onKeydown = (event) => {
     if (event.defaultPrevented) return;
     if (isReservedArrowChord(event)) return;
     const options = this.optionTargets;
-    if (options.length === 0) return;
     const target = event.target;
     const current = options.indexOf(target);
     if (current === -1) return;
-    const last = options.length - 1;
     let next = current;
     const step = logicalArrowStep(event.key, this.element);
     switch (event.key) {
@@ -76,13 +132,12 @@ var ThemeController = class extends Controller {
       case "ArrowRight":
       case "ArrowUp":
       case "ArrowLeft":
-        next = step === 1 ? current === last ? 0 : current + 1 : current === 0 ? last : current - 1;
+        next = rovingMove(current, options.length, step);
         break;
       case "Home":
-        next = 0;
-        break;
       case "End":
-        next = last;
+        if (hasModifierChord(event)) return;
+        next = event.key === "Home" ? 0 : options.length - 1;
         break;
       default:
         return;
@@ -91,25 +146,58 @@ var ThemeController = class extends Controller {
     const option = options[next];
     if (!option) return;
     option.focus();
-    this.#setMode(this.#optionMode(option));
+    const mode = this.#optionMode(option);
+    if (mode) this.#setMode(mode);
   };
   connect() {
     const stored = this.#readStored();
     if (stored) this.modeValue = stored;
     this.#media = window.matchMedia?.("(prefers-color-scheme: dark)") ?? null;
     this.#media?.addEventListener("change", this.#onMediaChange);
-    if (this.hasOptionTarget) this.element.addEventListener("keydown", this.#onKeydown);
+    this.element.addEventListener("keydown", this.#onKeydown);
+    this.#connected = true;
     this.#applyTheme();
     this.#syncControls();
+    this.#published = this.#current;
   }
   disconnect() {
+    this.#connected = false;
     this.#media?.removeEventListener("change", this.#onMediaChange);
     this.element.removeEventListener("keydown", this.#onKeydown);
   }
-  /** Selects an explicit mode from the `mode` action param (radiogroup option). */
+  /** Validates the `target` declaration once, so the render path never parses. */
+  targetValueChanged() {
+    const selector = this.targetValue;
+    if (selector.length > 0) {
+      try {
+        this.element.matches(selector);
+        this.#targetSelector = selector;
+        return;
+      } catch {
+      }
+    }
+    this.#targetSelector = DEFAULT_TARGET;
+  }
+  /** Re-derives the single Tab stop and ARIA for an option set that changed. */
+  optionTargetConnected() {
+    if (this.#connected) this.#syncControls();
+  }
+  /** Re-derives them again when an option leaves, so a Tab stop always remains. */
+  optionTargetDisconnected() {
+    if (this.#connected) this.#syncControls();
+  }
+  /**
+   * Selects the mode the activated option declares.
+   *
+   * Read through {@link ThemeController.#optionMode}, the same lane that decides
+   * which option is checked, so the two can never disagree about what an option
+   * declares.
+   */
   set(event) {
-    const mode = event.params?.mode;
-    if (isMode(mode)) this.#setMode(mode);
+    const option = event.currentTarget;
+    if (!(option instanceof HTMLElement)) return;
+    const mode = this.#optionMode(option);
+    if (mode) this.#setMode(mode);
   }
   /** Toggles light↔dark for the 2-value single-button contract. */
   toggle() {
@@ -119,9 +207,26 @@ var ThemeController = class extends Controller {
   #setMode(mode) {
     this.modeValue = mode;
     this.#writeStored(mode);
+    this.#commit();
+  }
+  /**
+   * Applies the current mode and reports it, but reports only a real move: the
+   * event means "the selection or the effective theme moved", so re-choosing the
+   * option already chosen is not one.
+   */
+  #commit() {
     this.#applyTheme();
     this.#syncControls();
-    this.#dispatchChange();
+    const next = this.#current;
+    const last = this.#published;
+    this.#published = next;
+    if (last.mode !== next.mode || last.resolved !== next.resolved) {
+      this.dispatch("change", { detail: { ...next } });
+    }
+  }
+  /** The pair the `change` detail carries, read from current state. */
+  get #current() {
+    return { mode: this.#mode, resolved: this.#resolved() };
   }
   /** Writes `data-theme` + `color-scheme` (the resolved theme) onto the target. */
   #applyTheme() {
@@ -135,39 +240,45 @@ var ThemeController = class extends Controller {
   #syncControls() {
     const options = this.optionTargets;
     if (options.length > 0) {
-      let hasTabbable = false;
-      for (const option of options) {
-        const selected = this.#optionMode(option) === this.modeValue;
-        option.setAttribute("aria-checked", String(selected));
-        option.tabIndex = selected ? 0 : -1;
-        hasTabbable ||= selected;
-      }
-      const first = options[0];
-      if (!hasTabbable && first) first.tabIndex = 0;
+      const mode = this.#mode;
+      let selected = -1;
+      options.forEach((option, index) => {
+        const isSelected = this.#optionMode(option) === mode;
+        option.setAttribute("aria-checked", String(isSelected));
+        if (isSelected && selected === -1) selected = index;
+      });
+      this.#roving.setActive(selected === -1 ? 0 : selected, { items: options });
       return;
     }
-    this.element.setAttribute("aria-pressed", String(this.#resolved() === "dark"));
+    if (this.#isToggleButton) {
+      this.element.setAttribute("aria-pressed", String(this.#resolved() === "dark"));
+    }
+  }
+  /** Whether the controller element is the button of the 2-value contract. */
+  get #isToggleButton() {
+    return this.element.tagName === "BUTTON" || this.element.getAttribute("role") === "button";
   }
-  /** Emits `change` with the selected mode and the resolved theme. */
-  #dispatchChange() {
-    this.dispatch("change", { detail: { mode: this.modeValue, resolved: this.#resolved() } });
+  /** The selected mode after validation; an unreadable declaration is the default. */
+  get #mode() {
+    return isMode(this.modeValue) ? this.modeValue : DEFAULT_MODE;
   }
   /** The effective theme: the OS preference when `system`, else the mode itself. */
   #resolved() {
-    if (this.modeValue === "dark") return "dark";
-    if (this.modeValue === "light") return "light";
+    const mode = this.#mode;
+    if (mode === "dark") return "dark";
+    if (mode === "light") return "light";
     return this.#media?.matches ? "dark" : "light";
   }
-  /** Reads an option's mode from its action param attribute. */
+  /** An option's mode from its `data-value`, or `null` when that is not one of the three. */
   #optionMode(option) {
-    const mode = option.getAttribute("data-stimeo--theme-mode-param");
-    return isMode(mode) ? mode : "system";
+    const mode = option.getAttribute("data-value");
+    return isMode(mode) ? mode : null;
   }
   /** Resolves the state-hook target (`<html>` by default). */
   #targetElement() {
-    if (this.targetValue === "html" || this.targetValue === ":root")
-      return document.documentElement;
-    return document.querySelector(this.targetValue);
+    const selector = this.#targetSelector;
+    if (selector === DEFAULT_TARGET || selector === ":root") return document.documentElement;
+    return document.querySelector(selector);
   }
   /** Reads a persisted, validated mode from `localStorage` (null when absent/blocked). */
   #readStored() {

data/dist/controllers/toast_controller.js

@@ -170,8 +170,8 @@ var ToastController = class extends Controller {
   }
   /**
    * Stimulus lifecycle callback triggered automatically when a new item target
-   * enters the DOM. Perfectly handles dynamic client-side injections and server-side
-   * Turbo Stream appends alike.
+   * enters the DOM, from a client-side injection or a Turbo Stream append alike. An
+   * item already leaving, or parented outside `list`, is skipped.
    */
   itemTargetConnected(element) {
     this.enforceMaxLimit();