stimeo-ui 0.2.0 → 0.3.0

data/dist/controllers/carousel_controller.js

@@ -0,0 +1,313 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/carousel_controller.ts
+
+// src/utils/logical_scroll.ts
+function isRtl(element) {
+  return window.getComputedStyle(element).direction === "rtl";
+}
+
+// src/utils/arrow_step.ts
+function logicalArrowStep(key, element) {
+  if (key === "ArrowDown") return 1;
+  if (key === "ArrowUp") return -1;
+  if (key !== "ArrowRight" && key !== "ArrowLeft") return 0;
+  const forward = isRtl(element) ? "ArrowLeft" : "ArrowRight";
+  return key === forward ? 1 : -1;
+}
+function isReservedArrowChord(event, allow = []) {
+  if (!event.key.startsWith("Arrow")) return false;
+  return event.altKey && !allow.includes("alt") || event.ctrlKey && !allow.includes("ctrl") || event.metaKey && !allow.includes("meta") || event.shiftKey && !allow.includes("shift");
+}
+
+// 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/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/carousel_controller.ts
+var CarouselController = class extends Controller {
+  static targets = ["slide", "viewport", "prev", "next", "picker", "playToggle"];
+  static values = {
+    autoplay: { type: Boolean, default: false },
+    interval: { type: Number, default: 5e3 },
+    loop: { type: Boolean, default: true }
+  };
+  static actions = [
+    "goto",
+    "next",
+    "onPickerKeydown",
+    "pause",
+    "prev",
+    "resume",
+    "togglePlay"
+  ];
+  static events = ["change", "pause", "play"];
+  #roving = new RovingTabindex(() => this.pickerTargets);
+  /** Gates the target callback so it does not repaint once per authored picker on mount. */
+  #connected = false;
+  #intervals = new SafeInterval();
+  /** Index of the visible slide. */
+  #index = 0;
+  /** User intent to autoplay (toggled by the play button / focus hard-stop). */
+  #playing = false;
+  /** Pointer is hovering the carousel: a temporary, auto-resuming suspension. */
+  #pointerPaused = false;
+  /** Id of the live autoplay interval, or null when stopped. */
+  #timerId = null;
+  /**
+   * Renders the initial slide and starts autoplay when requested.
+   *
+   * `findIndex` makes the authored pre-selection first-wins when several pickers
+   * are marked; `#render` then writes an explicit value onto every picker.
+   */
+  connect() {
+    const preselected = this.pickerTargets.findIndex(
+      (picker) => picker.getAttribute("aria-selected") === "true"
+    );
+    this.#index = preselected === -1 ? 0 : preselected;
+    this.#playing = this.#initialPlaying();
+    this.#render({ focus: false });
+    this.#syncTimer();
+    this.#connected = true;
+  }
+  /**
+   * Re-establishes the single selected picker when one is added after connect.
+   *
+   * Without this an appended picker that arrives `aria-selected="true"` leaves two
+   * marked at once — the authored pre-selection is only read on connect, so
+   * nothing else ever resolves the conflict. The current slide is kept: the
+   * repaint re-derives every picker from `#index`, so a late arrival never steals
+   * the selection.
+   */
+  pickerTargetConnected() {
+    if (!this.#connected) return;
+    this.#render({ focus: false });
+  }
+  /**
+   * Resolves the starting autoplay intent. The play toggle's `aria-pressed` is the
+   * source of truth **when present**, so a Turbo Drive cache restore / morph that
+   * re-runs `connect()` against existing DOM does not silently resume autoplay the
+   * user had stopped (e.g. by focusing into the carousel). Only when no toggle
+   * carries `aria-pressed` does it fall back to the declarative `autoplay` value.
+   */
+  #initialPlaying() {
+    if (this.hasPlayToggleTarget && this.playToggleTarget.hasAttribute("aria-pressed")) {
+      return this.playToggleTarget.getAttribute("aria-pressed") === "true";
+    }
+    return this.autoplayValue;
+  }
+  /** Clears the autoplay interval so it never fires after teardown. */
+  disconnect() {
+    this.#connected = false;
+    this.#intervals.clearAll();
+    this.#timerId = null;
+  }
+  /** Advances to the next slide. Bound via `data-action`. */
+  next() {
+    this.#select(this.#step(1), { focus: false });
+  }
+  /** Returns to the previous slide. Bound via `data-action`. */
+  prev() {
+    this.#select(this.#step(-1), { focus: false });
+  }
+  /** Jumps to the slide whose picker was activated (click / Enter / Space). */
+  goto(event) {
+    const target = event.currentTarget;
+    const index = this.pickerTargets.indexOf(target);
+    if (index !== -1) this.#select(index, { focus: false });
+  }
+  /** Toggles autoplay on the user's explicit request and syncs the timer. */
+  togglePlay() {
+    this.#playing = !this.#playing;
+    this.#syncTimer();
+  }
+  /**
+   * Suspends autoplay. Hover (`mouseenter`) is a temporary suspension that resumes
+   * on leave; keyboard focus (`focusin`) is a hard stop that turns autoplay off so
+   * it cannot resume without an explicit play (WCAG 2.2.2).
+   */
+  pause(event) {
+    if (event?.type.startsWith("focus")) {
+      this.#playing = false;
+    } else {
+      this.#pointerPaused = true;
+    }
+    this.#syncTimer();
+  }
+  /**
+   * Lifts a hover suspension (`mouseleave`) and resumes autoplay if it is still
+   * on. A `focusout` does nothing here: the focus pause was a hard stop, so the
+   * user must press play to restart.
+   */
+  resume(event) {
+    if (event?.type.startsWith("focus")) return;
+    this.#pointerPaused = false;
+    this.#syncTimer();
+  }
+  /** Picker roving: arrows move focus only; Home/End activate first/last slide. */
+  onPickerKeydown(event) {
+    if (event.defaultPrevented) return;
+    if (isReservedArrowChord(event)) return;
+    const current = this.pickerTargets.indexOf(event.currentTarget);
+    if (current === -1) return;
+    const length = this.pickerTargets.length;
+    switch (event.key) {
+      case "ArrowRight":
+      case "ArrowDown":
+      case "ArrowLeft":
+      case "ArrowUp": {
+        event.preventDefault();
+        const step = logicalArrowStep(event.key, this.element);
+        this.#roving.setActive(rovingMove(current, length, step), { focus: true });
+        return;
+      }
+      case "Home":
+        event.preventDefault();
+        this.#select(0, { focus: true });
+        return;
+      case "End":
+        event.preventDefault();
+        this.#select(length - 1, { focus: true });
+        return;
+    }
+  }
+  /** Resolves the index one step away from the current one, honoring `loop`. */
+  #step(delta) {
+    const total = this.slideTargets.length;
+    if (total === 0) return 0;
+    const next = this.#index + delta;
+    if (this.loopValue) return (next + total) % total;
+    return Math.min(total - 1, Math.max(0, next));
+  }
+  /**
+   * Changes the active slide, updates state hooks, and emits `change` — but only
+   * when the index actually changes, so a `next`/`prev` clamped at the end (or an
+   * autoplay tick at a non-looping boundary) re-renders without a spurious event
+   * (matching the "emit on real change" policy of flash/masonry/bulk-select).
+   */
+  #select(index, { focus }) {
+    const changed = index !== this.#index;
+    this.#index = index;
+    this.#render({ focus });
+    this.#syncTimer();
+    if (changed) this.dispatch("change", { detail: { index, total: this.slideTargets.length } });
+  }
+  /** Reflects `this.#index` onto slides and pickers (state hooks + roving). */
+  #render({ focus }) {
+    this.slideTargets.forEach((slide, i) => {
+      const active = i === this.#index;
+      slide.setAttribute("data-state", active ? "active" : "inactive");
+      slide.hidden = !active;
+    });
+    this.pickerTargets.forEach((picker, i) => {
+      picker.setAttribute("aria-selected", i === this.#index ? "true" : "false");
+    });
+    this.#roving.setActive(this.#index, { focus });
+  }
+  /**
+   * Drives the autoplay interval toward the desired state. Autoplay should run
+   * only when the user wants it (`playing`), the pointer is not hovering, and more
+   * than one slide exists. Transitions emit `play`/`pause` and keep the toggle's
+   * `aria-pressed` in sync.
+   */
+  #syncTimer() {
+    if (!this.loopValue && this.#index >= this.slideTargets.length - 1) {
+      this.#playing = false;
+    }
+    const shouldRun = this.#playing && !this.#pointerPaused && this.slideTargets.length > 1;
+    if (shouldRun && this.#timerId === null) {
+      this.#timerId = this.#intervals.set(() => this.next(), this.intervalValue);
+      this.dispatch("play");
+    } else if (!shouldRun && this.#timerId !== null) {
+      this.#intervals.clear(this.#timerId);
+      this.#timerId = null;
+      this.dispatch("pause");
+    }
+    if (this.hasPlayToggleTarget) {
+      this.playToggleTarget.setAttribute("aria-pressed", this.#playing ? "true" : "false");
+    }
+  }
+};
+
+export { CarouselController };
+//# sourceMappingURL=carousel_controller.js.map
+//# sourceMappingURL=carousel_controller.js.map

data/dist/controllers/clipboard_controller.js

@@ -0,0 +1,144 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/clipboard_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/clipboard_controller.ts
+var ClipboardController = class extends Controller {
+  static targets = ["source", "button", "feedback"];
+  static values = {
+    text: { type: String, default: "" },
+    feedbackDuration: { type: Number, default: 2e3 },
+    copiedLabel: { type: String, default: "Copied" },
+    errorLabel: { type: String, default: "Copy failed" }
+  };
+  static actions = ["copy"];
+  static events = ["copy"];
+  /** Auto-clear timer for the completion notice; torn down on disconnect. */
+  #timers = new SafeTimeout();
+  /**
+   * The pending auto-clear timer id, or `null` when none is scheduled. Tracked so
+   * a rapid second copy cancels the first window instead of letting a stale timer
+   * reset the freshly-shown notice early.
+   */
+  #resetTimerId = null;
+  connect() {
+    if (!this.element.hasAttribute("data-state")) {
+      this.element.setAttribute("data-state", "idle");
+    }
+  }
+  disconnect() {
+    this.#timers.clearAll();
+  }
+  /**
+   * Copies the resolved text and reports the outcome. Bound via `data-action`
+   * (click). Always dispatches `stimeo--clipboard:copy` with `{ success, text }`
+   * — including on failure — so consumers can react either way.
+   */
+  async copy() {
+    const text = this.#resolveText();
+    let success = false;
+    try {
+      if (!navigator.clipboard?.writeText) throw new Error("Clipboard API unavailable");
+      await navigator.clipboard.writeText(text);
+      success = true;
+    } catch {
+      success = false;
+    }
+    this.#reportResult(success);
+    this.dispatch("copy", { detail: { success, text } });
+  }
+  /**
+   * The text to copy: the explicit `text` value when set, otherwise the source
+   * target's current value (inputs/textareas) or text content.
+   */
+  #resolveText() {
+    if (this.textValue.length > 0) return this.textValue;
+    if (!this.hasSourceTarget) return "";
+    const source = this.sourceTarget;
+    if (source instanceof HTMLInputElement || source instanceof HTMLTextAreaElement) {
+      return source.value;
+    }
+    return source.textContent ?? "";
+  }
+  /** Reflects the result on `data-state`, announces it, and schedules a reset. */
+  #reportResult(success) {
+    this.element.setAttribute("data-state", success ? "copied" : "error");
+    if (this.hasFeedbackTarget) {
+      this.feedbackTarget.textContent = success ? this.copiedLabelValue : this.errorLabelValue;
+    }
+    if (this.#resetTimerId !== null) {
+      this.#timers.clear(this.#resetTimerId);
+      this.#resetTimerId = null;
+    }
+    if (this.feedbackDurationValue > 0) {
+      this.#resetTimerId = this.#timers.set(() => {
+        this.#resetTimerId = null;
+        this.#reset();
+      }, this.feedbackDurationValue);
+    }
+  }
+  /** Returns to the idle state and clears the completion notice. */
+  #reset() {
+    this.element.setAttribute("data-state", "idle");
+    if (this.hasFeedbackTarget) {
+      this.feedbackTarget.textContent = "";
+    }
+  }
+};
+
+export { ClipboardController };
+//# sourceMappingURL=clipboard_controller.js.map
+//# sourceMappingURL=clipboard_controller.js.map