stimeo-ui 0.1.0.pre.alpha.1

data/dist/controllers/toast_controller.js

@@ -0,0 +1,310 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/toast_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/toast_controller.ts
+var ToastController = class extends Controller {
+  static targets = ["list", "template", "item"];
+  static values = {
+    duration: { type: Number, default: 0 },
+    max: { type: Number, default: 3 }
+  };
+  static actions = ["dismiss", "onKeydown", "pause", "resume", "show"];
+  static events = ["dismiss", "show"];
+  /**
+   * Registry for every auto-dismiss and transition-finalize timer the controller
+   * schedules. {@link SafeTimeout} owns *registration and teardown only*; the
+   * pause/resume remaining-time accounting stays in `#activeTimeouts` so the
+   * per-widget WCAG 2.2.1 semantics are not flattened into the helper.
+   */
+  #timers = new SafeTimeout();
+  /**
+   * Pending one-shot `requestAnimationFrame` handles (the entering→visible flip).
+   * Tracked so {@link disconnect} can cancel any that have not fired, preventing a
+   * detached element from being mutated after it leaves the DOM (Turbo).
+   */
+  #rafHandles = /* @__PURE__ */ new Set();
+  /** Track active timeouts mapped by each toast element for safe cancellation. */
+  #activeTimeouts = /* @__PURE__ */ new Map();
+  /** Track active pause reasons (hover/focus) per toast for WCAG 2.2.1 pause/resume. */
+  #pauseReasons = /* @__PURE__ */ new Map();
+  connect() {
+    this.enforceMaxLimit();
+    for (const item of this.itemTargets) {
+      if (!this.#activeTimeouts.has(item)) {
+        this.#startTimer(item);
+      }
+    }
+  }
+  disconnect() {
+    this.#timers.clearAll();
+    for (const handle of this.#rafHandles) {
+      window.cancelAnimationFrame(handle);
+    }
+    this.#rafHandles.clear();
+    this.#activeTimeouts.clear();
+    this.#pauseReasons.clear();
+  }
+  durationValueChanged() {
+    if (this.durationValue > 0) {
+      for (const item of this.itemTargets) {
+        if (!this.#activeTimeouts.has(item)) {
+          this.#startTimer(item);
+        }
+      }
+    }
+  }
+  maxValueChanged() {
+    this.enforceMaxLimit();
+  }
+  /**
+   * Stimulus lifecycle callback triggered automatically when a new item target
+   * enters the DOM. Perfectly handles dynamic client-side injections and server-side
+   * Turbo Stream appends alike.
+   */
+  itemTargetConnected(element) {
+    this.enforceMaxLimit();
+    this.#startTimer(element);
+    element.setAttribute("data-state", "entering");
+    const handle = window.requestAnimationFrame(() => {
+      this.#rafHandles.delete(handle);
+      element.setAttribute("data-state", "visible");
+    });
+    this.#rafHandles.add(handle);
+  }
+  /** Clears any active timer when a toast is removed from the DOM. */
+  itemTargetDisconnected(element) {
+    this.#clearTimer(element);
+  }
+  /**
+   * Shows a new toast. Accepts its content from either a Stimulus action param
+   * (attribute-only trigger) or a programmatic `show` CustomEvent `detail`
+   * (remote / Turbo trigger); the action param wins when both are present.
+   *
+   *   <button data-action="click->stimeo--toast#show"
+   *           data-stimeo--toast-body-param="Saved"
+   *           data-stimeo--toast-type-param="status">Show</button>
+   *
+   *   element.dispatchEvent(new CustomEvent("show", { detail: { body, type } }))
+   *
+   * Clones the template slot, interpolates the body text, and appends to the list.
+   */
+  show(event) {
+    if (!this.hasTemplateTarget || !this.hasListTarget) return;
+    const body = this.#readField(event, "body");
+    if (!body) return;
+    const clone = this.templateTarget.content.cloneNode(true);
+    const item = clone.querySelector("[data-stimeo--toast-target='item']");
+    if (!item) return;
+    const bodySlot = item.querySelector("[data-toast-slot='body']");
+    if (bodySlot) {
+      bodySlot.textContent = body;
+    }
+    item.setAttribute("role", this.#readField(event, "type") === "alert" ? "alert" : "status");
+    this.listTarget.appendChild(item);
+    this.dispatch("show", { detail: { item } });
+  }
+  /**
+   * Reads a string field from a Stimulus action param or a CustomEvent `detail`,
+   * preferring the action param. Returns null unless a non-empty string is found,
+   * so untrusted runtime payloads cannot inject non-string values.
+   */
+  #readField(event, key) {
+    const params = event.params;
+    const fromParams = params?.[key];
+    if (typeof fromParams === "string" && fromParams.length > 0) return fromParams;
+    const detail = event.detail;
+    if (detail && typeof detail === "object" && key in detail) {
+      const value = detail[key];
+      if (typeof value === "string" && value.length > 0) return value;
+    }
+    return null;
+  }
+  /** Dismisses the toast that contained the trigger. */
+  dismiss(event) {
+    const target = event.currentTarget || event.target;
+    if (!target) return;
+    const item = target.closest("[data-stimeo--toast-target='item']");
+    if (!item) return;
+    this.#removeWithTransition(item, "user");
+  }
+  /** Dismisses the focused toast when Escape is pressed. */
+  onKeydown(event) {
+    if (event.key === "Escape") {
+      const target = event.currentTarget || event.target;
+      if (!target) return;
+      const item = target.closest("[data-stimeo--toast-target='item']");
+      if (!item) return;
+      event.preventDefault();
+      this.#removeWithTransition(item, "user");
+    }
+  }
+  /**
+   * Pauses the auto-dismiss timer on mouse entry or keyboard focus.
+   *
+   * Hover and focus are tracked as independent reasons: the timer is only
+   * snapshotted on the first active reason, and only resumed once *every*
+   * reason has been released (see {@link resume}). This keeps a toast paused
+   * while it is still hovered *or* focused, per WCAG 2.2.1.
+   */
+  pause(event) {
+    const item = this.#itemFromEvent(event);
+    if (!item || this.durationValue <= 0) return;
+    const timeout = this.#activeTimeouts.get(item);
+    if (!timeout) return;
+    const reasons = this.#pauseReasonsFor(item);
+    const wasActive = reasons.size > 0;
+    reasons.add(this.#pauseReason(event));
+    if (wasActive || timeout.id === 0) return;
+    this.#timers.clear(timeout.id);
+    const elapsed = Date.now() - timeout.startedAt;
+    const remaining = Math.max(0, timeout.remaining - elapsed);
+    this.#activeTimeouts.set(item, { id: 0, startedAt: 0, remaining });
+    item.setAttribute("data-paused", "true");
+  }
+  /** Resumes the auto-dismiss timer once both hover and focus have been released. */
+  resume(event) {
+    const item = this.#itemFromEvent(event);
+    if (!item || this.durationValue <= 0) return;
+    const reasons = this.#pauseReasonsFor(item);
+    reasons.delete(this.#pauseReason(event));
+    if (reasons.size > 0) return;
+    const timeout = this.#activeTimeouts.get(item);
+    if (!timeout || timeout.remaining <= 0) return;
+    item.removeAttribute("data-paused");
+    this.#startTimer(item, timeout.remaining);
+  }
+  /** Resolves the toast item element a pause/resume event targets. */
+  #itemFromEvent(event) {
+    const target = event.currentTarget || event.target;
+    return target?.closest("[data-stimeo--toast-target='item']") ?? null;
+  }
+  /** Classifies a pause/resume event as a hover or focus reason. */
+  #pauseReason(event) {
+    return event.type === "focusin" || event.type === "focusout" ? "focus" : "hover";
+  }
+  /** Lazily creates and returns the active pause-reason set for an item. */
+  #pauseReasonsFor(item) {
+    let reasons = this.#pauseReasons.get(item);
+    if (!reasons) {
+      reasons = /* @__PURE__ */ new Set();
+      this.#pauseReasons.set(item, reasons);
+    }
+    return reasons;
+  }
+  #startTimer(element, duration = this.durationValue) {
+    if (duration <= 0) return;
+    this.#clearTimer(element);
+    const id = this.#timers.set(() => {
+      this.#removeWithTransition(element, "timeout");
+    }, duration);
+    this.#activeTimeouts.set(element, { id, startedAt: Date.now(), remaining: duration });
+  }
+  #clearTimer(element) {
+    const timeout = this.#activeTimeouts.get(element);
+    if (timeout) {
+      if (timeout.id) this.#timers.clear(timeout.id);
+      this.#activeTimeouts.delete(element);
+    }
+    this.#pauseReasons.delete(element);
+  }
+  #removeWithTransition(element, reason) {
+    this.#clearTimer(element);
+    element.setAttribute("data-state", "leaving");
+    const finalize = () => {
+      if (element.parentNode === this.listTarget) {
+        this.listTarget.removeChild(element);
+      }
+      this.dispatch("dismiss", { detail: { item: element, reason } });
+    };
+    const transitions = window.getComputedStyle(element).transitionDuration;
+    const duration = cssTimeToMs(transitions);
+    if (duration > 0) {
+      this.#timers.set(finalize, duration);
+    } else {
+      finalize();
+    }
+  }
+  /**
+   * Removes the oldest toasts when the list exceeds `maxValue`.
+   *
+   * Public (not `#private`) as a deterministic test seam: enforcement normally
+   * runs from `itemTargetConnected`, a Stimulus callback that fires via a
+   * MutationObserver — which happy-dom does not reliably deliver — so the unit
+   * tests invoke it directly. It is therefore listed in the contract guard's
+   * NON_ACTION_ALLOWLIST (it is not a user-wired action).
+   */
+  enforceMaxLimit() {
+    const currentItems = this.itemTargets;
+    if (currentItems.length > this.maxValue) {
+      const excessCount = currentItems.length - this.maxValue;
+      for (let i = 0; i < excessCount; i++) {
+        const oldest = currentItems[i];
+        if (oldest) this.#removeWithTransition(oldest, "timeout");
+      }
+    }
+  }
+};
+function cssTimeToMs(value) {
+  const first = value.split(",")[0]?.trim() ?? "";
+  const amount = Number.parseFloat(first);
+  if (Number.isNaN(amount)) return 0;
+  return first.endsWith("ms") ? amount : amount * 1e3;
+}
+
+export { ToastController, cssTimeToMs };
+//# sourceMappingURL=toast_controller.js.map
+//# sourceMappingURL=toast_controller.js.map

data/dist/controllers/toggle_group_controller.js

@@ -0,0 +1,130 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/toggle_group_controller.ts
+
+// src/utils/roving_tabindex.ts
+var RovingTabindex = class {
+  /** Returns the current ordered item elements; called on every operation. */
+  #getItems;
+  /**
+   * @param getItems - Returns the current ordered item elements. Called on every
+   *   operation so the live target list is always used.
+   */
+  constructor(getItems) {
+    this.#getItems = getItems;
+  }
+  /** Index of the currently tabbable item (`tabindex="0"`), or `-1` if none. */
+  get activeIndex() {
+    return this.#getItems().findIndex((item) => item.tabIndex === 0);
+  }
+  /**
+   * Makes exactly the item at `index` tabbable (`tabindex="0"`) and removes every
+   * other item from the Tab sequence (`tabindex="-1"`). An out-of-range `index`
+   * (e.g. `-1`) leaves all items at `-1`, which a controller can use to express
+   * "nothing is currently tabbable".
+   *
+   * @param index - Position of the item to make tabbable.
+   * @param options - Pass `{ focus: true }` to also move DOM focus to that item.
+   */
+  setActive(index, { focus = false } = {}) {
+    const items = this.#getItems();
+    items.forEach((item, i) => {
+      item.tabIndex = i === index ? 0 : -1;
+    });
+    if (focus) items[index]?.focus();
+  }
+};
+function rovingMove(current, length, delta, wrap) {
+  if (length === 0) return -1;
+  const next = current + delta;
+  return (next + length) % length;
+}
+
+// src/controllers/toggle_group_controller.ts
+var ToggleGroupController = class extends Controller {
+  static targets = ["item"];
+  static values = {
+    mode: { type: String, default: "multiple" }
+  };
+  static actions = ["onKeydown", "toggle"];
+  static events = ["change"];
+  #roving = new RovingTabindex(() => this.itemTargets);
+  /** Establishes the roving entry point (first pressed item, else the first). */
+  connect() {
+    const firstPressed = this.itemTargets.findIndex((item) => this.#isPressed(item));
+    this.#roving.setActive(firstPressed === -1 ? 0 : firstPressed);
+  }
+  /** Toggles the activated item. Bound via `data-action` (click). */
+  toggle(event) {
+    this.#toggleIndex(this.itemTargets.indexOf(event.currentTarget));
+  }
+  /** Arrow/Home/End move focus only; Space/Enter toggle non-button hosts. */
+  onKeydown(event) {
+    const current = this.itemTargets.indexOf(event.currentTarget);
+    if (current === -1) return;
+    let next = null;
+    switch (event.key) {
+      case "ArrowRight":
+      case "ArrowDown":
+        next = rovingMove(current, this.itemTargets.length, 1);
+        break;
+      case "ArrowLeft":
+      case "ArrowUp":
+        next = rovingMove(current, this.itemTargets.length, -1);
+        break;
+      case "Home":
+        next = 0;
+        break;
+      case "End":
+        next = this.itemTargets.length - 1;
+        break;
+      case " ":
+      case "Enter":
+        if (event.currentTarget instanceof HTMLButtonElement) return;
+        event.preventDefault();
+        this.#toggleIndex(current);
+        return;
+      default:
+        return;
+    }
+    event.preventDefault();
+    this.#roving.setActive(next, { focus: true });
+  }
+  /** Applies the toggle at `index` per the current mode and dispatches `change`. */
+  #toggleIndex(index) {
+    const item = this.itemTargets[index];
+    if (!item) return;
+    const willPress = !this.#isPressed(item);
+    if (this.modeValue === "single") {
+      this.itemTargets.forEach((other, i) => {
+        this.#setPressed(other, i === index && willPress);
+      });
+    } else {
+      this.#setPressed(item, willPress);
+    }
+    this.#roving.setActive(index);
+    this.dispatch("change", {
+      detail: { value: this.#itemValue(item), pressed: willPress, values: this.#pressedValues() }
+    });
+  }
+  /** Whether an item is currently pressed. */
+  #isPressed(item) {
+    return item.getAttribute("aria-pressed") === "true";
+  }
+  /** Reflects the pressed state on `aria-pressed`. */
+  #setPressed(item, pressed) {
+    item.setAttribute("aria-pressed", pressed ? "true" : "false");
+  }
+  /** The `data-value` of every currently pressed item. */
+  #pressedValues() {
+    return this.itemTargets.filter((item) => this.#isPressed(item)).map((item) => this.#itemValue(item));
+  }
+  /** An item's value (`data-value`, defaulting to empty). */
+  #itemValue(item) {
+    return item.getAttribute("data-value") ?? "";
+  }
+};
+
+export { ToggleGroupController };
+//# sourceMappingURL=toggle_group_controller.js.map
+//# sourceMappingURL=toggle_group_controller.js.map

data/dist/controllers/toolbar_controller.js

@@ -0,0 +1,113 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/toolbar_controller.ts
+
+// src/utils/roving_tabindex.ts
+var RovingTabindex = class {
+  /** Returns the current ordered item elements; called on every operation. */
+  #getItems;
+  /**
+   * @param getItems - Returns the current ordered item elements. Called on every
+   *   operation so the live target list is always used.
+   */
+  constructor(getItems) {
+    this.#getItems = getItems;
+  }
+  /** Index of the currently tabbable item (`tabindex="0"`), or `-1` if none. */
+  get activeIndex() {
+    return this.#getItems().findIndex((item) => item.tabIndex === 0);
+  }
+  /**
+   * Makes exactly the item at `index` tabbable (`tabindex="0"`) and removes every
+   * other item from the Tab sequence (`tabindex="-1"`). An out-of-range `index`
+   * (e.g. `-1`) leaves all items at `-1`, which a controller can use to express
+   * "nothing is currently tabbable".
+   *
+   * @param index - Position of the item to make tabbable.
+   * @param options - Pass `{ focus: true }` to also move DOM focus to that item.
+   */
+  setActive(index, { focus = false } = {}) {
+    const items = this.#getItems();
+    items.forEach((item, i) => {
+      item.tabIndex = i === index ? 0 : -1;
+    });
+    if (focus) items[index]?.focus();
+  }
+};
+function rovingMove(current, length, delta, wrap) {
+  if (length === 0) return -1;
+  const next = current + delta;
+  if (wrap === "wrap") return (next + length) % length;
+  return Math.min(length - 1, Math.max(0, next));
+}
+
+// src/controllers/toolbar_controller.ts
+var ToolbarController = class extends Controller {
+  static targets = ["control"];
+  static values = {
+    orientation: { type: String, default: "horizontal" },
+    wrap: { type: Boolean, default: true }
+  };
+  static actions = ["onKeydown"];
+  #roving = new RovingTabindex(() => this.controlTargets);
+  /**
+   * Establishes the single tab stop: keep an existing one if it is still
+   * navigable, else the first navigable control. Disabled / hidden controls are
+   * skipped so the toolbar's lone Tab stop never lands on an unfocusable element
+   * (which would make the whole group unreachable on Tab re-entry).
+   */
+  connect() {
+    const active = this.#roving.activeIndex;
+    const activeEl = active === -1 ? null : this.controlTargets[active];
+    if (activeEl && this.#isNavigable(activeEl)) {
+      this.#roving.setActive(active);
+      return;
+    }
+    const first = this.#navigableControls[0];
+    this.#roving.setActive(first ? this.controlTargets.indexOf(first) : -1);
+  }
+  /** Arrow/Home/End move focus and the single tab stop. Bound via `data-action`. */
+  onKeydown(event) {
+    const navigable = this.#navigableControls;
+    const current = navigable.indexOf(event.currentTarget);
+    if (current === -1) return;
+    const length = navigable.length;
+    const wrap = this.wrapValue ? "wrap" : "clamp";
+    const vertical = this.orientationValue === "vertical";
+    const forwardKey = vertical ? "ArrowDown" : "ArrowRight";
+    const backwardKey = vertical ? "ArrowUp" : "ArrowLeft";
+    let next;
+    if (event.key === forwardKey) {
+      next = rovingMove(current, length, 1, wrap);
+    } else if (event.key === backwardKey) {
+      next = rovingMove(current, length, -1, wrap);
+    } else if (event.key === "Home") {
+      next = 0;
+    } else if (event.key === "End") {
+      next = length - 1;
+    } else {
+      return;
+    }
+    event.preventDefault();
+    const target = navigable[next];
+    if (target) this.#roving.setActive(this.controlTargets.indexOf(target), { focus: true });
+  }
+  /** Controls eligible for the roving tab stop (excludes disabled / hidden). */
+  get #navigableControls() {
+    return this.controlTargets.filter((control) => this.#isNavigable(control));
+  }
+  /**
+   * A control can hold the tab stop unless it is `hidden`, `aria-disabled`, or a
+   * natively `disabled` form control. CSS-only visibility cannot be detected
+   * headlessly and stays the consumer's responsibility.
+   */
+  #isNavigable(control) {
+    if (control.hasAttribute("hidden")) return false;
+    if (control.getAttribute("aria-disabled") === "true") return false;
+    return !control.disabled;
+  }
+};
+
+export { ToolbarController };
+//# sourceMappingURL=toolbar_controller.js.map
+//# sourceMappingURL=toolbar_controller.js.map