stimeo-ui 0.1.0.pre.alpha.1

data/dist/controllers/form_validation_controller.js

@@ -0,0 +1,202 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/form_validation_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"])';
+
+// src/controllers/form_validation_controller.ts
+var FormValidationController = class _FormValidationController extends Controller {
+  static outlets = ["stimeo--form-field"];
+  static values = {
+    validateOnBlur: { type: Boolean, default: true },
+    validateOnChange: { type: Boolean, default: true },
+    revalidateOnInput: { type: Boolean, default: true },
+    focusInvalid: { type: Boolean, default: true }
+  };
+  static actions = ["validate"];
+  static events = ["valid", "invalid"];
+  /** Marker recording that we added `novalidate`, so we only remove our own. */
+  static #NOVALIDATE_MARKER = "data-stimeo--form-validation-novalidate";
+  /** Controls already interacted with — the gate for blur / input (re)validation. */
+  #touched = /* @__PURE__ */ new WeakSet();
+  #onSubmit = (event) => {
+    if (event.target !== this.element) return;
+    const invalid = this.#validateAll();
+    if (invalid.length === 0) {
+      this.dispatch("valid", { detail: {} });
+      return;
+    }
+    event.preventDefault();
+    event.stopImmediatePropagation();
+    const first = invalid[0];
+    if (this.focusInvalidValue && first) this.#focusTargetFor(first)?.focus();
+    this.dispatch("invalid", { detail: { invalid } });
+  };
+  #onFocusOut = (event) => {
+    if (!this.validateOnBlurValue) return;
+    const control = this.#controlFrom(event.target);
+    if (!control) return;
+    const field = this.#fieldFor(control);
+    const related = event.relatedTarget;
+    if (field && related instanceof Node && field.element.contains(related)) return;
+    this.#touched.add(control);
+    this.#validateControl(control);
+  };
+  #onInput = (event) => {
+    if (!this.revalidateOnInputValue) return;
+    const control = this.#controlFrom(event.target);
+    if (!control || !this.#touched.has(control)) return;
+    this.#validateControl(control);
+  };
+  #onChange = (event) => {
+    if (!this.validateOnChangeValue) return;
+    const control = this.#controlFrom(event.target);
+    if (!control) return;
+    this.#touched.add(control);
+    this.#validateControl(control);
+  };
+  /** Suppresses native bubbles and binds the submit / blur / input listeners. */
+  connect() {
+    if (!this.element.hasAttribute("novalidate")) {
+      this.element.setAttribute("novalidate", "");
+      this.element.setAttribute(_FormValidationController.#NOVALIDATE_MARKER, "");
+    }
+    document.addEventListener("submit", this.#onSubmit, true);
+    this.element.addEventListener("focusout", this.#onFocusOut);
+    this.element.addEventListener("input", this.#onInput);
+    this.element.addEventListener("change", this.#onChange);
+  }
+  /** Tears down listeners and restores `novalidate` if we added it. */
+  disconnect() {
+    document.removeEventListener("submit", this.#onSubmit, true);
+    this.element.removeEventListener("focusout", this.#onFocusOut);
+    this.element.removeEventListener("input", this.#onInput);
+    this.element.removeEventListener("change", this.#onChange);
+    if (this.element.hasAttribute(_FormValidationController.#NOVALIDATE_MARKER)) {
+      this.element.removeAttribute("novalidate");
+      this.element.removeAttribute(_FormValidationController.#NOVALIDATE_MARKER);
+    }
+  }
+  /**
+   * Validates every control now, rendering or clearing each field's message, and
+   * returns whether the whole form is valid. Marks every control touched so a
+   * later input re-validates it. Bound via `data-action`
+   * (`#validate`) or callable directly (e.g. before a programmatic submit).
+   */
+  validate() {
+    return this.#validateAll().length === 0;
+  }
+  /**
+   * Validates every control and returns one invalid control per field. Controls
+   * are grouped by field first (see {@link #keyFor}) so a field with several
+   * controls — a radio group, or a mirror plus its visible control — reflects
+   * *all* of them: a valid sibling must never clear an invalid one's message.
+   * Each group's first invalid control supplies the message and the focus target.
+   */
+  #validateAll() {
+    const groups = /* @__PURE__ */ new Map();
+    for (const control of this.#controls) {
+      this.#touched.add(control);
+      const field = this.#fieldFor(control);
+      const key = this.#keyFor(control, field);
+      const group = groups.get(key);
+      if (group) {
+        group.controls.push(control);
+      } else {
+        groups.set(key, { field, controls: [control] });
+      }
+    }
+    const invalid = [];
+    for (const group of groups.values()) {
+      const firstInvalid = this.#applyGroup(group);
+      if (firstInvalid) invalid.push(firstInvalid);
+    }
+    return invalid;
+  }
+  /** Re-validates the whole field a single control belongs to (or that control). */
+  #validateControl(control) {
+    const field = this.#fieldFor(control);
+    const key = this.#keyFor(control, field);
+    const controls = this.#controls.filter(
+      (other) => this.#keyFor(other, this.#fieldFor(other)) === key
+    );
+    this.#applyGroup({ field, controls });
+  }
+  /**
+   * Runs native constraint validation across a field's controls and routes the
+   * result to its `stimeo--form-field` outlet: the first invalid control's
+   * `validationMessage` is shown, an all-valid field is cleared. Returns the
+   * first invalid control (for the invalid list / focus), or `null` when valid.
+   * Routing goes through the outlet, so the ARIA wiring is never duplicated here.
+   */
+  #applyGroup(group) {
+    const firstInvalid = group.controls.find((control) => !control.checkValidity()) ?? null;
+    if (group.field) {
+      if (firstInvalid) {
+        group.field.setError(firstInvalid.validationMessage);
+      } else {
+        group.field.clearError();
+      }
+    }
+    return firstInvalid;
+  }
+  /**
+   * A grouping key that collects controls belonging to the same field: the owning
+   * `stimeo--form-field` when present, else a radio group's shared `name`, else
+   * the control itself (always distinct).
+   */
+  #keyFor(control, field) {
+    if (field) return field;
+    if (control instanceof HTMLInputElement && control.type === "radio" && control.name) {
+      return `radio:${control.name}`;
+    }
+    return control;
+  }
+  /**
+   * Where focus should land for an invalid control. A visible control is focused
+   * directly (status quo for native fields and radios). A validatable mirror
+   * (the `hidden` attribute) cannot receive focus, so focus is delegated to the
+   * visible widget: the owning field's `control` target when it is itself
+   * focusable, else its first focusable descendant (e.g. a roving-tabindex
+   * member). Resolved structurally — never by probing `focus()` — so behavior
+   * is deterministic and CSS-independent.
+   */
+  #focusTargetFor(control) {
+    if (!control.hidden) return control;
+    const field = this.#fieldFor(control);
+    if (!field?.hasControlTarget) return null;
+    const root = field.controlTarget;
+    if (root.matches(FOCUSABLE)) return root;
+    return root.querySelector(FOCUSABLE);
+  }
+  /** The `stimeo--form-field` outlet whose element contains `control`, if any. */
+  #fieldFor(control) {
+    const elements = this.stimeoFormFieldOutletElements;
+    for (let index = 0; index < elements.length; index++) {
+      if (elements[index]?.contains(control)) return this.stimeoFormFieldOutlets[index];
+    }
+    return void 0;
+  }
+  /** This form's native controls that participate in constraint validation. */
+  get #controls() {
+    const controls = [];
+    for (const element of Array.from(this.element.elements)) {
+      if (this.#isValidatable(element)) controls.push(element);
+    }
+    return controls;
+  }
+  /** Narrows an event target to a validatable control. */
+  #controlFrom(target) {
+    return target instanceof Element && this.#isValidatable(target) ? target : null;
+  }
+  #isValidatable(element) {
+    return (element instanceof HTMLInputElement || element instanceof HTMLSelectElement || element instanceof HTMLTextAreaElement) && // `willValidate` already excludes disabled, read-only, hidden, and button
+    // controls — the exact set barred from constraint validation.
+    element.willValidate;
+  }
+};
+
+export { FormValidationController };
+//# sourceMappingURL=form_validation_controller.js.map
+//# sourceMappingURL=form_validation_controller.js.map

data/dist/controllers/frame_loading_controller.js

@@ -0,0 +1,177 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/frame_loading_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/frame_loading_controller.ts
+var FrameLoadingController = class extends Controller {
+  static targets = ["content", "skeleton", "overlay"];
+  static values = {
+    minDuration: { type: Number, default: 0 },
+    restoreFocus: { type: Boolean, default: true }
+  };
+  static events = ["start", "end"];
+  #timeouts = new SafeTimeout();
+  #loading = false;
+  #startedAt = 0;
+  #inertApplied = false;
+  #previousFocus = null;
+  /** The id of the retreated element, used to re-find it if the load replaced it. */
+  #previousFocusId = "";
+  #onStart = () => {
+    this.#timeouts.clearAll();
+    if (!this.#loading) this.#begin();
+  };
+  #onEnd = () => {
+    if (!this.#loading) return;
+    const remaining = this.minDurationValue - (Date.now() - this.#startedAt);
+    if (remaining > 0) {
+      this.#timeouts.clearAll();
+      this.#timeouts.set(() => this.#finish(), remaining);
+    } else {
+      this.#finish();
+    }
+  };
+  connect() {
+    this.element.addEventListener("turbo:before-fetch-request", this.#onStart);
+    this.element.addEventListener("turbo:frame-load", this.#onEnd);
+    this.element.addEventListener("turbo:fetch-request-error", this.#onEnd);
+  }
+  disconnect() {
+    this.element.removeEventListener("turbo:before-fetch-request", this.#onStart);
+    this.element.removeEventListener("turbo:frame-load", this.#onEnd);
+    this.element.removeEventListener("turbo:fetch-request-error", this.#onEnd);
+    this.#timeouts.clearAll();
+    if (this.#loading) {
+      this.element.removeAttribute("aria-busy");
+      this.element.removeAttribute("data-frame-loading");
+      this.#clearInert();
+    }
+    this.#loading = false;
+    this.#previousFocus = null;
+  }
+  /** Enters the loading state: hooks, skeleton/overlay, inert content, focus retreat. */
+  #begin() {
+    this.#loading = true;
+    this.#startedAt = Date.now();
+    this.element.setAttribute("aria-busy", "true");
+    this.element.setAttribute("data-frame-loading", "true");
+    if (this.hasSkeletonTarget) this.skeletonTarget.hidden = false;
+    if (this.hasOverlayTarget) this.overlayTarget.hidden = false;
+    this.#applyInert();
+    this.#retreatFocus();
+    this.dispatch("start", { detail: {} });
+  }
+  /** Leaves the loading state: restore hooks, hide skeleton/overlay, restore focus. */
+  #finish() {
+    this.#loading = false;
+    this.element.removeAttribute("aria-busy");
+    this.element.removeAttribute("data-frame-loading");
+    if (this.hasSkeletonTarget) this.skeletonTarget.hidden = true;
+    if (this.hasOverlayTarget) this.overlayTarget.hidden = true;
+    this.#clearInert();
+    this.#restoreFocus();
+    this.dispatch("end", { detail: {} });
+  }
+  /** Marks the content inert to block double-submits while stale (if we own it). */
+  #applyInert() {
+    if (!this.hasContentTarget || this.contentTarget.hasAttribute("inert")) return;
+    this.contentTarget.setAttribute("inert", "");
+    this.#inertApplied = true;
+  }
+  #clearInert() {
+    if (!this.#inertApplied) return;
+    this.#inertApplied = false;
+    if (this.hasContentTarget) this.contentTarget.removeAttribute("inert");
+  }
+  /** Saves and blurs focus if it sits inside the frame about to go stale. */
+  #retreatFocus() {
+    this.#previousFocus = null;
+    this.#previousFocusId = "";
+    if (!this.restoreFocusValue) return;
+    const active = document.activeElement;
+    if (active instanceof HTMLElement && active !== this.element && this.element.contains(active)) {
+      this.#previousFocus = active;
+      this.#previousFocusId = active.id;
+      active.blur();
+    }
+  }
+  /**
+   * Restores focus after the load. The same node when it survived (e.g. a
+   * non-replacing update), else the element re-rendered with the same id inside the
+   * frame — Turbo frames typically re-emit the same controls. When neither is present
+   * (an anonymous control was replaced) focus is left where the browser put it, to
+   * avoid an unexpected jump (WCAG 3.2.x).
+   */
+  #restoreFocus() {
+    const target = this.#previousFocus;
+    const id = this.#previousFocusId;
+    this.#previousFocus = null;
+    this.#previousFocusId = "";
+    if (!this.restoreFocusValue) return;
+    if (target?.isConnected) {
+      target.focus();
+      return;
+    }
+    if (id) {
+      const replacement = document.getElementById(id);
+      if (replacement && this.element.contains(replacement)) replacement.focus();
+    }
+  }
+};
+
+export { FrameLoadingController };
+//# sourceMappingURL=frame_loading_controller.js.map
+//# sourceMappingURL=frame_loading_controller.js.map

data/dist/controllers/highlight_controller.js

@@ -0,0 +1,107 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/highlight_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/highlight_controller.ts
+var HighlightController = class extends Controller {
+  static values = {
+    duration: { type: Number, default: 1500 },
+    observe: { type: Boolean, default: false }
+  };
+  static events = ["start", "end"];
+  #timeouts = new SafeTimeout();
+  #observer = null;
+  connect() {
+    if (this.observeValue) {
+      if (typeof MutationObserver !== "undefined") {
+        this.#observer = new MutationObserver((mutations) => this.#onMutations(mutations));
+        this.#observer.observe(this.element, { childList: true });
+      }
+      return;
+    }
+    this.#highlight(this.element);
+  }
+  disconnect() {
+    this.#observer?.disconnect();
+    this.#observer = null;
+    this.#timeouts.clearAll();
+  }
+  /** Highlights every element child added by a childList mutation. */
+  #onMutations(mutations) {
+    for (const mutation of mutations) {
+      for (const node of mutation.addedNodes) {
+        if (node instanceof HTMLElement) this.#highlight(node);
+      }
+    }
+  }
+  /** Flags `el` with `data-highlight` and schedules its removal (unless reduced-motion). */
+  #highlight(el) {
+    if (this.#prefersReducedMotion()) return;
+    el.setAttribute("data-highlight", "true");
+    this.dispatch("start", { target: el, detail: { element: el } });
+    this.#timeouts.set(() => {
+      el.removeAttribute("data-highlight");
+      this.dispatch("end", { target: el, detail: { element: el } });
+    }, this.durationValue);
+  }
+  #prefersReducedMotion() {
+    return typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  }
+};
+
+export { HighlightController };
+//# sourceMappingURL=highlight_controller.js.map
+//# sourceMappingURL=highlight_controller.js.map

data/dist/controllers/hover_card_controller.js

@@ -0,0 +1,165 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/hover_card_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/hover_card_controller.ts
+var HoverCardController = class extends Controller {
+  static targets = ["trigger", "card"];
+  static values = {
+    openDelay: { type: Number, default: 300 },
+    closeDelay: { type: Number, default: 200 }
+  };
+  static actions = ["close", "onKeydown", "open"];
+  /** Pending open/close timers, torn down together on disconnect. */
+  #timers = new SafeTimeout();
+  #pendingOpen = null;
+  #pendingClose = null;
+  /** Starts closed. */
+  connect() {
+    this.#conceal();
+  }
+  /** Clears timers and the document `Escape` listener so nothing outlives the element. */
+  disconnect() {
+    this.#timers.clearAll();
+    document.removeEventListener("keydown", this.#onDocumentKeydown);
+  }
+  /** Opens the card, after `openDelay` ms (or immediately at 0). Cancels a pending close. */
+  open() {
+    this.#cancelClose();
+    if (this.#isOpen || this.#pendingOpen !== null) return;
+    if (this.openDelayValue <= 0) {
+      this.#reveal();
+      return;
+    }
+    this.#pendingOpen = this.#timers.set(() => {
+      this.#pendingOpen = null;
+      this.#reveal();
+    }, this.openDelayValue);
+  }
+  /**
+   * Schedules the card to close after `closeDelay`. Cancels a pending open. The
+   * delayed callback re-checks whether focus has landed inside the controller
+   * (e.g. a link in the card) and, if so, aborts the close — covering keyboard
+   * traversal that the pointer-only hoverable bridge cannot.
+   */
+  close() {
+    this.#cancelOpen();
+    if (!this.#isOpen || this.#pendingClose !== null) return;
+    this.#pendingClose = this.#timers.set(() => {
+      this.#pendingClose = null;
+      if (this.element.contains(document.activeElement)) return;
+      this.#conceal();
+    }, this.closeDelayValue);
+  }
+  /** Closes immediately on `Escape` while open (keyboard dismissal from the trigger). */
+  onKeydown(event) {
+    if (event.key === "Escape" && this.#isOpen) {
+      event.preventDefault();
+      this.#dismiss();
+    }
+  }
+  /** Reveals the card, reflects state, and starts watching for a dismissing `Escape`. */
+  #reveal() {
+    if (!this.hasCardTarget) return;
+    this.cardTarget.hidden = false;
+    this.cardTarget.setAttribute("data-state", "open");
+    if (this.hasTriggerTarget) this.triggerTarget.setAttribute("aria-expanded", "true");
+    document.addEventListener("keydown", this.#onDocumentKeydown);
+  }
+  /** Hides the card, reflects state, and stops watching for `Escape`. */
+  #conceal() {
+    if (!this.hasCardTarget) return;
+    this.cardTarget.hidden = true;
+    this.cardTarget.setAttribute("data-state", "closed");
+    if (this.hasTriggerTarget) this.triggerTarget.setAttribute("aria-expanded", "false");
+    document.removeEventListener("keydown", this.#onDocumentKeydown);
+  }
+  /** Cancels pending timers and conceals immediately (shared Escape path). */
+  #dismiss() {
+    this.#cancelOpen();
+    this.#cancelClose();
+    this.#conceal();
+  }
+  /** Document-level `Escape` watcher (active only while open). */
+  #onDocumentKeydown = (event) => {
+    if (event.key === "Escape") {
+      event.preventDefault();
+      this.#dismiss();
+    }
+  };
+  /** Cancels any pending open timer. */
+  #cancelOpen() {
+    if (this.#pendingOpen !== null) {
+      this.#timers.clear(this.#pendingOpen);
+      this.#pendingOpen = null;
+    }
+  }
+  /** Cancels any pending close timer. */
+  #cancelClose() {
+    if (this.#pendingClose !== null) {
+      this.#timers.clear(this.#pendingClose);
+      this.#pendingClose = null;
+    }
+  }
+  /** Whether the card is currently visible. */
+  get #isOpen() {
+    return this.hasCardTarget && !this.cardTarget.hidden;
+  }
+};
+
+export { HoverCardController };
+//# sourceMappingURL=hover_card_controller.js.map
+//# sourceMappingURL=hover_card_controller.js.map