stimeo-ui 0.2.0 → 0.2.1

package/dist/controllers/password_reveal_controller.js

@@ -0,0 +1,117 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/password_reveal_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/password_reveal_controller.ts
+var PasswordRevealController = class extends Controller {
+  static targets = ["input", "toggle"];
+  static values = {
+    autoHide: { type: Number, default: 0 }
+  };
+  static actions = ["toggle"];
+  static events = ["toggle"];
+  /** Auto re-mask timer; torn down on disconnect. */
+  #timers = new SafeTimeout();
+  connect() {
+    this.#reflect(this.#isVisible);
+  }
+  disconnect() {
+    this.#timers.clearAll();
+  }
+  /** Toggles the input between masked and revealed. Bound via `data-action`. */
+  toggle() {
+    this.#setVisible(!this.#isVisible);
+  }
+  /** Whether the input is currently revealed (`type="text"`). */
+  get #isVisible() {
+    return this.hasInputTarget && this.inputTarget.type === "text";
+  }
+  /** Switches the masked/revealed state, preserving focus and caret. */
+  #setVisible(visible) {
+    if (!this.hasInputTarget) return;
+    const input = this.inputTarget;
+    const restoreInputFocus = document.activeElement === input;
+    const selectionStart = input.selectionStart;
+    const selectionEnd = input.selectionEnd;
+    input.type = visible ? "text" : "password";
+    if (restoreInputFocus) {
+      input.focus();
+      if (selectionStart !== null && selectionEnd !== null) {
+        try {
+          input.setSelectionRange(selectionStart, selectionEnd);
+        } catch {
+        }
+      }
+    }
+    this.#reflect(visible);
+    this.dispatch("toggle", { detail: { visible } });
+    this.#timers.clearAll();
+    if (visible && this.autoHideValue > 0) {
+      this.#timers.set(() => this.#setVisible(false), this.autoHideValue);
+    }
+  }
+  /** Reflects the visible state onto `aria-pressed` and `data-state`. */
+  #reflect(visible) {
+    if (this.hasToggleTarget) {
+      this.toggleTarget.setAttribute("aria-pressed", visible ? "true" : "false");
+    }
+    this.element.setAttribute("data-state", visible ? "visible" : "hidden");
+  }
+};
+
+export { PasswordRevealController };
+//# sourceMappingURL=password_reveal_controller.js.map
+//# sourceMappingURL=password_reveal_controller.js.map

package/dist/controllers/password_reveal_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/safe_timeout.ts","../../src/controllers/password_reveal_controller.ts"],"names":[],"mappings":"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","file":"password_reveal_controller.js","sourcesContent":["/**\n * Self-cleaning timer registries shared by Stimeo controllers.\n *\n * Stimulus controllers frequently schedule `setTimeout` / `setInterval` work\n * (auto-dismiss, debouncing, polling). When the element leaves the DOM — a\n * Turbo Drive navigation, a Turbo Stream replacement, or any `disconnect()` —\n * orphaned timers keep firing against a detached controller, leaking memory and\n * mutating stale state. {@link SafeTimeout} and {@link SafeInterval} track every\n * timer they create so a single {@link TimerRegistry.clearAll | clearAll()} call\n * in `disconnect()` tears them all down.\n *\n * These are intentionally low-level primitives: they own *registration and\n * cleanup only*. Higher-level policy (pause/resume, remaining-time accounting)\n * stays in the individual controllers so per-widget semantics are not flattened\n * into a lowest-common-denominator helper.\n */\n\n/**\n * Shared registry bookkeeping for the timeout/interval variants.\n *\n * Subclasses provide the scheduling primitive ({@link schedule}) and its matching\n * canceller ({@link cancel}); this base owns the set of live ids plus the\n * per-id and bulk teardown shared by both.\n */\nabstract class TimerRegistry {\n  /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */\n  protected readonly ids = new Set<number>();\n\n  /** Schedules the underlying platform timer and returns its id. */\n  protected abstract schedule(callback: () => void, delay: number): number;\n\n  /** Cancels the underlying platform timer for `id`. */\n  protected abstract cancel(id: number): void;\n\n  /**\n   * Cancels a single tracked timer.\n   *\n   * No-ops if the id is unknown (already cleared, fired, or never owned by this\n   * registry), so callers can clear defensively without guarding.\n   */\n  clear(id: number): void {\n    if (this.ids.delete(id)) {\n      this.cancel(id);\n    }\n  }\n\n  /**\n   * Cancels every tracked timer. Call this from a controller's `disconnect()`\n   * to guarantee no timer outlives the element.\n   */\n  clearAll(): void {\n    for (const id of this.ids) {\n      this.cancel(id);\n    }\n    this.ids.clear();\n  }\n\n  /** Number of timers currently tracked (pending). */\n  get size(): number {\n    return this.ids.size;\n  }\n}\n\n/**\n * `setTimeout` wrapper that auto-forgets each timer once it fires and supports\n * bulk teardown on disconnect.\n *\n * @example\n * ```ts\n * #timers = new SafeTimeout();\n *\n * connect() {\n *   this.#timers.set(() => this.dismiss(), 5000);\n * }\n *\n * disconnect() {\n *   this.#timers.clearAll();\n * }\n * ```\n */\nexport class SafeTimeout extends TimerRegistry {\n  /**\n   * Schedules `callback` after `delay` ms and returns the timer id.\n   *\n   * The id is removed from the registry automatically when the timeout fires,\n   * so {@link TimerRegistry.size | size} reflects only still-pending timers.\n   */\n  set(callback: () => void, delay: number): number {\n    const id = this.schedule(() => {\n      this.ids.delete(id);\n      callback();\n    }, delay);\n    this.ids.add(id);\n    return id;\n  }\n\n  protected schedule(callback: () => void, delay: number): number {\n    return window.setTimeout(callback, delay);\n  }\n\n  protected cancel(id: number): void {\n    window.clearTimeout(id);\n  }\n}\n\n/**\n * `setInterval` wrapper that tracks every interval for bulk teardown on\n * disconnect. Unlike {@link SafeTimeout}, intervals are retained until they are\n * explicitly cleared because they fire repeatedly.\n *\n * @example\n * ```ts\n * #intervals = new SafeInterval();\n *\n * connect() {\n *   this.#intervals.set(() => this.tick(), 1000);\n * }\n *\n * disconnect() {\n *   this.#intervals.clearAll();\n * }\n * ```\n */\nexport class SafeInterval extends TimerRegistry {\n  /** Schedules a repeating `callback` every `delay` ms and returns the timer id. */\n  set(callback: () => void, delay: number): number {\n    const id = this.schedule(callback, delay);\n    this.ids.add(id);\n    return id;\n  }\n\n  protected schedule(callback: () => void, delay: number): number {\n    return window.setInterval(callback, delay);\n  }\n\n  protected cancel(id: number): void {\n    window.clearInterval(id);\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { SafeTimeout } from \"../utils/safe_timeout\";\n\n/**\n * Headless password show/hide (unmask) toggle behavior.\n *\n * Markup contract (identifier: `stimeo--password-reveal`):\n *   <div data-controller=\"stimeo--password-reveal\">\n *     <input type=\"password\" aria-label=\"Password\"\n *            data-stimeo--password-reveal-target=\"input\">\n *     <button type=\"button\" aria-pressed=\"false\" aria-label=\"Show password\"\n *             data-stimeo--password-reveal-target=\"toggle\"\n *             data-action=\"stimeo--password-reveal#toggle\"></button>\n *   </div>\n *\n * No dedicated APG pattern; this follows the toggle **Button** practice. The\n * accessible name stays state-independent (\"Show password\") while the pressed\n * state is conveyed by `aria-pressed`.\n *\n * @remarks\n * Behavior only — icon rendering is the consumer's, keyed off `aria-pressed` /\n * `data-state` (`hidden` / `visible`). Flipping `input.type` can drop focus and\n * the caret, so when (and only when) the input was the focused element its focus\n * and selection are restored afterward; when the toggle button holds focus\n * (keyboard use) focus is left on the button. An optional `autoHide` re-masks\n * after a delay, and that timer is torn down on disconnect (Turbo).\n */\nexport class PasswordRevealController extends Controller<HTMLElement> {\n  static override targets = [\"input\", \"toggle\"];\n  static override values = {\n    autoHide: { type: Number, default: 0 },\n  };\n  static actions = [\"toggle\"] as const;\n  static events = [\"toggle\"] as const;\n\n  declare readonly inputTarget: HTMLInputElement;\n  declare readonly toggleTarget: HTMLElement;\n  declare readonly hasInputTarget: boolean;\n  declare readonly hasToggleTarget: boolean;\n\n  declare autoHideValue: number;\n\n  /** Auto re-mask timer; torn down on disconnect. */\n  #timers = new SafeTimeout();\n\n  override connect(): void {\n    this.#reflect(this.#isVisible);\n  }\n\n  override disconnect(): void {\n    this.#timers.clearAll();\n  }\n\n  /** Toggles the input between masked and revealed. Bound via `data-action`. */\n  toggle(): void {\n    this.#setVisible(!this.#isVisible);\n  }\n\n  /** Whether the input is currently revealed (`type=\"text\"`). */\n  get #isVisible(): boolean {\n    return this.hasInputTarget && this.inputTarget.type === \"text\";\n  }\n\n  /** Switches the masked/revealed state, preserving focus and caret. */\n  #setVisible(visible: boolean): void {\n    if (!this.hasInputTarget) return;\n    const input = this.inputTarget;\n\n    // Only the input's *own* focus is restored across the type change; if the\n    // toggle button (keyboard) holds focus, it is left untouched.\n    const restoreInputFocus = document.activeElement === input;\n    const selectionStart = input.selectionStart;\n    const selectionEnd = input.selectionEnd;\n\n    input.type = visible ? \"text\" : \"password\";\n\n    if (restoreInputFocus) {\n      input.focus();\n      // `selectionStart` / `selectionEnd` are `number | null` (null for input\n      // types that don't expose a selection); only restore when both are present.\n      if (selectionStart !== null && selectionEnd !== null) {\n        try {\n          input.setSelectionRange(selectionStart, selectionEnd);\n        } catch {\n          // Some input types reject selection access; focus alone is enough.\n        }\n      }\n    }\n\n    this.#reflect(visible);\n    this.dispatch(\"toggle\", { detail: { visible } });\n\n    this.#timers.clearAll();\n    if (visible && this.autoHideValue > 0) {\n      this.#timers.set(() => this.#setVisible(false), this.autoHideValue);\n    }\n  }\n\n  /** Reflects the visible state onto `aria-pressed` and `data-state`. */\n  #reflect(visible: boolean): void {\n    if (this.hasToggleTarget) {\n      this.toggleTarget.setAttribute(\"aria-pressed\", visible ? \"true\" : \"false\");\n    }\n    this.element.setAttribute(\"data-state\", visible ? \"visible\" : \"hidden\");\n  }\n}\n"]}

package/dist/controllers/range_slider_controller.d.ts

@@ -0,0 +1,87 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless, accessible **two-thumb range slider** behavior (APG Slider —
+ * Multi-Thumb). A derivative of {@link SliderController}: it manages two thumbs
+ * (`start` ≤ `end`) that constrain each other.
+ *
+ * Markup contract (identifier: `stimeo--range-slider`):
+ *   <div data-controller="stimeo--range-slider"
+ *        data-stimeo--range-slider-min-value="0"
+ *        data-stimeo--range-slider-max-value="100"
+ *        data-stimeo--range-slider-step-value="1"
+ *        data-stimeo--range-slider-start-value="20"
+ *        data-stimeo--range-slider-end-value="80">
+ *     <div data-stimeo--range-slider-target="track"
+ *          data-action="pointerdown->stimeo--range-slider#onPointerDown">
+ *       <div role="slider" tabindex="0" aria-label="Minimum"
+ *            data-stimeo--range-slider-target="startThumb"
+ *            data-action="keydown->stimeo--range-slider#onKeydown"></div>
+ *       <div role="slider" tabindex="0" aria-label="Maximum"
+ *            data-stimeo--range-slider-target="endThumb"
+ *            data-action="keydown->stimeo--range-slider#onKeydown"></div>
+ *     </div>
+ *   </div>
+ *
+ * @remarks
+ * Behavior only — the consumer owns all layout (positioning the thumbs and the
+ * selected range from the fractions). Only the horizontal orientation is handled
+ * in this MVP. Each thumb's movable range is bounded by the *other* thumb's
+ * current value, reflected on its `aria-valuemin`/`aria-valuemax` so assistive
+ * tech announces the live constraint.
+ *
+ * Behavior provided (per focused thumb):
+ * - `ArrowRight`/`ArrowUp` increase and `ArrowLeft`/`ArrowDown` decrease by one
+ *   step; `Home`/`End` jump to that thumb's movable min/max; `PageUp`/`PageDown`
+ *   move by ten steps. A thumb never crosses the other.
+ * - Pointer press/drag on the track moves the nearest thumb.
+ */
+declare class RangeSliderController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        min: {
+            type: NumberConstructor;
+            default: number;
+        };
+        max: {
+            type: NumberConstructor;
+            default: number;
+        };
+        step: {
+            type: NumberConstructor;
+            default: number;
+        };
+        start: {
+            type: NumberConstructor;
+            default: number;
+        };
+        end: {
+            type: NumberConstructor;
+            default: number;
+        };
+    };
+    static actions: readonly ["onKeydown", "onPointerDown"];
+    static events: readonly ["change"];
+    readonly trackTarget: HTMLElement;
+    readonly startThumbTarget: HTMLElement;
+    readonly endThumbTarget: HTMLElement;
+    readonly hasTrackTarget: boolean;
+    readonly hasStartThumbTarget: boolean;
+    readonly hasEndThumbTarget: boolean;
+    minValue: number;
+    maxValue: number;
+    stepValue: number;
+    startValue: number;
+    endValue: number;
+    /** Normalizes the initial pair (clamped, snapped, ordered) and renders. */
+    connect(): void;
+    /** Cancels any active pointer drag so document listeners never leak. */
+    disconnect(): void;
+    /** Keyboard stepping for whichever thumb is focused (the action's element). */
+    onKeydown(event: KeyboardEvent): void;
+    /** Begins a pointer drag on the track, moving the thumb nearest the press. */
+    onPointerDown(event: PointerEvent): void;
+}
+
+export { RangeSliderController };

package/dist/controllers/range_slider_controller.js

@@ -0,0 +1,166 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/range_slider_controller.ts
+var START_PROPERTY = "--stimeo-range-start";
+var END_PROPERTY = "--stimeo-range-end";
+var RangeSliderController = class extends Controller {
+  static targets = ["track", "startThumb", "endThumb"];
+  static values = {
+    min: { type: Number, default: 0 },
+    max: { type: Number, default: 100 },
+    step: { type: Number, default: 1 },
+    start: { type: Number, default: 0 },
+    end: { type: Number, default: 100 }
+  };
+  static actions = ["onKeydown", "onPointerDown"];
+  static events = ["change"];
+  /** Aborts in-progress pointer-drag listeners when the drag ends or on teardown. */
+  #dragAbort = null;
+  /** Normalizes the initial pair (clamped, snapped, ordered) and renders. */
+  connect() {
+    const lo = Math.min(this.startValue, this.endValue);
+    const hi = Math.max(this.startValue, this.endValue);
+    this.#commit(lo, hi, false);
+  }
+  /** Cancels any active pointer drag so document listeners never leak. */
+  disconnect() {
+    this.#dragAbort?.abort();
+    this.#dragAbort = null;
+  }
+  /** Keyboard stepping for whichever thumb is focused (the action's element). */
+  onKeydown(event) {
+    const thumb = event.currentTarget;
+    const isStart = this.hasStartThumbTarget && thumb === this.startThumbTarget;
+    const current = isStart ? this.startValue : this.endValue;
+    const lower = isStart ? this.minValue : this.startValue;
+    const upper = isStart ? this.endValue : this.maxValue;
+    const big = this.stepValue * 10;
+    let next = null;
+    switch (event.key) {
+      case "ArrowRight":
+      case "ArrowUp":
+        next = current + this.stepValue;
+        break;
+      case "ArrowLeft":
+      case "ArrowDown":
+        next = current - this.stepValue;
+        break;
+      case "PageUp":
+        next = current + big;
+        break;
+      case "PageDown":
+        next = current - big;
+        break;
+      case "Home":
+        next = lower;
+        break;
+      case "End":
+        next = upper;
+        break;
+      default:
+        return;
+    }
+    event.preventDefault();
+    this.#moveThumb(isStart, next);
+  }
+  /** Begins a pointer drag on the track, moving the thumb nearest the press. */
+  onPointerDown(event) {
+    if (!this.hasTrackTarget) return;
+    const value = this.#valueFromClientX(event.clientX);
+    if (value === null) return;
+    event.preventDefault();
+    const useStart = Math.abs(value - this.startValue) <= Math.abs(value - this.endValue);
+    if (useStart) {
+      if (this.hasStartThumbTarget) this.startThumbTarget.focus();
+    } else if (this.hasEndThumbTarget) {
+      this.endThumbTarget.focus();
+    }
+    this.#moveThumb(useStart, value);
+    this.#dragAbort?.abort();
+    const abort = new AbortController();
+    this.#dragAbort = abort;
+    const onMove = (move) => {
+      const moved = this.#valueFromClientX(move.clientX);
+      if (moved !== null) this.#moveThumb(useStart, moved);
+    };
+    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 raw value using the track geometry. */
+  #valueFromClientX(clientX) {
+    const rect = this.trackTarget.getBoundingClientRect();
+    if (rect.width === 0) return null;
+    const fraction = (clientX - rect.left) / rect.width;
+    return this.minValue + fraction * (this.maxValue - this.minValue);
+  }
+  /** Moves one thumb to a new raw value, keeping the pair ordered. */
+  #moveThumb(isStart, raw) {
+    if (isStart) {
+      this.#commit(raw, this.endValue, true);
+    } else {
+      this.#commit(this.startValue, raw, true);
+    }
+  }
+  /**
+   * Clamps and snaps `start`/`end`, enforces `start ≤ end`, stores the pair, and
+   * reflects it onto the thumbs' ARIA attributes and the range custom
+   * properties. Dispatches `change` only on user-driven updates (`notify`).
+   */
+  #commit(start, end, notify) {
+    const prevStart = this.startValue;
+    const prevEnd = this.endValue;
+    let nextStart = this.#snap(start);
+    let nextEnd = this.#snap(end);
+    if (nextStart > nextEnd) {
+      if (isUserMovingStart(start, prevStart, end, prevEnd)) nextStart = nextEnd;
+      else nextEnd = nextStart;
+    }
+    this.startValue = nextStart;
+    this.endValue = nextEnd;
+    this.#render(nextStart, nextEnd);
+    if (notify && (nextStart !== prevStart || nextEnd !== prevEnd)) {
+      this.dispatch("change", { detail: { start: nextStart, end: nextEnd } });
+    }
+  }
+  /** Reflects the current pair onto thumb ARIA attributes and CSS properties. */
+  #render(start, end) {
+    if (this.hasStartThumbTarget) {
+      this.startThumbTarget.setAttribute("aria-valuemin", String(this.minValue));
+      this.startThumbTarget.setAttribute("aria-valuemax", String(end));
+      this.startThumbTarget.setAttribute("aria-valuenow", String(start));
+    }
+    if (this.hasEndThumbTarget) {
+      this.endThumbTarget.setAttribute("aria-valuemin", String(start));
+      this.endThumbTarget.setAttribute("aria-valuemax", String(this.maxValue));
+      this.endThumbTarget.setAttribute("aria-valuenow", String(end));
+    }
+    const span = this.maxValue - this.minValue;
+    this.element.style.setProperty(
+      START_PROPERTY,
+      String(span > 0 ? (start - this.minValue) / span : 0)
+    );
+    this.element.style.setProperty(
+      END_PROPERTY,
+      String(span > 0 ? (end - this.minValue) / span : 0)
+    );
+  }
+  /** Clamps `raw` to `[min, max]` and snaps it to the nearest step from `min`. */
+  #snap(raw) {
+    const clamped = Math.min(this.maxValue, Math.max(this.minValue, raw));
+    if (this.stepValue <= 0) return clamped;
+    const stepped = Math.round((clamped - this.minValue) / this.stepValue) * this.stepValue + this.minValue;
+    return Math.min(this.maxValue, Math.max(this.minValue, stepped));
+  }
+};
+function isUserMovingStart(start, prevStart, end, prevEnd) {
+  return start !== prevStart && end === prevEnd;
+}
+
+export { RangeSliderController };
+//# sourceMappingURL=range_slider_controller.js.map
+//# sourceMappingURL=range_slider_controller.js.map

package/dist/controllers/range_slider_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/controllers/range_slider_controller.ts"],"names":[],"mappings":"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","file":"range_slider_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\n\n/** CSS custom properties exposing each thumb's position (0..1) to the consumer. */\nconst START_PROPERTY = \"--stimeo-range-start\";\nconst END_PROPERTY = \"--stimeo-range-end\";\n\n/**\n * Headless, accessible **two-thumb range slider** behavior (APG Slider —\n * Multi-Thumb). A derivative of {@link SliderController}: it manages two thumbs\n * (`start` ≤ `end`) that constrain each other.\n *\n * Markup contract (identifier: `stimeo--range-slider`):\n *   <div data-controller=\"stimeo--range-slider\"\n *        data-stimeo--range-slider-min-value=\"0\"\n *        data-stimeo--range-slider-max-value=\"100\"\n *        data-stimeo--range-slider-step-value=\"1\"\n *        data-stimeo--range-slider-start-value=\"20\"\n *        data-stimeo--range-slider-end-value=\"80\">\n *     <div data-stimeo--range-slider-target=\"track\"\n *          data-action=\"pointerdown->stimeo--range-slider#onPointerDown\">\n *       <div role=\"slider\" tabindex=\"0\" aria-label=\"Minimum\"\n *            data-stimeo--range-slider-target=\"startThumb\"\n *            data-action=\"keydown->stimeo--range-slider#onKeydown\"></div>\n *       <div role=\"slider\" tabindex=\"0\" aria-label=\"Maximum\"\n *            data-stimeo--range-slider-target=\"endThumb\"\n *            data-action=\"keydown->stimeo--range-slider#onKeydown\"></div>\n *     </div>\n *   </div>\n *\n * @remarks\n * Behavior only — the consumer owns all layout (positioning the thumbs and the\n * selected range from the fractions). Only the horizontal orientation is handled\n * in this MVP. Each thumb's movable range is bounded by the *other* thumb's\n * current value, reflected on its `aria-valuemin`/`aria-valuemax` so assistive\n * tech announces the live constraint.\n *\n * Behavior provided (per focused thumb):\n * - `ArrowRight`/`ArrowUp` increase and `ArrowLeft`/`ArrowDown` decrease by one\n *   step; `Home`/`End` jump to that thumb's movable min/max; `PageUp`/`PageDown`\n *   move by ten steps. A thumb never crosses the other.\n * - Pointer press/drag on the track moves the nearest thumb.\n */\nexport class RangeSliderController extends Controller<HTMLElement> {\n  static override targets = [\"track\", \"startThumb\", \"endThumb\"];\n  static override values = {\n    min: { type: Number, default: 0 },\n    max: { type: Number, default: 100 },\n    step: { type: Number, default: 1 },\n    start: { type: Number, default: 0 },\n    end: { type: Number, default: 100 },\n  };\n  static actions = [\"onKeydown\", \"onPointerDown\"] as const;\n  static events = [\"change\"] as const;\n\n  declare readonly trackTarget: HTMLElement;\n  declare readonly startThumbTarget: HTMLElement;\n  declare readonly endThumbTarget: HTMLElement;\n  declare readonly hasTrackTarget: boolean;\n  declare readonly hasStartThumbTarget: boolean;\n  declare readonly hasEndThumbTarget: boolean;\n  declare minValue: number;\n  declare maxValue: number;\n  declare stepValue: number;\n  declare startValue: number;\n  declare endValue: number;\n\n  /** Aborts in-progress pointer-drag listeners when the drag ends or on teardown. */\n  #dragAbort: AbortController | null = null;\n\n  /** Normalizes the initial pair (clamped, snapped, ordered) and renders. */\n  override connect(): void {\n    // Order the initial pair up front so a reversed start/end is corrected by\n    // swapping (preserving both values) rather than collapsing one onto the other.\n    const lo = Math.min(this.startValue, this.endValue);\n    const hi = Math.max(this.startValue, this.endValue);\n    this.#commit(lo, hi, false);\n  }\n\n  /** Cancels any active pointer drag so document listeners never leak. */\n  override disconnect(): void {\n    this.#dragAbort?.abort();\n    this.#dragAbort = null;\n  }\n\n  /** Keyboard stepping for whichever thumb is focused (the action's element). */\n  onKeydown(event: KeyboardEvent): void {\n    const thumb = event.currentTarget as HTMLElement;\n    const isStart = this.hasStartThumbTarget && thumb === this.startThumbTarget;\n    const current = isStart ? this.startValue : this.endValue;\n    // The opposing thumb caps this one's travel so the two never cross.\n    const lower = isStart ? this.minValue : this.startValue;\n    const upper = isStart ? this.endValue : this.maxValue;\n    const big = this.stepValue * 10;\n\n    let next: number | null = null;\n    switch (event.key) {\n      case \"ArrowRight\":\n      case \"ArrowUp\":\n        next = current + this.stepValue;\n        break;\n      case \"ArrowLeft\":\n      case \"ArrowDown\":\n        next = current - this.stepValue;\n        break;\n      case \"PageUp\":\n        next = current + big;\n        break;\n      case \"PageDown\":\n        next = current - big;\n        break;\n      case \"Home\":\n        next = lower;\n        break;\n      case \"End\":\n        next = upper;\n        break;\n      default:\n        return;\n    }\n    event.preventDefault();\n    this.#moveThumb(isStart, next);\n  }\n\n  /** Begins a pointer drag on the track, moving the thumb nearest the press. */\n  onPointerDown(event: PointerEvent): void {\n    if (!this.hasTrackTarget) return;\n    const value = this.#valueFromClientX(event.clientX);\n    if (value === null) return;\n    event.preventDefault();\n\n    // Pick the nearer thumb; ties go to the start thumb so a press exactly\n    // between them stays deterministic. Only read the target getter behind its\n    // has*Target guard — Stimulus throws when an absent target is accessed.\n    const useStart = Math.abs(value - this.startValue) <= Math.abs(value - this.endValue);\n    if (useStart) {\n      if (this.hasStartThumbTarget) this.startThumbTarget.focus();\n    } else if (this.hasEndThumbTarget) {\n      this.endThumbTarget.focus();\n    }\n    this.#moveThumb(useStart, value);\n\n    this.#dragAbort?.abort();\n    const abort = new AbortController();\n    this.#dragAbort = abort;\n    const onMove = (move: PointerEvent): void => {\n      const moved = this.#valueFromClientX(move.clientX);\n      if (moved !== null) this.#moveThumb(useStart, moved);\n    };\n    const onUp = (): void => {\n      abort.abort();\n      this.#dragAbort = null;\n    };\n    document.addEventListener(\"pointermove\", onMove, { signal: abort.signal });\n    document.addEventListener(\"pointerup\", onUp, { signal: abort.signal });\n    // pointercancel fires when the gesture is interrupted (OS gesture, scroll\n    // takeover, device switch); clean up the same way so no listener leaks.\n    document.addEventListener(\"pointercancel\", onUp, { signal: abort.signal });\n  }\n\n  /** Maps a pointer X coordinate to a raw value using the track geometry. */\n  #valueFromClientX(clientX: number): number | null {\n    const rect = this.trackTarget.getBoundingClientRect();\n    if (rect.width === 0) return null;\n    const fraction = (clientX - rect.left) / rect.width;\n    return this.minValue + fraction * (this.maxValue - this.minValue);\n  }\n\n  /** Moves one thumb to a new raw value, keeping the pair ordered. */\n  #moveThumb(isStart: boolean, raw: number): void {\n    if (isStart) {\n      this.#commit(raw, this.endValue, true);\n    } else {\n      this.#commit(this.startValue, raw, true);\n    }\n  }\n\n  /**\n   * Clamps and snaps `start`/`end`, enforces `start ≤ end`, stores the pair, and\n   * reflects it onto the thumbs' ARIA attributes and the range custom\n   * properties. Dispatches `change` only on user-driven updates (`notify`).\n   */\n  #commit(start: number, end: number, notify: boolean): void {\n    const prevStart = this.startValue;\n    const prevEnd = this.endValue;\n\n    let nextStart = this.#snap(start);\n    let nextEnd = this.#snap(end);\n    // Keep them ordered: a thumb pushed past its partner stops at the partner.\n    if (nextStart > nextEnd) {\n      if (isUserMovingStart(start, prevStart, end, prevEnd)) nextStart = nextEnd;\n      else nextEnd = nextStart;\n    }\n\n    this.startValue = nextStart;\n    this.endValue = nextEnd;\n    this.#render(nextStart, nextEnd);\n\n    if (notify && (nextStart !== prevStart || nextEnd !== prevEnd)) {\n      this.dispatch(\"change\", { detail: { start: nextStart, end: nextEnd } });\n    }\n  }\n\n  /** Reflects the current pair onto thumb ARIA attributes and CSS properties. */\n  #render(start: number, end: number): void {\n    if (this.hasStartThumbTarget) {\n      this.startThumbTarget.setAttribute(\"aria-valuemin\", String(this.minValue));\n      this.startThumbTarget.setAttribute(\"aria-valuemax\", String(end));\n      this.startThumbTarget.setAttribute(\"aria-valuenow\", String(start));\n    }\n    if (this.hasEndThumbTarget) {\n      this.endThumbTarget.setAttribute(\"aria-valuemin\", String(start));\n      this.endThumbTarget.setAttribute(\"aria-valuemax\", String(this.maxValue));\n      this.endThumbTarget.setAttribute(\"aria-valuenow\", String(end));\n    }\n    const span = this.maxValue - this.minValue;\n    this.element.style.setProperty(\n      START_PROPERTY,\n      String(span > 0 ? (start - this.minValue) / span : 0),\n    );\n    this.element.style.setProperty(\n      END_PROPERTY,\n      String(span > 0 ? (end - this.minValue) / span : 0),\n    );\n  }\n\n  /** Clamps `raw` to `[min, max]` and snaps it to the nearest step from `min`. */\n  #snap(raw: number): number {\n    const clamped = Math.min(this.maxValue, Math.max(this.minValue, raw));\n    if (this.stepValue <= 0) return clamped;\n    const stepped =\n      Math.round((clamped - this.minValue) / this.stepValue) * this.stepValue + this.minValue;\n    return Math.min(this.maxValue, Math.max(this.minValue, stepped));\n  }\n}\n\n/**\n * Decides which thumb yields when a move would cross the pair. The moving thumb\n * is the one whose requested value differs from its previous value; it stops at\n * the partner rather than dragging the partner along.\n */\nfunction isUserMovingStart(\n  start: number,\n  prevStart: number,\n  end: number,\n  prevEnd: number,\n): boolean {\n  return start !== prevStart && end === prevEnd;\n}\n"]}

package/dist/controllers/read_more_controller.d.ts

@@ -0,0 +1,52 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless "read more / truncate" behavior for visually clamped text.
+ *
+ * Markup contract (identifier: `stimeo--read-more`):
+ *   <div data-controller="stimeo--read-more">
+ *     <p id="bio" data-stimeo--read-more-target="content" data-state="collapsed">…</p>
+ *     <button data-stimeo--read-more-target="trigger"
+ *             data-action="stimeo--read-more#toggle"
+ *             aria-expanded="false" aria-controls="bio" hidden>Read more</button>
+ *   </div>
+ *
+ * There is no dedicated APG widget; the toggle borrows the **Disclosure**
+ * convention (`aria-expanded`). The visual clamp itself (`-webkit-line-clamp`
+ * etc.) is the consumer's CSS, keyed off `data-state`.
+ *
+ * @remarks
+ * Behavior only. The full text always stays in the DOM — the clamp is purely
+ * visual, so assistive technology reads everything regardless of state; here
+ * `aria-expanded` therefore signals the *visual* expansion, not content hidden
+ * from AT. The controller's extra job is **overflow detection**: when the
+ * content is not actually clamped (it fits), the toggle is `hidden` so no
+ * pointless "read more" is offered. Resizes, content changes, and target
+ * replacement re-evaluate it; hiding a focused toggle waits until blur.
+ */
+declare class ReadMoreController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        collapsed: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+    };
+    static actions: readonly ["toggle"];
+    readonly contentTarget: HTMLElement;
+    readonly triggerTarget: HTMLElement;
+    readonly hasContentTarget: boolean;
+    readonly hasTriggerTarget: boolean;
+    collapsedValue: boolean;
+    connect(): void;
+    disconnect(): void;
+    contentTargetConnected(): void;
+    contentTargetDisconnected(): void;
+    triggerTargetConnected(): void;
+    triggerTargetDisconnected(trigger: HTMLElement): void;
+    /** Toggles between the collapsed (clamped) and expanded states. */
+    toggle(): void;
+}
+
+export { ReadMoreController };