stimeo-ui 0.1.0.pre.alpha.1

data/dist/controllers/slider_controller.js

@@ -0,0 +1,109 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/slider_controller.ts
+var FRACTION_PROPERTY = "--stimeo--slider-fraction";
+var SliderController = class extends Controller {
+  static targets = ["track", "thumb"];
+  static values = {
+    min: { type: Number, default: 0 },
+    max: { type: Number, default: 100 },
+    step: { type: Number, default: 1 },
+    value: { type: Number, default: 0 }
+  };
+  static actions = ["onKeydown", "onPointerDown"];
+  static events = ["change"];
+  /** Aborts in-progress pointer-drag listeners when the drag ends or on teardown. */
+  #dragAbort = null;
+  /** Clamps the initial value and renders the starting position. */
+  connect() {
+    this.#setValue(this.valueValue, { silent: true });
+  }
+  /** Cancels any active pointer drag so document listeners never leak. */
+  disconnect() {
+    this.#dragAbort?.abort();
+    this.#dragAbort = null;
+  }
+  /** Handles keyboard stepping per the APG slider model. */
+  onKeydown(event) {
+    const big = this.stepValue * 10;
+    let next = null;
+    switch (event.key) {
+      case "ArrowRight":
+      case "ArrowUp":
+        next = this.valueValue + this.stepValue;
+        break;
+      case "ArrowLeft":
+      case "ArrowDown":
+        next = this.valueValue - this.stepValue;
+        break;
+      case "PageUp":
+        next = this.valueValue + big;
+        break;
+      case "PageDown":
+        next = this.valueValue - big;
+        break;
+      case "Home":
+        next = this.minValue;
+        break;
+      case "End":
+        next = this.maxValue;
+        break;
+      default:
+        return;
+    }
+    event.preventDefault();
+    this.#setValue(next);
+  }
+  /** Begins a pointer drag: sets the value and tracks subsequent movement. */
+  onPointerDown(event) {
+    if (!this.hasTrackTarget) return;
+    event.preventDefault();
+    this.#updateFromClientX(event.clientX);
+    if (this.hasThumbTarget) this.thumbTarget.focus();
+    this.#dragAbort?.abort();
+    const abort = new AbortController();
+    this.#dragAbort = abort;
+    const onMove = (move) => this.#updateFromClientX(move.clientX);
+    const onUp = () => {
+      abort.abort();
+      this.#dragAbort = null;
+    };
+    document.addEventListener("pointermove", onMove, { signal: abort.signal });
+    document.addEventListener("pointerup", onUp, { signal: abort.signal });
+    document.addEventListener("pointercancel", onUp, { signal: abort.signal });
+  }
+  /** Maps a pointer X coordinate to a value using the track's geometry. */
+  #updateFromClientX(clientX) {
+    const rect = this.trackTarget.getBoundingClientRect();
+    if (rect.width === 0) return;
+    const fraction = (clientX - rect.left) / rect.width;
+    this.#setValue(this.minValue + fraction * (this.maxValue - this.minValue));
+  }
+  /**
+   * Clamps `raw` to `[min, max]`, snaps it to the nearest step, stores it, and
+   * reflects the new state on the thumb's ARIA attributes and the fraction
+   * custom property. Dispatches `change` (detail `{ value }`) on a real value
+   * change — symmetric with `range-slider` — unless `silent` (the initial
+   * connect render, which is not a user edit).
+   */
+  #setValue(raw, { silent = false } = {}) {
+    const clamped = Math.min(this.maxValue, Math.max(this.minValue, raw));
+    const stepped = this.stepValue > 0 ? Math.round((clamped - this.minValue) / this.stepValue) * this.stepValue + this.minValue : clamped;
+    const value = Math.min(this.maxValue, Math.max(this.minValue, stepped));
+    const changed = value !== this.valueValue;
+    this.valueValue = value;
+    if (this.hasThumbTarget) {
+      this.thumbTarget.setAttribute("aria-valuemin", String(this.minValue));
+      this.thumbTarget.setAttribute("aria-valuemax", String(this.maxValue));
+      this.thumbTarget.setAttribute("aria-valuenow", String(value));
+    }
+    const span = this.maxValue - this.minValue;
+    const fraction = span > 0 ? (value - this.minValue) / span : 0;
+    this.element.style.setProperty(FRACTION_PROPERTY, String(fraction));
+    if (changed && !silent) this.dispatch("change", { detail: { value } });
+  }
+};
+
+export { SliderController };
+//# sourceMappingURL=slider_controller.js.map
+//# sourceMappingURL=slider_controller.js.map

data/dist/controllers/spinner_controller.js

@@ -0,0 +1,164 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/spinner_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/spinner_controller.ts
+var SpinnerController = class extends Controller {
+  static targets = ["indicator", "region", "message"];
+  static values = {
+    delay: { type: Number, default: 0 },
+    minDuration: { type: Number, default: 0 }
+  };
+  static actions = ["start", "stop"];
+  static events = ["hide", "show"];
+  #timers = new SafeTimeout();
+  /** Pending show-delay timer id, or `null` when no start is awaiting its delay. */
+  #delayTimerId = null;
+  /** Pending min-duration hide timer id, or `null` when none is scheduled. */
+  #hideTimerId = null;
+  /** Epoch ms when the spinner became visible, used to enforce `minDuration`. */
+  #shownAt = 0;
+  connect() {
+    if (!this.element.hasAttribute("data-state")) {
+      this.element.setAttribute("data-state", "idle");
+    }
+  }
+  disconnect() {
+    this.#timers.clearAll();
+    this.#delayTimerId = null;
+    this.#hideTimerId = null;
+  }
+  /** Begins loading. Honors `delay` before the spinner actually appears. */
+  start() {
+    if (this.#state === "loading") {
+      this.#setBusy(true);
+      this.#cancelHide();
+      return;
+    }
+    if (this.#state !== "idle") return;
+    this.#setBusy(true);
+    this.#cancelHide();
+    if (this.delayValue > 0) {
+      this.element.setAttribute("data-state", "pending");
+      this.#delayTimerId = this.#timers.set(() => {
+        this.#delayTimerId = null;
+        this.#show();
+      }, this.delayValue);
+    } else {
+      this.#show();
+    }
+  }
+  /** Ends loading. Honors `minDuration` so a shown spinner does not flicker. */
+  stop() {
+    const state = this.#state;
+    if (state === "pending") {
+      this.#cancelDelay();
+      this.#setBusy(false);
+      this.element.setAttribute("data-state", "idle");
+      return;
+    }
+    if (state !== "loading") return;
+    this.#setBusy(false);
+    const remaining = this.minDurationValue - (Date.now() - this.#shownAt);
+    if (remaining > 0) {
+      this.#hideTimerId = this.#timers.set(() => {
+        this.#hideTimerId = null;
+        this.#hide();
+      }, remaining);
+    } else {
+      this.#hide();
+    }
+  }
+  /** Reveals the indicator, marks the moment shown, and announces via the live region. */
+  #show() {
+    this.#shownAt = Date.now();
+    if (this.hasIndicatorTarget) this.indicatorTarget.hidden = false;
+    this.element.setAttribute("data-state", "loading");
+    this.dispatch("show", { detail: {} });
+  }
+  /** Hides the indicator and returns to the idle state. */
+  #hide() {
+    if (this.hasIndicatorTarget) this.indicatorTarget.hidden = true;
+    this.element.setAttribute("data-state", "idle");
+    this.dispatch("hide", { detail: {} });
+  }
+  /** Reflects busy state onto the controlled region (if present). */
+  #setBusy(busy) {
+    if (this.hasRegionTarget) {
+      this.regionTarget.setAttribute("aria-busy", String(busy));
+    }
+  }
+  #cancelDelay() {
+    if (this.#delayTimerId !== null) {
+      this.#timers.clear(this.#delayTimerId);
+      this.#delayTimerId = null;
+    }
+  }
+  #cancelHide() {
+    if (this.#hideTimerId !== null) {
+      this.#timers.clear(this.#hideTimerId);
+      this.#hideTimerId = null;
+    }
+  }
+  /** Current lifecycle phase as reflected on `data-state`. */
+  get #state() {
+    return this.element.getAttribute("data-state") ?? "idle";
+  }
+};
+
+export { SpinnerController };
+//# sourceMappingURL=spinner_controller.js.map
+//# sourceMappingURL=spinner_controller.js.map

data/dist/controllers/step_indicator_controller.js

@@ -0,0 +1,55 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/step_indicator_controller.ts
+var StepIndicatorController = class extends Controller {
+  static targets = ["step"];
+  static values = {
+    current: { type: Number, default: 0 }
+  };
+  static actions = ["setCurrent"];
+  static events = ["change"];
+  /** Renders the initial state from the `current` value. */
+  connect() {
+    this.#render();
+  }
+  /**
+   * Updates the current step from an external event (`detail.current`, 0-based)
+   * and dispatches `change`. Out-of-range indices are clamped to the step set.
+   */
+  setCurrent(event) {
+    const next = event.detail?.current;
+    if (typeof next !== "number" || !Number.isFinite(next)) return;
+    const clamped = this.#clamp(next);
+    if (clamped === this.currentValue) return;
+    this.currentValue = clamped;
+    this.#render();
+    this.dispatch("change", {
+      detail: { current: clamped, total: this.stepTargets.length }
+    });
+  }
+  /** Applies `data-state`, `aria-current`, and the progress ratio custom property. */
+  #render() {
+    const total = this.stepTargets.length;
+    const current = this.#clamp(this.currentValue);
+    this.stepTargets.forEach((step, index) => {
+      step.dataset.state = index < current ? "complete" : index === current ? "current" : "upcoming";
+      if (index === current) {
+        step.setAttribute("aria-current", "step");
+      } else {
+        step.removeAttribute("aria-current");
+      }
+    });
+    const ratio = total > 1 ? current / (total - 1) : 0;
+    this.element.style.setProperty("--stimeo-step-indicator-ratio", String(ratio));
+  }
+  /** Constrains an index to `[0, total-1]` (or `0` when there are no steps). */
+  #clamp(index) {
+    const last = this.stepTargets.length - 1;
+    if (last < 0) return 0;
+    return Math.min(last, Math.max(0, Math.trunc(index)));
+  }
+};
+
+export { StepIndicatorController };
+//# sourceMappingURL=step_indicator_controller.js.map
+//# sourceMappingURL=step_indicator_controller.js.map

data/dist/controllers/stepper_controller.js

@@ -0,0 +1,78 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/stepper_controller.ts
+var StepperController = class extends Controller {
+  static targets = ["step"];
+  static values = {
+    index: { type: Number, default: 0 },
+    linear: { type: Boolean, default: false }
+  };
+  static actions = ["goto", "next", "prev"];
+  static events = ["change"];
+  /** Normalizes an out-of-range initial `index` and renders the initial state. */
+  connect() {
+    this.indexValue = this.#clampIndex(this.indexValue);
+    this.#render();
+  }
+  /** Advances to the next step (ignored at the last step). */
+  next() {
+    this.#moveTo(this.indexValue + 1);
+  }
+  /** Returns to the previous step (ignored at the first step). */
+  prev() {
+    this.#moveTo(this.indexValue - 1);
+  }
+  /** Jumps to the step carried in the action's `index` param. */
+  goto(event) {
+    const target = Number(event.params.index);
+    if (!Number.isFinite(target)) return;
+    this.#moveTo(target);
+  }
+  /**
+   * Moves the current step to `target` when allowed: in range, not a no-op, and
+   * — under `linear` — not skipping more than one step ahead. Re-renders and
+   * dispatches `change`.
+   */
+  #moveTo(target) {
+    const total = this.stepTargets.length;
+    if (target < 0 || target >= total) return;
+    if (target === this.indexValue) return;
+    if (this.linearValue && target > this.indexValue + 1) return;
+    const previous = this.indexValue;
+    this.indexValue = target;
+    this.#render();
+    this.dispatch("change", {
+      detail: { index: target, previous, step: this.stepTargets[target] }
+    });
+  }
+  /**
+   * Derives each step's `data-state` and the current button's `aria-current`.
+   *
+   * `aria-current="step"` is placed on the step's **first** `<button>`; the markup
+   * contract assumes one operable button per step. If a step needs multiple
+   * buttons, mark the navigational one first (or this would target the wrong one).
+   */
+  #render() {
+    const current = this.indexValue;
+    this.stepTargets.forEach((step, index) => {
+      step.dataset.state = index < current ? "complete" : index === current ? "current" : "upcoming";
+      const button = step.querySelector("button");
+      if (!button) return;
+      if (index === current) {
+        button.setAttribute("aria-current", "step");
+      } else {
+        button.removeAttribute("aria-current");
+      }
+    });
+  }
+  /** Constrains an index to `[0, total-1]` (or `0` when there are no steps). */
+  #clampIndex(index) {
+    const last = this.stepTargets.length - 1;
+    if (last < 0) return 0;
+    return Math.min(last, Math.max(0, Math.trunc(index)));
+  }
+};
+
+export { StepperController };
+//# sourceMappingURL=stepper_controller.js.map
+//# sourceMappingURL=stepper_controller.js.map

data/dist/controllers/stick_to_bottom_controller.js

@@ -0,0 +1,100 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/stick_to_bottom_controller.ts
+var countElements = (nodes) => {
+  let n = 0;
+  for (const node of nodes) if (node.nodeType === Node.ELEMENT_NODE) n += 1;
+  return n;
+};
+var StickToBottomController = class extends Controller {
+  static targets = ["content"];
+  static values = {
+    threshold: { type: Number, default: 80 },
+    behavior: { type: String, default: "auto" }
+  };
+  static actions = ["scrollToBottom"];
+  static events = ["pin", "new"];
+  #observer = null;
+  #pinned = false;
+  #onScroll = () => this.#updatePinned();
+  connect() {
+    this.#pinned = this.#isPinned();
+    this.#reflectPinned();
+    this.element.addEventListener("scroll", this.#onScroll, { passive: true });
+    if (typeof MutationObserver !== "undefined") {
+      this.#observer = new MutationObserver((mutations) => this.#onMutations(mutations));
+      this.#observer.observe(this.#watched(), { childList: true });
+    }
+  }
+  disconnect() {
+    this.element.removeEventListener("scroll", this.#onScroll);
+    this.#observer?.disconnect();
+    this.#observer = null;
+  }
+  /** Jumps to the bottom and re-pins (wired to a "new messages" button). */
+  scrollToBottom() {
+    this.#scrollToBottom();
+    this.element.removeAttribute("data-has-new");
+    if (!this.#pinned) {
+      this.#pinned = true;
+      this.element.setAttribute("data-pinned", "true");
+      this.dispatch("pin", { detail: { pinned: true } });
+    }
+  }
+  /** Follows appended children while pinned; otherwise flags new content. */
+  #onMutations(mutations) {
+    let added = 0;
+    for (const mutation of mutations) added += countElements(mutation.addedNodes);
+    if (added === 0) return;
+    if (this.#pinned) {
+      this.#scrollToBottom();
+    } else {
+      this.element.setAttribute("data-has-new", "true");
+      this.dispatch("new", { detail: { count: added } });
+    }
+  }
+  /** Recomputes pinned from the scroll position and reflects it on a transition. */
+  #updatePinned() {
+    const pinned = this.#isPinned();
+    if (pinned === this.#pinned) return;
+    this.#pinned = pinned;
+    this.#reflectPinned();
+    this.dispatch("pin", { detail: { pinned } });
+  }
+  /** Mirrors the current `#pinned` onto the state hooks (clearing has-new once pinned). */
+  #reflectPinned() {
+    if (this.#pinned) {
+      this.element.setAttribute("data-pinned", "true");
+      this.element.removeAttribute("data-has-new");
+    } else {
+      this.element.removeAttribute("data-pinned");
+    }
+  }
+  #isPinned() {
+    const el = this.element;
+    return el.scrollHeight - el.clientHeight - el.scrollTop <= this.thresholdValue;
+  }
+  #scrollToBottom() {
+    const top = this.element.scrollHeight;
+    if (typeof this.element.scrollTo === "function") {
+      this.element.scrollTo({ top, behavior: this.#behavior() });
+    } else {
+      this.element.scrollTop = top;
+    }
+  }
+  /** The append-watched element: the `content` target, or the container itself. */
+  #watched() {
+    return this.hasContentTarget ? this.contentTarget : this.element;
+  }
+  #behavior() {
+    if (this.#prefersReducedMotion()) return "auto";
+    return this.behaviorValue === "smooth" ? "smooth" : "auto";
+  }
+  #prefersReducedMotion() {
+    return typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  }
+};
+
+export { StickToBottomController };
+//# sourceMappingURL=stick_to_bottom_controller.js.map
+//# sourceMappingURL=stick_to_bottom_controller.js.map

data/dist/controllers/sticky_observer_controller.js

@@ -0,0 +1,53 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/sticky_observer_controller.ts
+var StickyObserverController = class extends Controller {
+  static targets = ["sentinel", "element"];
+  static values = {
+    rootSelector: { type: String, default: "" },
+    offset: { type: Number, default: 0 }
+  };
+  static events = ["change"];
+  #observer = null;
+  /** Guards against a queued callback mutating state after teardown. */
+  #active = false;
+  /** Last reported stuck state, so `change` fires only on transitions. */
+  #stuck = null;
+  #onIntersect = (entries) => {
+    if (!this.#active) return;
+    const entry = entries[entries.length - 1];
+    if (!entry) return;
+    this.#setStuck(!entry.isIntersecting);
+  };
+  connect() {
+    if (!this.hasSentinelTarget) return;
+    this.#active = true;
+    if (typeof IntersectionObserver === "undefined") return;
+    const root = this.rootSelectorValue ? document.querySelector(this.rootSelectorValue) : null;
+    this.#observer = new IntersectionObserver(this.#onIntersect, {
+      root,
+      rootMargin: `-${this.offsetValue}px 0px 0px 0px`,
+      threshold: [0]
+    });
+    this.#observer.observe(this.sentinelTarget);
+  }
+  disconnect() {
+    this.#active = false;
+    this.#observer?.disconnect();
+    this.#observer = null;
+    this.#stuck = null;
+  }
+  /** Reflects the stuck state onto the sticky element and emits `change`. */
+  #setStuck(next) {
+    if (next === this.#stuck) return;
+    this.#stuck = next;
+    if (this.hasElementTarget) {
+      this.elementTarget.setAttribute("data-stuck", next ? "true" : "false");
+    }
+    this.dispatch("change", { detail: { stuck: next } });
+  }
+};
+
+export { StickyObserverController };
+//# sourceMappingURL=sticky_observer_controller.js.map
+//# sourceMappingURL=sticky_observer_controller.js.map