stimeo-ui 0.2.1 → 0.3.0

data/dist/controllers/navigation_menu_controller.js

@@ -2,6 +2,17 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/navigation_menu_controller.ts
 
+// src/utils/logical_scroll.ts
+function isRtl(element) {
+  return window.getComputedStyle(element).direction === "rtl";
+}
+
+// src/utils/arrow_step.ts
+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");
+}
+
 // src/utils/escape_layer.ts
 function claimsWhileFocusWithin(element) {
   return () => {
@@ -157,27 +168,52 @@ var NavigationMenuController = class extends Controller {
   #hoverTimers = new SafeTimeout();
   /**
    * Elements currently carrying hover listeners. Removal always mirrors this
-   * set (not a recomputed target snapshot), so add/remove stays symmetric even
-   * when targets churn between connect and disconnect.
+   * set (not a recomputed target snapshot), so a rebuild driven by target churn
+   * can never strand a listener on an element that stopped being a target.
    */
   #hoverWired = /* @__PURE__ */ new Set();
+  /**
+   * The trigger whose hover region the pointer currently occupies, if any. Only
+   * the click semantics under `openOnHover` read it (see {@link toggle}).
+   */
+  #hoveredTrigger = null;
+  /**
+   * Whether the controller is between `connect()` and `disconnect()`. Stimulus
+   * disconnects the controller **before** disconnecting its targets, so the
+   * target callbacks below also fire during teardown; without this flag their
+   * rebuild would re-wire hover listeners onto an already-disconnected nav.
+   */
+  #connected = false;
   /** Escape-stack membership while any panel is open; the shared resolver dismisses via it. */
   #escapeLayer = new EscapeLayer();
   /** Establishes the closed baseline and the dismissal listeners. */
   connect() {
+    this.#connected = true;
     this.#closeAll();
-    document.addEventListener("click", this.#onOutsideClick);
+    document.addEventListener("click", this.#onOutsideClick, true);
     this.element.addEventListener("focusout", this.#onFocusOut);
     if (this.openOnHoverValue) this.#addHoverListeners();
   }
-  /** Removes every listener, pending hover timer, and stack membership registered while connected. */
+  /** Removes every listener, pending hover timer, and stack membership taken while connected. */
   disconnect() {
+    this.#connected = false;
     this.#escapeLayer.deactivate();
-    document.removeEventListener("click", this.#onOutsideClick);
+    document.removeEventListener("click", this.#onOutsideClick, true);
     this.element.removeEventListener("focusout", this.#onFocusOut);
     this.#removeHoverListeners();
     this.#hoverTimers.clearAll();
   }
+  /**
+   * Follows a runtime flip of `openOnHover` (a morph or a scripted attribute
+   * change) by wiring or unwiring the hover listeners in place. Stimulus also
+   * fires this once before `connect()`, which the `#connected` guard skips —
+   * `connect()` owns the initial wiring.
+   */
+  openOnHoverValueChanged() {
+    if (!this.#connected) return;
+    if (this.openOnHoverValue) this.#addHoverListeners();
+    else this.#removeHoverListeners();
+  }
   /** Re-wires hover listeners when a target is added after connect (Turbo Streams etc.). */
   triggerTargetConnected() {
     this.#rewireHoverListeners();
@@ -202,31 +238,65 @@ var NavigationMenuController = class extends Controller {
   hoverAreaTargetDisconnected() {
     this.#rewireHoverListeners();
   }
-  /** Toggles a trigger's panel (single-open). Bound via `data-action` (click). */
+  /**
+   * Toggles a trigger's panel (single-open). Bound via `data-action` (click).
+   *
+   * An explicit activation always wins over a scheduled hover open/close, so any
+   * pending hover timer is dropped first — otherwise a close scheduled just
+   * before the click would fire into the freshly opened panel.
+   *
+   * Under `openOnHover`, closing a panel the pointer itself is holding open is
+   * refused: the pointer stays put, `mouseenter` does not re-fire, and the panel
+   * would be unopenable until the pointer left and came back. Keyboard
+   * activation (pointer elsewhere) still toggles it closed, and `Escape` and
+   * outside clicks dismiss either way.
+   */
   toggle(event) {
     const trigger = event.currentTarget;
-    if (this.#isExpanded(trigger)) {
-      this.#closePanel(trigger);
-    } else {
+    this.#hoverTimers.clearAll();
+    if (!this.#isExpanded(trigger)) {
       this.#openPanel(trigger);
+      return;
     }
+    if (this.openOnHoverValue && this.#hoveredTrigger === trigger) return;
+    this.#closePanel(trigger);
   }
-  /** `ArrowLeft`/`ArrowRight` move focus between triggers (keeping Tab order). */
+  /**
+   * `ArrowLeft`/`ArrowRight` move focus between triggers (keeping Tab order).
+   *
+   * Only navigable triggers are destinations, so a `hidden` or disabled item
+   * never swallows the press. A modified arrow belongs to the browser or OS
+   * (`Alt+←`/`Alt+→` is history back/forward), and with no destination at all
+   * (a single-trigger nav) the press is left to the page — `preventDefault()` is
+   * called only when focus actually moves, keeping the scroll-suppression
+   * contract honest.
+   */
   onTriggerKeydown(event) {
-    const triggers = this.triggerTargets;
-    const index = triggers.indexOf(event.currentTarget);
-    if (index === -1) return;
-    const length = triggers.length;
-    if (event.key === "ArrowRight") {
-      event.preventDefault();
-      triggers[(index + 1) % length]?.focus();
-    } else if (event.key === "ArrowLeft") {
-      event.preventDefault();
-      triggers[(index - 1 + length) % length]?.focus();
-    }
+    if (event.defaultPrevented) return;
+    if (event.key !== "ArrowRight" && event.key !== "ArrowLeft") return;
+    if (isReservedArrowChord(event)) return;
+    const current = event.currentTarget;
+    const triggers = this.triggerTargets.filter(
+      (trigger) => trigger === current || this.#isNavigable(trigger)
+    );
+    const index = triggers.indexOf(current);
+    if (index === -1 || triggers.length < 2) return;
+    event.preventDefault();
+    const forward = isRtl(this.element) ? "ArrowLeft" : "ArrowRight";
+    const step = event.key === forward ? 1 : -1;
+    triggers[(index + step + triggers.length) % triggers.length]?.focus();
   }
-  /** Opens `trigger`'s panel, closing any other open panel first. */
+  /**
+   * Opens `trigger`'s panel, closing any other open panel first. Re-opening an
+   * already-open panel only re-asserts the Escape layer: the close/open
+   * round-trip would rewrite `aria-expanded` and `hidden` for no state change.
+   */
   #openPanel(trigger) {
+    if (trigger.getAttribute("aria-disabled") === "true") return;
+    if (this.#isExpanded(trigger)) {
+      this.#syncEscapeLayer();
+      return;
+    }
     this.#closeAll();
     const panel = this.#panelFor(trigger);
     if (!panel) return;
@@ -241,10 +311,30 @@ var NavigationMenuController = class extends Controller {
     trigger.setAttribute("aria-expanded", "false");
     this.#syncEscapeLayer();
   }
-  /** Closes every open panel. */
+  /**
+   * Closes every open panel and normalizes `aria-expanded="false"` on **all**
+   * triggers, so a trigger whose panel was hidden by other means cannot keep
+   * advertising an open panel.
+   */
   #closeAll() {
     for (const trigger of this.triggerTargets) this.#closePanel(trigger);
   }
+  /**
+   * Whether a trigger can receive arrow-key focus: not `hidden`, not a natively
+   * `disabled` control (mirrors `toolbar`). CSS-only visibility cannot be
+   * detected headlessly and stays the consumer's responsibility.
+   *
+   * **`aria-disabled="true"` stays reachable.** APG separates the attributes by
+   * intent: `disabled` is for controls a neighbour makes inferable, while
+   * `aria-disabled` marks one that must remain *discoverable* — and a nav
+   * section the user cannot even arrow to is a section they cannot learn exists.
+   * Opening is suppressed separately, so the trigger announces itself and does
+   * nothing.
+   */
+  #isNavigable(trigger) {
+    if (trigger.hasAttribute("hidden")) return false;
+    return !trigger.disabled;
+  }
   /**
    * Aligns Escape-stack membership with the open state: joins (or re-asserts to
    * the top) while a panel is open, leaves once none is. Re-asserting when the
@@ -260,10 +350,15 @@ var NavigationMenuController = class extends Controller {
       this.#escapeLayer.deactivate();
     }
   }
-  /** Closes any open panel and returns focus to its trigger (Escape path). */
+  /**
+   * Closes any open panel and returns focus to its trigger (Escape path). A
+   * pending hover open would otherwise re-open the panel the user just
+   * dismissed, so the reservation is dropped with it.
+   */
   #closeAndRestore() {
     const open = this.#openTrigger;
     if (!open) return;
+    this.#hoverTimers.clearAll();
     this.#closePanel(open);
     open.focus();
   }
@@ -288,8 +383,9 @@ var NavigationMenuController = class extends Controller {
   #onPointerEnter = (event) => {
     const trigger = this.#triggerForHover(event.currentTarget);
     if (!trigger) return;
+    this.#hoveredTrigger = trigger;
     this.#hoverTimers.clearAll();
-    this.#hoverTimers.set(() => this.#openPanel(trigger), this.hoverDelayValue);
+    this.#hoverTimers.set(() => this.#openFromHover(trigger), this.hoverDelayValue);
   };
   /**
    * Closes the open panel after the hover delay (hover mode) — unless the
@@ -300,9 +396,37 @@ var NavigationMenuController = class extends Controller {
   #onPointerLeave = (event) => {
     const next = event instanceof MouseEvent ? event.relatedTarget : null;
     if (next instanceof Node && this.#hoverElements.some((el) => el.contains(next))) return;
+    this.#hoveredTrigger = null;
     this.#hoverTimers.clearAll();
-    this.#hoverTimers.set(() => this.#closeAll(), this.hoverDelayValue);
+    this.#hoverTimers.set(() => this.#closeFromHover(), this.hoverDelayValue);
   };
+  /**
+   * Hover-driven open. Switching panels would hide the outgoing one, so focus
+   * standing inside it is handed back to its trigger first: pointer movement
+   * must never send focus to the body (the keyboard user would lose their
+   * place). Focus outside the closing panel is left alone.
+   */
+  #openFromHover(trigger) {
+    if (trigger.getAttribute("aria-disabled") === "true") return;
+    const open = this.#openTrigger;
+    if (open && open !== trigger && this.#holdsFocus(this.#panelFor(open))) open.focus();
+    this.#openPanel(trigger);
+  }
+  /**
+   * Hover-driven close: skipped while focus sits inside the panel it would hide,
+   * for the same no-focus-loss reason (cf. `hover_card`'s delayed close). The
+   * panel then stays open until `Escape`, an outside click, or focus leaving the
+   * nav dismisses it — all of which restore or keep focus deliberately.
+   */
+  #closeFromHover() {
+    const open = this.#openTrigger;
+    if (open && this.#holdsFocus(this.#panelFor(open))) return;
+    this.#closeAll();
+  }
+  /** Whether `panel` exists and currently contains the focused element. */
+  #holdsFocus(panel) {
+    return panel?.contains(document.activeElement) ?? false;
+  }
   /** Wires hover open/close on each hover element (opt-in), tracking what was wired. */
   #addHoverListeners() {
     for (const element of this.#hoverElements) {
@@ -318,14 +442,17 @@ var NavigationMenuController = class extends Controller {
       element.removeEventListener("mouseleave", this.#onPointerLeave);
     }
     this.#hoverWired.clear();
+    this.#hoveredTrigger = null;
   }
   /**
    * Rebuilds the hover wiring from the current targets. Target callbacks call
    * this so items added or removed after connect (e.g. a Turbo Stream append)
    * participate in hover; the wired-set removal keeps the rebuild symmetric.
+   * Stimulus fires those callbacks during teardown too, hence the `#connected`
+   * guard — a rebuild after `disconnect()` would resurrect the listeners.
    */
   #rewireHoverListeners() {
-    if (!this.openOnHoverValue) return;
+    if (!this.#connected || !this.openOnHoverValue) return;
     this.#removeHoverListeners();
     this.#addHoverListeners();
   }

data/dist/controllers/number_input_controller.js

@@ -2,6 +2,12 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/number_input_controller.ts
 
+// src/utils/arrow_step.ts
+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");
+}
+
 // src/utils/safe_timeout.ts
 var TimerRegistry = class {
   /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
@@ -148,6 +154,7 @@ var NumberInputController = class _NumberInputController extends Controller {
   }
   /** Keyboard stepping per the APG spinbutton model. */
   onKeydown(event) {
+    if (isReservedArrowChord(event)) return;
     const page = this.pageStepValue > 0 ? this.pageStepValue : this.stepValue * 10;
     let next = null;
     switch (event.key) {

data/dist/controllers/otp_controller.js

@@ -2,6 +2,22 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/otp_controller.ts
 
+// src/utils/logical_scroll.ts
+function isRtl(element) {
+  return window.getComputedStyle(element).direction === "rtl";
+}
+
+// src/utils/arrow_step.ts
+function logicalArrowKey(key, element) {
+  if (key !== "ArrowRight" && key !== "ArrowLeft") return key;
+  if (!isRtl(element)) return key;
+  return key === "ArrowRight" ? "ArrowLeft" : "ArrowRight";
+}
+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");
+}
+
 // src/utils/composition_tracker.ts
 var CompositionTracker = class {
   #observedTargets = /* @__PURE__ */ new Set();
@@ -99,12 +115,13 @@ var OtpController = class extends Controller {
   }
   /** Handles Backspace retreating, arrows, and home/end navigation. */
   onKeydown(event) {
+    if (isReservedArrowChord(event)) return;
     const input = event.currentTarget;
     if (!input) return;
     const index = this.fieldTargets.indexOf(input);
     if (index === -1) return;
     if (this.#composition.isComposing(event)) return;
-    switch (event.key) {
+    switch (logicalArrowKey(event.key, this.element)) {
       case "Backspace":
         if (!input.value) {
           if (index > 0) {

data/dist/controllers/overflow_indicator_controller.js

@@ -2,6 +2,61 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/overflow_indicator_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/layout_observer.ts
 var LayoutObserver = class {
   #callback;
@@ -97,7 +152,16 @@ var OverflowIndicatorController = class extends Controller {
   #observedViewport = null;
   #observedContent = /* @__PURE__ */ new Set();
   #mutationObserver = null;
-  #pendingButtonDisables = /* @__PURE__ */ new Map();
+  /**
+   * Boundary buttons whose native `disabled` is held back while they hold focus.
+   *
+   * Completing the deferral is what actually disables the button, so the release
+   * callback — unlike {@link #cancelPendingButtonDisable} — applies it.
+   */
+  #pendingButtonDisables = new BlurDeferral((button) => {
+    this.#restorePendingMarkers(button);
+    if (!button.disabled) this.#disableButton(button);
+  });
   /** Last reported room, so `change` fires only on transitions. */
   #state = null;
   connect() {
@@ -155,7 +219,7 @@ var OverflowIndicatorController = class extends Controller {
     const page = horizontal ? vp.clientWidth : vp.clientHeight;
     const logicalDelta = direction === "start" ? -page : page;
     const delta = physicalScrollDelta(vp, horizontal, logicalDelta);
-    const behavior = prefersReducedMotion() ? "auto" : "smooth";
+    const behavior = prefersReducedMotion() ? "instant" : "smooth";
     if (horizontal) {
       vp.scrollBy({ left: delta, behavior });
     } else {
@@ -164,7 +228,7 @@ var OverflowIndicatorController = class extends Controller {
   }
   /** Mirrors remaining room onto any direction buttons by toggling `disabled`. */
   #syncButtons(start, end) {
-    for (const button of [...this.#pendingButtonDisables.keys()]) {
+    for (const button of this.#pendingButtonDisables.elements) {
       if (!button.isConnected || button.closest("[data-controller~='stimeo--overflow-indicator']") !== this.element) {
         this.#cancelPendingButtonDisable(button);
       }
@@ -216,21 +280,25 @@ var OverflowIndicatorController = class extends Controller {
       button.getAttribute("aria-disabled") ?? ""
     );
     button.setAttribute("aria-disabled", "true");
-    const onBlur = () => {
-      this.#cancelPendingButtonDisable(button);
-      if (!button.disabled) this.#disableButton(button);
-    };
-    this.#pendingButtonDisables.set(button, { onBlur });
-    button.addEventListener("blur", onBlur);
+    this.#pendingButtonDisables.defer(button);
   }
   #disableButton(button) {
     button.disabled = true;
     button.setAttribute("data-overflow-indicator-disabled", "");
   }
+  /** Cancels a pending disable without applying it, restoring the displaced state. */
   #cancelPendingButtonDisable(button) {
-    const pending = this.#pendingButtonDisables.get(button);
-    if (pending) button.removeEventListener("blur", pending.onBlur);
-    this.#pendingButtonDisables.delete(button);
+    this.#pendingButtonDisables.release(button);
+    this.#restorePendingMarkers(button);
+  }
+  /**
+   * Drops the pending marker and gives back the `aria-disabled` it displaced.
+   *
+   * Reads the displaced value from the DOM rather than memory: a Turbo snapshot is
+   * cloned before `disconnect()` runs, so a restored page can arrive with markers
+   * this instance never wrote.
+   */
+  #restorePendingMarkers(button) {
     button.removeAttribute("data-overflow-indicator-pending-disabled");
     const displaced = button.getAttribute("data-overflow-indicator-aria-disabled");
     if (displaced !== null) {
@@ -242,7 +310,7 @@ var OverflowIndicatorController = class extends Controller {
     }
   }
   #clearPendingButtonDisables() {
-    for (const button of [...this.#pendingButtonDisables.keys()]) {
+    for (const button of this.#pendingButtonDisables.elements) {
       this.#cancelPendingButtonDisable(button);
     }
   }