stimeo-ui 0.9.0 → 0.11.0

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();

data/dist/controllers/transition_controller.js

@@ -2,6 +2,35 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/transition_controller.ts
 
+// 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;
+  }
+  /** 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);
+    }
+  }
+  /** 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);
+  }
+};
+
 // src/utils/reduced_motion.ts
 function prefersReducedMotion() {
   return typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
@@ -217,12 +246,21 @@ var TransitionController = class extends Controller {
   static events = ["entered", "left"];
   /** Owns the cancellable completion wait (terminal events + bounded fallback). */
   #transition = new TransitionCompletion();
+  /** Rewinds a half-applied stage before Turbo copies the page into its snapshot. */
+  #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
   #rafId = null;
+  /**
+   * Stage classes this controller put on the element. Removing by declaration
+   * instead would take a token the consumer also authored, and would strand the
+   * token that was applied when a Value changes mid-transition.
+   */
+  #staged = /* @__PURE__ */ new Set();
   connect() {
-    this.#strip();
-    this.element.setAttribute("data-transition-state", this.element.hidden ? "left" : "entered");
+    this.#beforeCache.activate();
+    this.#settleState();
   }
   disconnect() {
+    this.#beforeCache.deactivate();
     this.#cancel();
   }
   /** Shows the element with the enter transition. */
@@ -252,6 +290,7 @@ var TransitionController = class extends Controller {
     const from = isEnter ? this.enterFromValue : this.leaveFromValue;
     const to = isEnter ? this.enterToValue : this.leaveToValue;
     this.#add(base, from);
+    void this.element.offsetWidth;
     this.#rafId = this.#raf(() => {
       this.#rafId = null;
       this.#remove(from);
@@ -273,6 +312,21 @@ var TransitionController = class extends Controller {
       this.dispatch("left", { detail: {} });
     }
   }
+  /** Writes the state hook the element's visibility implies. */
+  #settleState() {
+    this.element.setAttribute("data-transition-state", this.element.hidden ? "left" : "entered");
+  }
+  /**
+   * Returns the element to a settled state before Turbo copies the page.
+   *
+   * The snapshot is taken while the controller is still connected, so stripping on
+   * the next `connect()` would only repair the page after it has been painted from
+   * the cache. The pass is silent: `connect()` derives the state again on restore.
+   */
+  #rewindForCache() {
+    this.#cancel();
+    this.#settleState();
+  }
   /** Cancels any in-flight transition (interruption / teardown). */
   #cancel() {
     if (this.#rafId !== null) {
@@ -282,24 +336,34 @@ var TransitionController = class extends Controller {
     this.#transition.cancel();
     this.#strip();
   }
+  /**
+   * Applies the stage tokens this controller does not already find on the
+   * element, and claims exactly those.
+   *
+   * A token already on the element is left unclaimed: it is either the consumer's
+   * standing class or one an earlier stage of this transition already claimed, and
+   * in neither case may this call take ownership of it. That is what keeps a
+   * standing class the consumer also named as a stage Value; the cost is that such
+   * a token cannot be staged, so the property it drives resolves from their CSS.
+   */
   #add(...lists) {
-    const tokens = lists.flatMap(tokensOf);
-    if (tokens.length > 0) this.element.classList.add(...tokens);
+    for (const token of lists.flatMap(tokensOf)) {
+      if (this.element.classList.contains(token)) continue;
+      this.element.classList.add(token);
+      this.#staged.add(token);
+    }
   }
+  /** Drops the named tokens that are this controller's to drop. */
   #remove(...lists) {
-    const tokens = lists.flatMap(tokensOf);
-    if (tokens.length > 0) this.element.classList.remove(...tokens);
+    for (const token of lists.flatMap(tokensOf)) {
+      if (!this.#staged.delete(token)) continue;
+      this.element.classList.remove(token);
+    }
   }
-  /** Removes every stage class so no half-applied state lingers. */
+  /** Removes every stage class this controller applied, so none lingers. */
   #strip() {
-    this.#remove(
-      this.enterValue,
-      this.enterFromValue,
-      this.enterToValue,
-      this.leaveValue,
-      this.leaveFromValue,
-      this.leaveToValue
-    );
+    this.element.classList.remove(...this.#staged);
+    this.#staged.clear();
   }
   #raf(callback) {
     if (typeof window.requestAnimationFrame === "function") {