stimeo-ui 0.2.0 → 0.3.0

data/dist/controllers/navigation_menu_controller.js

@@ -0,0 +1,511 @@
+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 () => {
+    const active = element.ownerDocument.activeElement;
+    return active === null || active === element.ownerDocument.body || element.contains(active);
+  };
+}
+var EscapeLayer = class _EscapeLayer {
+  static #registries = /* @__PURE__ */ new WeakMap();
+  #ownerDocument = null;
+  /** Dismissal callback while active; `null` when inactive. */
+  #onDismiss = null;
+  /** Live predicate deciding whether the layer claims a press; `null` = always. */
+  #claims = null;
+  /**
+   * Activates this layer at the top of its document's Escape stack, installing
+   * the document's shared resolver listener if this is its first layer.
+   * Re-activating an already-active layer moves it to the top.
+   */
+  activate(ownerDocument = document, options) {
+    this.deactivate();
+    let registry = _EscapeLayer.#registries.get(ownerDocument);
+    if (!registry) {
+      registry = _EscapeLayer.#createRegistry();
+      _EscapeLayer.#registries.set(ownerDocument, registry);
+      ownerDocument.addEventListener("keydown", registry.onKeydown);
+    }
+    registry.stack.push(this);
+    this.#ownerDocument = ownerDocument;
+    this.#onDismiss = options.onDismiss;
+    this.#claims = options.claims ?? null;
+  }
+  /**
+   * Removes this layer from its document's Escape stack, uninstalling the
+   * shared listener when the stack empties. Safe to call when inactive.
+   */
+  deactivate() {
+    const ownerDocument = this.#ownerDocument;
+    if (!ownerDocument) return;
+    const registry = _EscapeLayer.#registries.get(ownerDocument);
+    if (registry) {
+      const index = registry.stack.lastIndexOf(this);
+      if (index >= 0) registry.stack.splice(index, 1);
+      if (registry.stack.length === 0) {
+        ownerDocument.removeEventListener("keydown", registry.onKeydown);
+        _EscapeLayer.#registries.delete(ownerDocument);
+      }
+    }
+    this.#ownerDocument = null;
+    this.#onDismiss = null;
+    this.#claims = null;
+  }
+  /**
+   * Whether this active layer would own a press right now: it is the topmost
+   * layer whose {@link EscapeLayerOptions.claims} passes. Exposed for tests
+   * and diagnostics — production dismissal goes through the shared listener.
+   */
+  get ownsEscape() {
+    const ownerDocument = this.#ownerDocument;
+    if (!ownerDocument) return false;
+    const registry = _EscapeLayer.#registries.get(ownerDocument);
+    if (!registry) return false;
+    return _EscapeLayer.#resolveOwner(registry.stack) === this;
+  }
+  /** Builds a document's registry with its shared resolver listener. */
+  static #createRegistry() {
+    const registry = {
+      stack: [],
+      onKeydown: (event) => {
+        if (event.key !== "Escape" || event.defaultPrevented || event.isComposing) return;
+        const owner = _EscapeLayer.#resolveOwner(registry.stack);
+        if (!owner) return;
+        event.preventDefault();
+        owner.#onDismiss?.();
+      }
+    };
+    return registry;
+  }
+  /** The topmost stack layer whose claims predicate passes, or `null`. */
+  static #resolveOwner(stack) {
+    for (let index = stack.length - 1; index >= 0; index--) {
+      const layer = stack[index];
+      if (!layer) continue;
+      if (layer.#claims && !layer.#claims()) continue;
+      return layer;
+    }
+    return null;
+  }
+};
+
+// src/utils/safe_timeout.ts
+var TimerRegistry = class {
+  /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
+  ids = /* @__PURE__ */ new Set();
+  /**
+   * Cancels a single tracked timer.
+   *
+   * No-ops if the id is unknown (already cleared, fired, or never owned by this
+   * registry), so callers can clear defensively without guarding.
+   */
+  clear(id) {
+    if (this.ids.delete(id)) {
+      this.cancel(id);
+    }
+  }
+  /**
+   * Cancels every tracked timer. Call this from a controller's `disconnect()`
+   * to guarantee no timer outlives the element.
+   */
+  clearAll() {
+    for (const id of this.ids) {
+      this.cancel(id);
+    }
+    this.ids.clear();
+  }
+  /** Number of timers currently tracked (pending). */
+  get size() {
+    return this.ids.size;
+  }
+};
+var SafeTimeout = class extends TimerRegistry {
+  /**
+   * Schedules `callback` after `delay` ms and returns the timer id.
+   *
+   * The id is removed from the registry automatically when the timeout fires,
+   * so {@link TimerRegistry.size | size} reflects only still-pending timers.
+   */
+  set(callback, delay) {
+    const id = this.schedule(() => {
+      this.ids.delete(id);
+      callback();
+    }, delay);
+    this.ids.add(id);
+    return id;
+  }
+  schedule(callback, delay) {
+    return window.setTimeout(callback, delay);
+  }
+  cancel(id) {
+    window.clearTimeout(id);
+  }
+};
+
+// src/controllers/navigation_menu_controller.ts
+var NavigationMenuController = class extends Controller {
+  static targets = ["trigger", "panel", "hoverArea"];
+  static values = {
+    openOnHover: { type: Boolean, default: false },
+    hoverDelay: { type: Number, default: 150 }
+  };
+  static actions = ["onTriggerKeydown", "toggle"];
+  /** Open/close delay timers for hover mode; cleared together on disconnect. */
+  #hoverTimers = new SafeTimeout();
+  /**
+   * Elements currently carrying hover listeners. Removal always mirrors this
+   * 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, true);
+    this.element.addEventListener("focusout", this.#onFocusOut);
+    if (this.openOnHoverValue) this.#addHoverListeners();
+  }
+  /** Removes every listener, pending hover timer, and stack membership taken while connected. */
+  disconnect() {
+    this.#connected = false;
+    this.#escapeLayer.deactivate();
+    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();
+  }
+  /** Re-wires hover listeners when a target is removed while connected. */
+  triggerTargetDisconnected() {
+    this.#rewireHoverListeners();
+  }
+  /** See {@link NavigationMenuController.triggerTargetConnected}. */
+  panelTargetConnected() {
+    this.#rewireHoverListeners();
+  }
+  /** See {@link NavigationMenuController.triggerTargetDisconnected}. */
+  panelTargetDisconnected() {
+    this.#rewireHoverListeners();
+  }
+  /** See {@link NavigationMenuController.triggerTargetConnected}. */
+  hoverAreaTargetConnected() {
+    this.#rewireHoverListeners();
+  }
+  /** See {@link NavigationMenuController.triggerTargetDisconnected}. */
+  hoverAreaTargetDisconnected() {
+    this.#rewireHoverListeners();
+  }
+  /**
+   * 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;
+    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).
+   *
+   * 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) {
+    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. 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;
+    panel.hidden = false;
+    trigger.setAttribute("aria-expanded", "true");
+    this.#syncEscapeLayer();
+  }
+  /** Closes `trigger`'s panel and reflects the collapsed state. */
+  #closePanel(trigger) {
+    const panel = this.#panelFor(trigger);
+    if (panel) panel.hidden = true;
+    trigger.setAttribute("aria-expanded", "false");
+    this.#syncEscapeLayer();
+  }
+  /**
+   * 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
+   * user switches panels is deliberate — the nav is again the newest layer.
+   */
+  #syncEscapeLayer() {
+    if (this.#isAnyOpen) {
+      this.#escapeLayer.activate(document, {
+        onDismiss: () => this.#closeAndRestore(),
+        claims: claimsWhileFocusWithin(this.element)
+      });
+    } else {
+      this.#escapeLayer.deactivate();
+    }
+  }
+  /**
+   * 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();
+  }
+  /** Closes panels when a click lands outside the nav element. */
+  #onOutsideClick = (event) => {
+    if (this.#isAnyOpen && !this.element.contains(event.target)) this.#closeAll();
+  };
+  /**
+   * Closes (without restoring focus) when focus leaves the nav for a known
+   * external destination. A null/non-Node destination is indeterminate:
+   * browsers use it for clicks on non-focusable content and for window
+   * deactivation, so those never close the nav here (matching the popover
+   * convention) — the outside-click handler decides pointer dismissal, and the
+   * Escape stack's body-focus claim keeps keyboard dismissal working.
+   */
+  #onFocusOut = (event) => {
+    const next = event.relatedTarget;
+    if (!(next instanceof Node) || this.element.contains(next)) return;
+    this.#closeAll();
+  };
+  /** Opens a trigger's panel after the hover delay (hover mode). */
+  #onPointerEnter = (event) => {
+    const trigger = this.#triggerForHover(event.currentTarget);
+    if (!trigger) return;
+    this.#hoveredTrigger = trigger;
+    this.#hoverTimers.clearAll();
+    this.#hoverTimers.set(() => this.#openFromHover(trigger), this.hoverDelayValue);
+  };
+  /**
+   * Closes the open panel after the hover delay (hover mode) — unless the
+   * pointer moved directly into another part of the hover region (an adjacent
+   * trigger, panel, or hoverArea): crossing a shared edge must not schedule a
+   * spurious close, e.g. a hoverArea whose panel sits outside it as a sibling.
+   */
+  #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.#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) {
+      element.addEventListener("mouseenter", this.#onPointerEnter);
+      element.addEventListener("mouseleave", this.#onPointerLeave);
+      this.#hoverWired.add(element);
+    }
+  }
+  /** Removes the hover listeners from exactly the elements that were wired. */
+  #removeHoverListeners() {
+    for (const element of this.#hoverWired) {
+      element.removeEventListener("mouseenter", this.#onPointerEnter);
+      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.#connected || !this.openOnHoverValue) return;
+    this.#removeHoverListeners();
+    this.#addHoverListeners();
+  }
+  /**
+   * Elements that participate in hover: each `hoverArea`, plus every trigger and
+   * panel **not** wrapped by one. A wrapped trigger/panel must defer to its
+   * wrapper — its own mouseleave would otherwise schedule a close while the
+   * pointer is still inside the area (mouseenter does not re-fire on the wrapper
+   * when moving among its descendants), flickering the panel shut.
+   */
+  get #hoverElements() {
+    const areas = this.hoverAreaTargets;
+    const covered = (element) => areas.some((area) => area.contains(element));
+    return [
+      ...areas,
+      ...this.triggerTargets.filter((trigger) => !covered(trigger)),
+      ...this.panelTargets.filter((panel) => !covered(panel))
+    ];
+  }
+  /**
+   * Resolves the trigger for a hovered element: the trigger itself, the trigger
+   * controlling a hovered panel, or the first trigger contained in a hovered
+   * `hoverArea` wrapper.
+   */
+  #triggerForHover(element) {
+    if (this.triggerTargets.includes(element)) return element;
+    if (this.panelTargets.includes(element)) {
+      return this.triggerTargets.find((trigger) => this.#panelFor(trigger) === element) ?? null;
+    }
+    if (this.hoverAreaTargets.includes(element)) {
+      return this.triggerTargets.find((trigger) => element.contains(trigger)) ?? null;
+    }
+    return null;
+  }
+  /** The panel controlled by `trigger` (matched by `aria-controls`/`id`). */
+  #panelFor(trigger) {
+    const id = trigger.getAttribute("aria-controls");
+    return id ? this.panelTargets.find((panel) => panel.id === id) ?? null : null;
+  }
+  /** Whether `trigger`'s panel is currently expanded. */
+  #isExpanded(trigger) {
+    return trigger.getAttribute("aria-expanded") === "true";
+  }
+  /** The trigger whose panel is currently open, if any. */
+  get #openTrigger() {
+    return this.triggerTargets.find((trigger) => this.#isExpanded(trigger)) ?? null;
+  }
+  /** Whether any panel is currently open. */
+  get #isAnyOpen() {
+    return this.#openTrigger !== null;
+  }
+};
+
+export { NavigationMenuController };
+//# sourceMappingURL=navigation_menu_controller.js.map
+//# sourceMappingURL=navigation_menu_controller.js.map

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) {