stimeo-ui 0.1.0.pre.alpha.1

data/dist/controllers/flash_controller.js

@@ -0,0 +1,221 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/flash_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 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/flash_controller.ts
+var ASSERTIVE_TYPES = /* @__PURE__ */ new Set(["alert", "error"]);
+var MESSAGE_SELECTOR = '[data-stimeo--flash-target="message"]';
+var FlashController = class extends Controller {
+  static targets = ["region", "message"];
+  static values = {
+    duration: { type: Number, default: 5e3 },
+    pauseOnHover: { type: Boolean, default: true },
+    max: { type: Number, default: 0 }
+  };
+  static actions = ["dismiss"];
+  static events = ["show", "dismiss"];
+  #timers = new SafeTimeout();
+  #observer = null;
+  /** Auto-dismiss timer state keyed by message element. */
+  #state = /* @__PURE__ */ new Map();
+  /** Messages already processed, in insertion order, to enforce `max` and avoid double work. */
+  #order = [];
+  #onEnter = (event) => this.#pause(event.currentTarget);
+  #onLeave = (event) => this.#resume(event.currentTarget);
+  connect() {
+    if (!this.hasRegionTarget) return;
+    for (const message of this.messageTargets) {
+      this.#process(message, true);
+    }
+    if (typeof MutationObserver !== "undefined") {
+      this.#observer = new MutationObserver((mutations) => this.#onMutations(mutations));
+      this.#observer.observe(this.regionTarget, { childList: true, subtree: true });
+    }
+  }
+  disconnect() {
+    this.#observer?.disconnect();
+    this.#observer = null;
+    this.#timers.clearAll();
+    for (const message of this.#order) this.#unbindPause(message);
+    this.#state.clear();
+    this.#order.length = 0;
+  }
+  /**
+   * Pause-on-hover/focus listeners, bound and unbound as a pair so the two sides
+   * stay in sync. Binding is gated by `pauseOnHover`; unbinding is unconditional
+   * and idempotent (a no-op when nothing was bound), which keeps teardown correct
+   * even if `pauseOnHover` were ever toggled during a message's life.
+   */
+  #bindPause(message) {
+    if (!this.pauseOnHoverValue) return;
+    message.addEventListener("mouseenter", this.#onEnter);
+    message.addEventListener("mouseleave", this.#onLeave);
+    message.addEventListener("focusin", this.#onEnter);
+    message.addEventListener("focusout", this.#onLeave);
+  }
+  #unbindPause(message) {
+    message.removeEventListener("mouseenter", this.#onEnter);
+    message.removeEventListener("mouseleave", this.#onLeave);
+    message.removeEventListener("focusin", this.#onEnter);
+    message.removeEventListener("focusout", this.#onLeave);
+  }
+  /** Dismisses the flash whose close control fired the event. */
+  dismiss(event) {
+    const target = event.currentTarget || event.target;
+    const message = target?.closest(MESSAGE_SELECTOR);
+    if (message) this.#beginDismiss(message, "user");
+  }
+  /** Processes messages added after connect (Turbo Stream); their own role announces them. */
+  #onMutations(mutations) {
+    for (const mutation of mutations) {
+      for (const node of mutation.addedNodes) {
+        if (!(node instanceof HTMLElement)) continue;
+        if (node.matches(MESSAGE_SELECTOR)) this.#process(node, false);
+        for (const message of node.querySelectorAll(MESSAGE_SELECTOR)) {
+          this.#process(message, false);
+        }
+      }
+    }
+  }
+  /**
+   * Applies role/state, wires pause listeners, schedules auto-dismiss, and either
+   * bridges to the Announcer (`bridge`, for initial flashes) or leaves the message's
+   * own role to do the announcing (dynamic inserts). Idempotent per message.
+   */
+  #process(message, bridge) {
+    if (this.#state.has(message) || this.#order.includes(message)) return;
+    const type = message.getAttribute("data-flash-type") ?? "";
+    const assertive = ASSERTIVE_TYPES.has(type);
+    if (!message.hasAttribute("role")) {
+      message.setAttribute("role", assertive ? "alert" : "status");
+    }
+    message.setAttribute("data-flash-state", "visible");
+    this.#order.push(message);
+    this.#bindPause(message);
+    const text = message.textContent?.trim() ?? "";
+    this.dispatch("show", { target: message, detail: { type, message: text } });
+    if (bridge && text) {
+      window.dispatchEvent(
+        new CustomEvent("stimeo--announcer:announce", { detail: { message: text, assertive } })
+      );
+    }
+    this.#startTimer(message);
+    this.#enforceMax();
+  }
+  /** Removes the oldest visible flashes once the count exceeds `max` (0 = unlimited). */
+  #enforceMax() {
+    if (this.maxValue <= 0) return;
+    while (this.#order.length > this.maxValue) {
+      const oldest = this.#order[0];
+      if (!oldest) break;
+      this.#beginDismiss(oldest, "limit");
+    }
+  }
+  #startTimer(message, duration = this.durationValue) {
+    if (duration <= 0) return;
+    const existing = this.#state.get(message);
+    if (existing?.id) this.#timers.clear(existing.id);
+    const id = this.#timers.set(() => this.#beginDismiss(message, "timeout"), duration);
+    this.#state.set(message, { id, startedAt: Date.now(), remaining: duration });
+  }
+  /** Pauses a message's auto-dismiss, banking the time left (hover/focus, WCAG 2.2.1). */
+  #pause(message) {
+    const timer = this.#state.get(message);
+    if (!timer || timer.id === 0) return;
+    this.#timers.clear(timer.id);
+    const remaining = Math.max(0, timer.remaining - (Date.now() - timer.startedAt));
+    this.#state.set(message, { id: 0, startedAt: 0, remaining });
+  }
+  /** Resumes a paused message's auto-dismiss with the banked time. */
+  #resume(message) {
+    const timer = this.#state.get(message);
+    if (!timer) return;
+    if (timer.id !== 0 || timer.remaining <= 0) return;
+    this.#startTimer(message, timer.remaining);
+  }
+  /** Marks a message leaving, then removes it after its CSS transition and emits dismiss. */
+  #beginDismiss(message, reason) {
+    const timer = this.#state.get(message);
+    if (timer?.id) this.#timers.clear(timer.id);
+    this.#state.delete(message);
+    const index = this.#order.indexOf(message);
+    if (index !== -1) this.#order.splice(index, 1);
+    message.setAttribute("data-flash-state", "leaving");
+    const finalize = () => {
+      this.#unbindPause(message);
+      message.remove();
+      this.dispatch("dismiss", { detail: { element: message, reason } });
+    };
+    const transition = this.#transitionMs(message);
+    if (transition > 0) {
+      this.#timers.set(finalize, transition);
+    } else {
+      finalize();
+    }
+  }
+  /** First `transition-duration` of `el` in ms (0 when none / unsupported). */
+  #transitionMs(el) {
+    if (typeof window.getComputedStyle !== "function") return 0;
+    const first = window.getComputedStyle(el).transitionDuration.split(",")[0]?.trim() ?? "";
+    const amount = Number.parseFloat(first);
+    if (Number.isNaN(amount)) return 0;
+    return first.endsWith("ms") ? amount : amount * 1e3;
+  }
+};
+
+export { FlashController };
+//# sourceMappingURL=flash_controller.js.map
+//# sourceMappingURL=flash_controller.js.map

data/dist/controllers/focus_controller.js

@@ -0,0 +1,216 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/focus_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/focus_controller.ts
+var FocusController = class extends Controller {
+  static targets = ["initial"];
+  static values = {
+    trap: { type: Boolean, default: false },
+    auto: { type: Boolean, default: true },
+    restore: { type: Boolean, default: true },
+    inert: { type: Boolean, default: false }
+  };
+  static actions = ["activate", "deactivate"];
+  static events = ["activate", "deactivate"];
+  #trap = new FocusTrap(() => this.element, {
+    // A focus scope is not a modal: never lock scroll, and only isolate the background
+    // when `inert` is requested. `auto` gates the initial focus move; Escape releases.
+    lockScroll: false,
+    isolate: () => this.inertValue,
+    autoFocus: () => this.autoValue,
+    initialFocus: () => this.hasInitialTarget ? this.initialTarget : null,
+    onEscape: () => this.deactivate()
+  });
+  /** Stimulus drives activation from the `trap` value (also fires on connect). */
+  trapValueChanged() {
+    if (this.trapValue) this.#activate();
+    else this.#deactivate();
+  }
+  disconnect() {
+    this.#trap.deactivate({ restoreFocus: false });
+    this.element.removeAttribute("data-focus-trapped");
+  }
+  /** Turns the trap on. Acts synchronously and keeps the `trap` value in sync. */
+  activate() {
+    this.trapValue = true;
+    this.#activate();
+  }
+  /** Turns the trap off (also wired to Escape). */
+  deactivate() {
+    this.trapValue = false;
+    this.#deactivate();
+  }
+  #activate() {
+    if (this.#trap.active) return;
+    this.#trap.activate();
+    this.element.setAttribute("data-focus-trapped", "true");
+    this.dispatch("activate", { detail: {} });
+  }
+  #deactivate() {
+    if (!this.#trap.active) return;
+    this.#trap.deactivate({ restoreFocus: this.restoreValue });
+    this.element.removeAttribute("data-focus-trapped");
+    this.dispatch("deactivate", { detail: {} });
+  }
+};
+
+export { FocusController };
+//# sourceMappingURL=focus_controller.js.map
+//# sourceMappingURL=focus_controller.js.map

data/dist/controllers/form_field_controller.js

@@ -0,0 +1,154 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/form_field_controller.ts
+
+// src/utils/aria_ids.ts
+var counter = 0;
+function uniqueId(prefix = "stimeo") {
+  let candidate;
+  do {
+    counter += 1;
+    candidate = `${prefix}-${counter}`;
+  } while (typeof document !== "undefined" && document.getElementById(candidate) !== null);
+  return candidate;
+}
+function ensureId(element, prefix = "stimeo") {
+  if (element.id) return element.id;
+  const id = uniqueId(prefix);
+  element.id = id;
+  return id;
+}
+
+// src/controllers/form_field_controller.ts
+var FormFieldController = class _FormFieldController extends Controller {
+  static targets = ["control", "description", "error"];
+  static values = {
+    focusOnError: { type: Boolean, default: false }
+  };
+  static actions = ["clearError", "setError"];
+  static events = ["validate"];
+  /** Root attribute (CSS hook) reflecting the invalid state. */
+  static #INVALID_ATTR = "data-stimeo--form-field-invalid";
+  /**
+   * `aria-describedby` tokens the consumer set on the control that the
+   * controller does not own. Captured once so composition never clobbers them.
+   */
+  #baseDescribedBy = [];
+  /** Wires ids, captures consumer tokens, and reflects any initial error state. */
+  connect() {
+    for (const description of this.descriptionTargets) {
+      ensureId(description, "stimeo--form-field-desc");
+    }
+    for (const error of this.errorTargets) {
+      ensureId(error, "stimeo--form-field-error");
+    }
+    this.#baseDescribedBy = this.#externalDescribedByTokens();
+    this.#reflect();
+  }
+  /**
+   * Marks the field invalid and shows the error message. Bound via `data-action`
+   * (`#setError`) or callable directly.
+   *
+   * @param arg - Either the message string, or the action event whose
+   *   `data-stimeo--form-field-message-param` supplies it. When no message is
+   *   resolvable, any already-populated error targets are simply (re)shown.
+   */
+  setError(arg) {
+    const message = this.#resolveMessage(arg);
+    if (message !== null && this.hasErrorTarget) {
+      this.errorTargets[0]?.replaceChildren(document.createTextNode(message));
+    }
+    for (const error of this.errorTargets) {
+      error.hidden = (error.textContent ?? "").trim() === "";
+    }
+    this.#reflect(true);
+    this.dispatch("validate", { detail: { valid: false, message: this.#shownMessage() } });
+    if (this.focusOnErrorValue && this.hasControlTarget) {
+      this.controlTarget.focus();
+    }
+  }
+  /**
+   * Clears the error: empties and hides every error target and marks the field
+   * valid. Bound via `data-action` (`#clearError`) or callable directly.
+   */
+  clearError() {
+    for (const error of this.errorTargets) {
+      error.replaceChildren();
+      error.hidden = true;
+    }
+    this.#reflect();
+    this.dispatch("validate", { detail: { valid: true, message: "" } });
+  }
+  /**
+   * Synchronizes the control's ARIA wiring and the root CSS hook from the current
+   * error targets. Idempotent, so it is safe to call on connect and after any
+   * change (and survives Turbo morphing).
+   *
+   * @param force - When `true`, the field is marked invalid regardless of whether
+   *   a (visible, non-empty) error region exists. {@link setError} passes this so
+   *   the invalid state holds even with no error target; derivation from the DOM
+   *   (connect / {@link clearError}) leaves it `false`.
+   */
+  #reflect(force = false) {
+    const shown = this.#shownErrors();
+    const invalid = force || shown.length > 0;
+    if (invalid) {
+      this.element.setAttribute(_FormFieldController.#INVALID_ATTR, "");
+    } else {
+      this.element.removeAttribute(_FormFieldController.#INVALID_ATTR);
+    }
+    if (!this.hasControlTarget) return;
+    const control = this.controlTarget;
+    control.setAttribute("aria-invalid", invalid ? "true" : "false");
+    const errorIds = shown.map((error) => error.id);
+    const primaryErrorId = errorIds[0];
+    if (primaryErrorId) {
+      control.setAttribute("aria-errormessage", primaryErrorId);
+    } else {
+      control.removeAttribute("aria-errormessage");
+    }
+    const describedBy = [
+      ...this.#baseDescribedBy,
+      ...this.descriptionTargets.map((description) => description.id),
+      ...errorIds
+    ];
+    if (describedBy.length > 0) {
+      control.setAttribute("aria-describedby", describedBy.join(" "));
+    } else {
+      control.removeAttribute("aria-describedby");
+    }
+  }
+  /** Error targets currently visible and non-empty. */
+  #shownErrors() {
+    return this.errorTargets.filter(
+      (error) => !error.hidden && (error.textContent ?? "").trim() !== ""
+    );
+  }
+  /** Text of the first shown error, for the `validate` event detail. */
+  #shownMessage() {
+    return (this.#shownErrors()[0]?.textContent ?? "").trim();
+  }
+  /** Resolves a message from a string argument or an action event's params. */
+  #resolveMessage(arg) {
+    if (typeof arg === "string") return arg;
+    const message = arg?.params?.message;
+    return typeof message === "string" ? message : null;
+  }
+  /**
+   * Tokens already in the control's `aria-describedby` that are not ids of this
+   * controller's own description/error targets.
+   */
+  #externalDescribedByTokens() {
+    if (!this.hasControlTarget) return [];
+    const owned = /* @__PURE__ */ new Set([
+      ...this.descriptionTargets.map((description) => description.id),
+      ...this.errorTargets.map((error) => error.id)
+    ]);
+    const existing = this.controlTarget.getAttribute("aria-describedby") ?? "";
+    return existing.split(/\s+/).filter((token) => token.length > 0 && !owned.has(token));
+  }
+};
+
+export { FormFieldController };
+//# sourceMappingURL=form_field_controller.js.map
+//# sourceMappingURL=form_field_controller.js.map