stimeo-ui 0.1.0.pre.alpha.1

data/dist/controllers/confirm_controller.js

@@ -0,0 +1,276 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/confirm_controller.ts
+
+// src/utils/focus_trap.ts
+var FOCUSABLE = 'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+var FocusTrap = class {
+  /** The element focused before activation, restored on deactivation. */
+  #previouslyFocused = null;
+  /** The body's inline `overflow` before locking, restored on deactivation. */
+  #previousBodyOverflow = "";
+  /** Whether scroll was locked this activation (so it is only restored if applied). */
+  #scrollLocked = false;
+  /** Background siblings made `inert` while active, restored on deactivation. */
+  #inertedSiblings = [];
+  /** Whether the modal side effects are currently applied. */
+  #activeState = false;
+  /** Returns the trapped element; called on every operation for the live target. */
+  #getContainer;
+  /** Closing/focus hooks; see {@link FocusTrapOptions}. */
+  #options;
+  /**
+   * @param getContainer - Returns the trapped element. Called on every operation
+   *   so the live target is always used.
+   * @param options - Closing/focus hooks; see {@link FocusTrapOptions}.
+   */
+  constructor(getContainer, options = {}) {
+    this.#getContainer = getContainer;
+    this.#options = options;
+  }
+  /** Whether the trap is currently active. */
+  get active() {
+    return this.#activeState;
+  }
+  /**
+   * Applies the trap: records the current focus, optionally locks background scroll
+   * and makes background siblings `inert`, listens for `Tab`/`Escape`, and (unless
+   * `autoFocus` is off) moves focus inside. No-ops if already active.
+   */
+  activate() {
+    if (this.#activeState) return;
+    this.#activeState = true;
+    const active = document.activeElement;
+    this.#previouslyFocused = active instanceof HTMLElement && active !== document.body ? active : null;
+    if (this.#flag(this.#options.lockScroll, true)) {
+      this.#previousBodyOverflow = document.body.style.overflow;
+      document.body.style.overflow = "hidden";
+      this.#scrollLocked = true;
+    }
+    if (this.#flag(this.#options.isolate, true)) this.#isolateBackground();
+    document.addEventListener("keydown", this.#onKeydown);
+    if (this.#flag(this.#options.autoFocus, true)) this.#focusInitial();
+  }
+  /**
+   * Reverts every side effect applied by {@link activate}. No-ops if inactive, so
+   * a controller can call it defensively from both `close()` and `disconnect()`.
+   *
+   * @param restoreFocus - Move focus back to the opener (default `true`). Pass
+   *   `false` on teardown (`disconnect`), where yanking focus is undesirable.
+   */
+  deactivate({ restoreFocus = true } = {}) {
+    if (!this.#activeState) return;
+    this.#activeState = false;
+    document.removeEventListener("keydown", this.#onKeydown);
+    if (this.#scrollLocked) {
+      document.body.style.overflow = this.#previousBodyOverflow;
+      this.#scrollLocked = false;
+    }
+    this.#releaseBackground();
+    if (restoreFocus) {
+      const target = this.#previouslyFocused ?? this.#options.fallbackFocus?.() ?? null;
+      target?.focus();
+    }
+  }
+  /** Resolves a boolean-or-getter option, defaulting when it was not provided. */
+  #flag(option, fallback) {
+    if (option === void 0) return fallback;
+    return typeof option === "function" ? option() : option;
+  }
+  /** Handles `Escape` (delegated) and `Tab` (focus trap) while active. */
+  #onKeydown = (event) => {
+    if (event.key === "Escape") {
+      if (this.#options.onEscape) {
+        event.preventDefault();
+        this.#options.onEscape();
+      }
+      return;
+    }
+    if (event.key === "Tab") this.#trapTab(event);
+  };
+  /** Keeps `Tab` focus cycling within the container's focusable elements. */
+  #trapTab(event) {
+    const focusable = this.#focusableElements();
+    if (focusable.length === 0) {
+      event.preventDefault();
+      return;
+    }
+    const first = focusable[0];
+    const last = focusable[focusable.length - 1];
+    const active = document.activeElement;
+    if (!(active instanceof Node) || !this.#getContainer().contains(active)) {
+      event.preventDefault();
+      first?.focus();
+      return;
+    }
+    if (event.shiftKey && active === first) {
+      event.preventDefault();
+      last?.focus();
+    } else if (!event.shiftKey && active === last) {
+      event.preventDefault();
+      first?.focus();
+    }
+  }
+  /**
+   * Marks every element outside the container's subtree as `inert` so background
+   * 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.
+   */
+  #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);
+    }
+  }
+  /** Reverts the `inert` flags applied by `#isolateBackground`. */
+  #releaseBackground() {
+    for (const sibling of this.#inertedSiblings) {
+      sibling.inert = false;
+    }
+    this.#inertedSiblings = [];
+  }
+  /** Moves focus to the initial target, the first focusable, or the container. */
+  #focusInitial() {
+    const preferred = this.#options.initialFocus?.();
+    if (preferred) {
+      preferred.focus();
+      return;
+    }
+    const focusable = this.#focusableElements();
+    if (focusable[0]) {
+      focusable[0].focus();
+      return;
+    }
+    const container = this.#getContainer();
+    container.tabIndex = -1;
+    container.focus();
+  }
+  /** Collects the container's currently focusable descendants in DOM order. */
+  #focusableElements() {
+    return Array.from(this.#getContainer().querySelectorAll(FOCUSABLE)).filter(
+      (el) => !el.hidden
+    );
+  }
+};
+
+// src/controllers/confirm_controller.ts
+var ConfirmController = class extends Controller {
+  static targets = ["dialog", "title", "message", "confirm", "cancel"];
+  static values = {
+    confirmLabel: { type: String, default: "OK" },
+    cancelLabel: { type: String, default: "Cancel" },
+    initialFocus: { type: String, default: "cancel" }
+  };
+  static actions = ["confirm", "cancel", "request"];
+  static events = ["open", "resolve"];
+  /** Resolver for the in-flight confirmation Promise (one dialog at a time). */
+  #pending = null;
+  /** Turbo's forms config and its original confirm method, for restore. */
+  #turboForms = null;
+  #previousConfirm = void 0;
+  #trap = new FocusTrap(() => this.dialogTarget, {
+    onEscape: () => this.#resolve(false),
+    initialFocus: () => this.#initialFocusElement()
+  });
+  connect() {
+    if (this.hasDialogTarget) this.dialogTarget.hidden = true;
+    this.#installTurboHook();
+  }
+  disconnect() {
+    if (this.#turboForms) {
+      this.#turboForms.confirm = this.#previousConfirm;
+      this.#turboForms = null;
+    }
+    this.#resolve(false, false);
+    this.#trap.deactivate({ restoreFocus: false });
+  }
+  /** Confirms the pending request (resolves `true`). Bound via `data-action`. */
+  confirm() {
+    this.#resolve(true);
+  }
+  /** Cancels the pending request (resolves `false`). Bound via `data-action`. */
+  cancel() {
+    this.#resolve(false);
+  }
+  /**
+   * Intercepts a link/button click, shows the confirm dialog, and continues the
+   * original action (form submit or navigation) only when confirmed. The message
+   * comes from the `message` action param or the element's `data-turbo-confirm`.
+   */
+  request(event) {
+    const element = event.currentTarget ?? event.target;
+    if (!element) return;
+    event.preventDefault();
+    const params = event.params;
+    const fromParam = typeof params?.message === "string" ? params.message : null;
+    const message = fromParam ?? element.getAttribute("data-turbo-confirm") ?? "";
+    void this.#prompt(message).then((confirmed) => {
+      if (confirmed) this.#continue(element);
+    });
+  }
+  /**
+   * Opens the dialog for `message` and resolves once the user confirms or cancels.
+   * Degrades to native `window.confirm` when no dialog target is present.
+   */
+  #prompt(message) {
+    if (!this.hasDialogTarget) return Promise.resolve(window.confirm(message));
+    this.#resolve(false);
+    if (this.hasMessageTarget) this.messageTarget.textContent = message;
+    if (this.hasConfirmTarget) this.confirmTarget.textContent = this.confirmLabelValue;
+    if (this.hasCancelTarget) this.cancelTarget.textContent = this.cancelLabelValue;
+    return new Promise((resolve) => {
+      this.#pending = resolve;
+      this.dialogTarget.hidden = false;
+      this.dispatch("open", { detail: { message } });
+      this.#trap.activate();
+    });
+  }
+  /**
+   * Settles the pending Promise, closes the dialog, and emits `resolve`.
+   * `restoreFocus` is forwarded to the trap so teardown (disconnect) can settle a
+   * pending confirmation without moving focus.
+   */
+  #resolve(confirmed, restoreFocus = true) {
+    const pending = this.#pending;
+    if (!pending) return;
+    this.#pending = null;
+    if (this.hasDialogTarget) this.dialogTarget.hidden = true;
+    this.#trap.deactivate({ restoreFocus });
+    this.dispatch("resolve", { detail: { confirmed } });
+    pending(confirmed);
+  }
+  /** Continues the intercepted action when confirmed: submit a form, else navigate. */
+  #continue(element) {
+    if (element instanceof HTMLAnchorElement && element.href) {
+      window.location.href = element.href;
+      return;
+    }
+    const form = element instanceof HTMLFormElement ? element : element.closest("form");
+    if (form) {
+      form.requestSubmit(element instanceof HTMLButtonElement ? element : void 0);
+    }
+  }
+  /** Swaps Turbo's confirm method for a Promise-returning bridge to this dialog. */
+  #installTurboHook() {
+    const turbo = window.Turbo;
+    const forms = turbo?.config?.forms;
+    if (!forms) return;
+    this.#turboForms = forms;
+    this.#previousConfirm = forms.confirm;
+    forms.confirm = (message) => this.#prompt(message);
+  }
+  /** The button to focus on open — the least-destructive one (cancel) by default. */
+  #initialFocusElement() {
+    if (this.initialFocusValue === "confirm" && this.hasConfirmTarget) return this.confirmTarget;
+    return this.hasCancelTarget ? this.cancelTarget : null;
+  }
+};
+
+export { ConfirmController };
+//# sourceMappingURL=confirm_controller.js.map
+//# sourceMappingURL=confirm_controller.js.map

data/dist/controllers/context_menu_controller.js

@@ -0,0 +1,112 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/context_menu_controller.ts
+var ContextMenuController = class extends Controller {
+  static targets = ["region", "menu", "item"];
+  static actions = ["activate", "onItemKeydown", "onRegionKeydown", "open"];
+  /** Starts closed and registers the outside-click listener. */
+  connect() {
+    this.#closeMenu();
+    document.addEventListener("click", this.#onOutsideClick);
+  }
+  /** Removes the document-level listener registered in {@link connect}. */
+  disconnect() {
+    document.removeEventListener("click", this.#onOutsideClick);
+  }
+  /**
+   * Opens the menu from a `contextmenu` event: suppresses the native menu and
+   * places this one at the pointer coordinate.
+   */
+  open(event) {
+    event.preventDefault();
+    this.#openAt(event.clientX, event.clientY);
+  }
+  /** Keyboard entry on the region: `Shift+F10` / `ContextMenu` open at center. */
+  onRegionKeydown(event) {
+    const isContextKey = event.key === "ContextMenu" || event.key === "F10" && event.shiftKey;
+    if (!isContextKey) return;
+    event.preventDefault();
+    const rect = this.hasRegionTarget ? this.regionTarget.getBoundingClientRect() : { left: 0, top: 0, width: 0, height: 0 };
+    this.#openAt(rect.left + rect.width / 2, rect.top + rect.height / 2);
+  }
+  /** Roving focus and closing keys inside the menu. */
+  onItemKeydown(event) {
+    const items = this.#navigableItems;
+    const currentIndex = items.indexOf(event.currentTarget);
+    switch (event.key) {
+      case "ArrowDown":
+        event.preventDefault();
+        if (items.length > 0) items[(currentIndex + 1) % items.length]?.focus();
+        break;
+      case "ArrowUp":
+        event.preventDefault();
+        if (items.length > 0) items[(currentIndex - 1 + items.length) % items.length]?.focus();
+        break;
+      case "Home":
+        event.preventDefault();
+        items[0]?.focus();
+        break;
+      case "End":
+        event.preventDefault();
+        items[items.length - 1]?.focus();
+        break;
+      case "Escape":
+        event.preventDefault();
+        this.#closeAndRestore();
+        break;
+      case "Tab":
+        this.#closeMenu();
+        break;
+    }
+  }
+  /** Closes after an item is activated and restores focus to the region. */
+  activate() {
+    this.#closeAndRestore();
+  }
+  /** Opens the menu at viewport coordinates `(x, y)` and focuses the first item. */
+  #openAt(x, y) {
+    if (!this.hasMenuTarget) return;
+    this.menuTarget.style.setProperty("--stimeo-context-menu-x", `${x}px`);
+    this.menuTarget.style.setProperty("--stimeo-context-menu-y", `${y}px`);
+    this.menuTarget.hidden = false;
+    if (this.hasRegionTarget) this.regionTarget.setAttribute("data-state", "open");
+    this.#navigableItems[0]?.focus();
+  }
+  /** Hides the menu and reflects the collapsed state on the region. */
+  #closeMenu() {
+    if (!this.hasMenuTarget) return;
+    this.menuTarget.hidden = true;
+    if (this.hasRegionTarget) this.regionTarget.setAttribute("data-state", "closed");
+  }
+  /** Closes the menu and returns focus to the region (Escape / activation). */
+  #closeAndRestore() {
+    this.#closeMenu();
+    if (this.hasRegionTarget) this.regionTarget.focus();
+  }
+  /** Closes the menu when a click lands outside the controller's element. */
+  #onOutsideClick = (event) => {
+    if (this.#isOpen && !this.element.contains(event.target)) this.#closeMenu();
+  };
+  /** Menu items eligible for roving focus (excludes disabled / hidden). */
+  get #navigableItems() {
+    return this.itemTargets.filter((item) => this.#isNavigable(item));
+  }
+  /**
+   * An item can take roving focus unless it is `hidden`, `aria-disabled="true"`,
+   * or a natively `disabled` form control. CSS-only visibility is not detectable
+   * here and is the consumer's responsibility.
+   */
+  #isNavigable(item) {
+    if (item.hasAttribute("hidden")) return false;
+    if (item.getAttribute("aria-disabled") === "true") return false;
+    return !item.disabled;
+  }
+  /** Whether the menu is currently visible. */
+  get #isOpen() {
+    return this.hasMenuTarget && !this.menuTarget.hidden;
+  }
+};
+
+export { ContextMenuController };
+//# sourceMappingURL=context_menu_controller.js.map
+//# sourceMappingURL=context_menu_controller.js.map

data/dist/controllers/countdown_controller.js

@@ -0,0 +1,202 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/countdown_controller.ts
+
+// 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 SafeInterval = class extends TimerRegistry {
+  /** Schedules a repeating `callback` every `delay` ms and returns the timer id. */
+  set(callback, delay) {
+    const id = this.schedule(callback, delay);
+    this.ids.add(id);
+    return id;
+  }
+  schedule(callback, delay) {
+    return window.setInterval(callback, delay);
+  }
+  cancel(id) {
+    window.clearInterval(id);
+  }
+};
+
+// src/controllers/countdown_controller.ts
+var CountdownController = class extends Controller {
+  static targets = ["days", "hours", "minutes", "seconds", "status"];
+  static values = {
+    deadline: { type: String, default: "" },
+    interval: { type: Number, default: 1e3 },
+    direction: { type: String, default: "down" },
+    autostart: { type: Boolean, default: true },
+    completeLabel: { type: String, default: "" }
+  };
+  static actions = ["pause", "reset", "resume", "start"];
+  static events = ["complete", "tick"];
+  #intervals = new SafeInterval();
+  #intervalId = null;
+  /** Epoch-ms anchor: the deadline (down) or the count-up origin (up). */
+  #reference = 0;
+  /** Amount (ms) captured at pause, so resume can restore the same display. */
+  #pausedAmount = 0;
+  connect() {
+    this.#initReference();
+    this.#render(this.#currentAmount());
+    if (this.autostartValue && this.#isValidDeadline) {
+      this.start();
+    } else {
+      this.element.setAttribute("data-state", "paused");
+    }
+  }
+  disconnect() {
+    this.#intervals.clearAll();
+    this.#intervalId = null;
+  }
+  /** Starts (or restarts after pause) ticking toward the deadline. */
+  start() {
+    if (this.#state === "running" || !this.#isValidDeadline) return;
+    if (this.#isDown && this.#currentAmount() <= 0) {
+      this.#complete();
+      return;
+    }
+    this.#runInterval();
+  }
+  /** Pauses ticking, preserving the currently displayed amount. */
+  pause() {
+    if (this.#state !== "running") return;
+    this.#pausedAmount = this.#currentAmount();
+    this.#teardownInterval();
+    this.element.setAttribute("data-state", "paused");
+  }
+  /** Resumes from a pause, continuing from the preserved amount. */
+  resume() {
+    if (this.#state !== "paused" || !this.#isValidDeadline) return;
+    const now = Date.now();
+    this.#reference = this.#isDown ? now + this.#pausedAmount : now - this.#pausedAmount;
+    this.start();
+  }
+  /**
+   * Re-syncs to the deadline and clears any pause offset, **preserving the current
+   * run state**: a running timer keeps counting down from the reset amount, while a
+   * paused (or completed) one resets the displayed amount but stays paused until the
+   * user resumes — it never silently restarts. The run state is read from the DOM,
+   * not re-derived from the declarative `autostart` Value (which only governs the
+   * initial state on connect); re-deriving it would override a user's pause, the same
+   * anti-pattern the Turbo-lifecycle guide warns about.
+   */
+  reset() {
+    const wasRunning = this.#state === "running";
+    this.#teardownInterval();
+    this.#initReference();
+    const amount = this.#currentAmount();
+    this.#render(amount);
+    if (this.hasStatusTarget) this.statusTarget.textContent = "";
+    this.element.setAttribute("data-state", "paused");
+    if (wasRunning && this.#isValidDeadline) {
+      this.#pausedAmount = 0;
+      this.start();
+    } else {
+      this.#pausedAmount = amount;
+    }
+  }
+  /** Schedules the repeating tick and marks the timer running. */
+  #runInterval() {
+    this.element.setAttribute("data-state", "running");
+    this.#intervalId = this.#intervals.set(() => this.#tick(), this.intervalValue);
+  }
+  /** Cancels the repeating tick, if any. */
+  #teardownInterval() {
+    if (this.#intervalId !== null) {
+      this.#intervals.clear(this.#intervalId);
+      this.#intervalId = null;
+    }
+  }
+  /** Recomputes, renders, emits `tick`, and completes when a countdown hits 0. */
+  #tick() {
+    const amount = this.#currentAmount();
+    this.#render(amount);
+    this.dispatch("tick", {
+      detail: { remaining: amount, direction: this.#isDown ? "down" : "up" }
+    });
+    if (this.#isDown && this.#reference - Date.now() <= 0) {
+      this.#complete();
+    }
+  }
+  /** Stops at zero, marks completion, announces it, and emits `complete`. */
+  #complete() {
+    this.#teardownInterval();
+    this.#render(0);
+    this.element.setAttribute("data-state", "complete");
+    if (this.hasStatusTarget && this.completeLabelValue.length > 0) {
+      this.statusTarget.textContent = this.completeLabelValue;
+    }
+    this.dispatch("complete", { detail: {} });
+  }
+  /** Sets the time anchor from the `deadline` value. */
+  #initReference() {
+    this.#reference = Date.parse(this.deadlineValue);
+  }
+  /** Remaining (down) or elapsed (up) ms, never negative. */
+  #currentAmount() {
+    if (!this.#isValidDeadline) return 0;
+    const now = Date.now();
+    const raw = this.#isDown ? this.#reference - now : now - this.#reference;
+    return Math.max(0, raw);
+  }
+  /** Writes the amount into the day/hour/minute/second slots. */
+  #render(amount) {
+    const totalSeconds = Math.floor(amount / 1e3);
+    const days = Math.floor(totalSeconds / 86400);
+    const hours = Math.floor(totalSeconds % 86400 / 3600);
+    const minutes = Math.floor(totalSeconds % 3600 / 60);
+    const seconds = totalSeconds % 60;
+    if (this.hasDaysTarget) this.daysTarget.textContent = String(days);
+    if (this.hasHoursTarget) this.hoursTarget.textContent = this.#pad(hours);
+    if (this.hasMinutesTarget) this.minutesTarget.textContent = this.#pad(minutes);
+    if (this.hasSecondsTarget) this.secondsTarget.textContent = this.#pad(seconds);
+  }
+  /** Zero-pads a unit to two digits. */
+  #pad(unit) {
+    return String(unit).padStart(2, "0");
+  }
+  get #isDown() {
+    return this.directionValue !== "up";
+  }
+  get #isValidDeadline() {
+    return !Number.isNaN(this.#reference);
+  }
+  /** Current lifecycle phase as reflected on `data-state`. */
+  get #state() {
+    return this.element.getAttribute("data-state") ?? "paused";
+  }
+};
+
+export { CountdownController };
+//# sourceMappingURL=countdown_controller.js.map
+//# sourceMappingURL=countdown_controller.js.map