stimeo-ui 0.1.0-alpha.1

package/dist/controllers/input_mask_controller.d.ts

@@ -0,0 +1,74 @@
+import { Controller } from '@hotwired/stimulus';
+
+/** The outcome of applying a fixed mask to a raw string. */
+interface MaskResult {
+    /** The formatted (masked) string. */
+    readonly masked: string;
+    /** The significant characters only (literals/separators removed). */
+    readonly unmasked: string;
+    /** Whether every token slot in the pattern is filled. */
+    readonly complete: boolean;
+    /** Per-output-char flag: true where the char fills a token (not a literal). */
+    readonly tokenFlags: readonly boolean[];
+}
+/**
+ * Applies a fixed mask `pattern` to `value` using `tokens` (placeholder → regex).
+ * Non-matching input characters are rejected (skipped); literals are auto-inserted
+ * and a typed literal that matches is consumed. Pure and exported for direct testing.
+ */
+declare function applyMask(value: string, pattern: string, tokens: ReadonlyMap<string, RegExp>): MaskResult;
+/**
+ * Headless **input mask** — formats a field in place against a fixed pattern
+ * (`9`=digit, `a`=letter, `*`=alphanumeric, others literal), preserving the caret,
+ * rejecting invalid characters, and syncing the raw value to a hidden field. No
+ * dedicated APG pattern; Currency Input owns money-specific formatting.
+ *
+ * Markup contract (identifier: `stimeo--input-mask`, on the `<input>`):
+ *   <input type="text" inputmode="numeric"
+ *          data-controller="stimeo--input-mask"
+ *          data-stimeo--input-mask-pattern-value="999-9999"
+ *          data-action="input->stimeo--input-mask#format">
+ *   <input type="hidden" name="zip" data-stimeo--input-mask-unmask>
+ *
+ * @remarks
+ * Behavior only and **idempotent** — the formatted value lives only in the input and
+ * the hidden field (no module-scope state), so `connect()` re-formats the existing
+ * value and is stable across Turbo restore/morph. The controller sits on the
+ * `<input>` itself (a void element), so the raw-value sink is not a Stimulus target;
+ * it is the `[data-stimeo--input-mask-unmask]` field resolved nearest-first within
+ * the same form (an explicit pairing by the sink attribute's value naming the
+ * input's `id` wins; otherwise the closest ancestor's value-less sink) — when one
+ * form holds several masked inputs, wrap each input+sink pair in a container or
+ * pair them by `id`. Formatting never steals keys: it rejects disallowed characters
+ * silently and keeps the caret on insert, Backspace, and range replacement
+ * (WCAG 2.2 3.3.2 / 1.3.5; the expected format is the consumer's `aria-describedby`).
+ * It reflects `data-mask-complete` / `data-mask-empty` and dispatches
+ * `stimeo--input-mask:change` only when the value actually changes.
+ */
+declare class InputMaskController extends Controller<HTMLInputElement> {
+    #private;
+    static values: {
+        pattern: {
+            type: StringConstructor;
+            default: string;
+        };
+        tokens: {
+            type: ObjectConstructor;
+            default: {};
+        };
+        unmaskToHidden: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+    };
+    static actions: readonly ["format"];
+    static events: readonly ["change"];
+    patternValue: string;
+    tokensValue: Record<string, string>;
+    unmaskToHiddenValue: boolean;
+    connect(): void;
+    /** Formats the field on input, preserving the caret. Bound via `data-action`. */
+    format(): void;
+}
+
+export { InputMaskController, type MaskResult, applyMask };

package/dist/controllers/input_mask_controller.js

@@ -0,0 +1,166 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/input_mask_controller.ts
+var DEFAULT_TOKENS = {
+  "9": "\\d",
+  a: "[A-Za-z]",
+  "*": "[A-Za-z0-9]"
+};
+var UNMASK_ATTR = "data-stimeo--input-mask-unmask";
+function applyMask(value, pattern, tokens) {
+  let masked = "";
+  let unmasked = "";
+  const tokenFlags = [];
+  let valueIndex = 0;
+  let totalTokens = 0;
+  for (const patternChar of pattern) {
+    const regex = tokens.get(patternChar);
+    if (regex) totalTokens += 1;
+    if (valueIndex >= value.length) continue;
+    if (regex) {
+      while (valueIndex < value.length && !regex.test(value[valueIndex] ?? "")) valueIndex += 1;
+      const char = value[valueIndex];
+      if (char === void 0) continue;
+      masked += char;
+      unmasked += char;
+      tokenFlags.push(true);
+      valueIndex += 1;
+    } else {
+      masked += patternChar;
+      tokenFlags.push(false);
+      if (value[valueIndex] === patternChar) valueIndex += 1;
+    }
+  }
+  return {
+    masked,
+    unmasked,
+    complete: totalTokens > 0 && unmasked.length === totalTokens,
+    tokenFlags
+  };
+}
+var InputMaskController = class extends Controller {
+  static values = {
+    pattern: { type: String, default: "" },
+    tokens: { type: Object, default: {} },
+    unmaskToHidden: { type: Boolean, default: true }
+  };
+  static actions = ["format"];
+  static events = ["change"];
+  connect() {
+    this.#apply();
+  }
+  /** Formats the field on input, preserving the caret. Bound via `data-action`. */
+  format() {
+    this.#apply();
+  }
+  /** Core reformat: mask the current value, restore the caret, sync, and announce. */
+  #apply() {
+    if (!this.patternValue) return;
+    const input = this.element;
+    const previous = input.value;
+    const caret = input.selectionStart ?? previous.length;
+    const tokens = this.#tokenRegexes();
+    const significant = this.#countSignificant(previous.slice(0, caret), tokens);
+    const result = applyMask(previous, this.patternValue, tokens);
+    input.value = result.masked;
+    this.#restoreCaret(input, result.tokenFlags, significant);
+    if (this.unmaskToHiddenValue) {
+      const unmask = this.#unmaskField();
+      if (unmask) unmask.value = result.unmasked;
+    }
+    this.#flag("data-mask-complete", result.complete);
+    this.#flag("data-mask-empty", result.masked.length === 0);
+    if (result.masked !== previous) {
+      this.dispatch("change", {
+        detail: { masked: result.masked, unmasked: result.unmasked, complete: result.complete }
+      });
+    }
+  }
+  /** Places the caret after the `n`-th token char (skipping following literals). */
+  #restoreCaret(input, tokenFlags, n) {
+    let position;
+    if (n <= 0) {
+      let i = 0;
+      while (i < tokenFlags.length && !tokenFlags[i]) i += 1;
+      position = i;
+    } else {
+      let seen = 0;
+      position = tokenFlags.length;
+      for (let i = 0; i < tokenFlags.length; i += 1) {
+        if (!tokenFlags[i]) continue;
+        seen += 1;
+        if (seen === n) {
+          let j = i + 1;
+          while (j < tokenFlags.length && !tokenFlags[j]) j += 1;
+          position = j;
+          break;
+        }
+      }
+    }
+    try {
+      input.setSelectionRange(position, position);
+    } catch {
+    }
+  }
+  /**
+   * The hidden raw-value sink for this input, resolved so several masked inputs
+   * can coexist in one form:
+   *
+   * 1. **Explicit pairing** — a sink whose attribute value names this input's
+   *    `id` (`data-stimeo--input-mask-unmask="zip"`), looked up across the form
+   *    (or the document when the input is form-less).
+   * 2. **Nearest container** — otherwise, walking up from the input (stopping at
+   *    the form boundary), the first *value-less* sink in the closest ancestor.
+   *    Wrapped input+sink pairs each find their own sink, and the single
+   *    form-level sink keeps working unchanged. A sink claimed by another
+   *    input's id is never matched here.
+   */
+  #unmaskField() {
+    const id = this.element.id;
+    if (id.length > 0) {
+      const scope = this.element.form ?? document;
+      const quoted = id.replace(/["\\]/g, "\\$&");
+      const paired = scope.querySelector(`input[${UNMASK_ATTR}="${quoted}"]`);
+      if (paired) return paired;
+    }
+    for (let node = this.element.parentElement; node !== null; node = node.parentElement) {
+      const sink = node.querySelector(`input[${UNMASK_ATTR}=""]`);
+      if (sink) return sink;
+      if (node === this.element.form) break;
+    }
+    return null;
+  }
+  /** Counts characters in `text` that fill any token (the caret-significant chars). */
+  #countSignificant(text, tokens) {
+    let count = 0;
+    for (const char of text) {
+      for (const regex of tokens.values()) {
+        if (regex.test(char)) {
+          count += 1;
+          break;
+        }
+      }
+    }
+    return count;
+  }
+  /** Compiles the effective token map (defaults with the user `tokens` merged over). */
+  #tokenRegexes() {
+    const map = /* @__PURE__ */ new Map();
+    for (const [key, source] of Object.entries({ ...DEFAULT_TOKENS, ...this.tokensValue })) {
+      try {
+        map.set(key, new RegExp(`^(?:${source})$`));
+      } catch {
+      }
+    }
+    return map;
+  }
+  /** Sets a boolean `data-*` flag to `"true"` when `on`, else removes it. */
+  #flag(name, on) {
+    if (on) this.element.setAttribute(name, "true");
+    else this.element.removeAttribute(name);
+  }
+};
+
+export { InputMaskController, applyMask };
+//# sourceMappingURL=input_mask_controller.js.map
+//# sourceMappingURL=input_mask_controller.js.map

package/dist/controllers/input_mask_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/controllers/input_mask_controller.ts"],"names":[],"mappings":"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","file":"input_mask_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\n\n/** Default placeholder tokens → single-char regex sources (user tokens merge over these). */\nconst DEFAULT_TOKENS: Readonly<Record<string, string>> = {\n  \"9\": \"\\\\d\",\n  a: \"[A-Za-z]\",\n  \"*\": \"[A-Za-z0-9]\",\n};\n\n/** Attribute marking the hidden raw-value sink; its value may name the paired input's `id`. */\nconst UNMASK_ATTR = \"data-stimeo--input-mask-unmask\";\n\n/** The outcome of applying a fixed mask to a raw string. */\nexport interface MaskResult {\n  /** The formatted (masked) string. */\n  readonly masked: string;\n  /** The significant characters only (literals/separators removed). */\n  readonly unmasked: string;\n  /** Whether every token slot in the pattern is filled. */\n  readonly complete: boolean;\n  /** Per-output-char flag: true where the char fills a token (not a literal). */\n  readonly tokenFlags: readonly boolean[];\n}\n\n/**\n * Applies a fixed mask `pattern` to `value` using `tokens` (placeholder → regex).\n * Non-matching input characters are rejected (skipped); literals are auto-inserted\n * and a typed literal that matches is consumed. Pure and exported for direct testing.\n */\nexport function applyMask(\n  value: string,\n  pattern: string,\n  tokens: ReadonlyMap<string, RegExp>,\n): MaskResult {\n  let masked = \"\";\n  let unmasked = \"\";\n  const tokenFlags: boolean[] = [];\n  let valueIndex = 0;\n  let totalTokens = 0;\n\n  for (const patternChar of pattern) {\n    const regex = tokens.get(patternChar);\n    if (regex) totalTokens += 1;\n    if (valueIndex >= value.length) continue;\n\n    if (regex) {\n      // Skip rejected characters until one matches this token (or input runs out).\n      while (valueIndex < value.length && !regex.test(value[valueIndex] ?? \"\")) valueIndex += 1;\n      const char = value[valueIndex];\n      if (char === undefined) continue;\n      masked += char;\n      unmasked += char;\n      tokenFlags.push(true);\n      valueIndex += 1;\n    } else {\n      masked += patternChar;\n      tokenFlags.push(false);\n      if (value[valueIndex] === patternChar) valueIndex += 1;\n    }\n  }\n\n  return {\n    masked,\n    unmasked,\n    complete: totalTokens > 0 && unmasked.length === totalTokens,\n    tokenFlags,\n  };\n}\n\n/**\n * Headless **input mask** — formats a field in place against a fixed pattern\n * (`9`=digit, `a`=letter, `*`=alphanumeric, others literal), preserving the caret,\n * rejecting invalid characters, and syncing the raw value to a hidden field. No\n * dedicated APG pattern; Currency Input owns money-specific formatting.\n *\n * Markup contract (identifier: `stimeo--input-mask`, on the `<input>`):\n *   <input type=\"text\" inputmode=\"numeric\"\n *          data-controller=\"stimeo--input-mask\"\n *          data-stimeo--input-mask-pattern-value=\"999-9999\"\n *          data-action=\"input->stimeo--input-mask#format\">\n *   <input type=\"hidden\" name=\"zip\" data-stimeo--input-mask-unmask>\n *\n * @remarks\n * Behavior only and **idempotent** — the formatted value lives only in the input and\n * the hidden field (no module-scope state), so `connect()` re-formats the existing\n * value and is stable across Turbo restore/morph. The controller sits on the\n * `<input>` itself (a void element), so the raw-value sink is not a Stimulus target;\n * it is the `[data-stimeo--input-mask-unmask]` field resolved nearest-first within\n * the same form (an explicit pairing by the sink attribute's value naming the\n * input's `id` wins; otherwise the closest ancestor's value-less sink) — when one\n * form holds several masked inputs, wrap each input+sink pair in a container or\n * pair them by `id`. Formatting never steals keys: it rejects disallowed characters\n * silently and keeps the caret on insert, Backspace, and range replacement\n * (WCAG 2.2 3.3.2 / 1.3.5; the expected format is the consumer's `aria-describedby`).\n * It reflects `data-mask-complete` / `data-mask-empty` and dispatches\n * `stimeo--input-mask:change` only when the value actually changes.\n */\nexport class InputMaskController extends Controller<HTMLInputElement> {\n  static override values = {\n    pattern: { type: String, default: \"\" },\n    tokens: { type: Object, default: {} },\n    unmaskToHidden: { type: Boolean, default: true },\n  };\n  static actions = [\"format\"] as const;\n  static events = [\"change\"] as const;\n\n  declare patternValue: string;\n  declare tokensValue: Record<string, string>;\n  declare unmaskToHiddenValue: boolean;\n\n  override connect(): void {\n    // Re-format any server-rendered/restored value so the field is consistent.\n    this.#apply();\n  }\n\n  /** Formats the field on input, preserving the caret. Bound via `data-action`. */\n  format(): void {\n    this.#apply();\n  }\n\n  /** Core reformat: mask the current value, restore the caret, sync, and announce. */\n  #apply(): void {\n    // No pattern → act as a pass-through. Without this guard `applyMask` would\n    // produce an empty string and blank a misconfigured field's value.\n    if (!this.patternValue) return;\n\n    const input = this.element;\n    const previous = input.value;\n    const caret = input.selectionStart ?? previous.length;\n    const tokens = this.#tokenRegexes();\n\n    const significant = this.#countSignificant(previous.slice(0, caret), tokens);\n    const result = applyMask(previous, this.patternValue, tokens);\n\n    input.value = result.masked;\n    this.#restoreCaret(input, result.tokenFlags, significant);\n\n    if (this.unmaskToHiddenValue) {\n      const unmask = this.#unmaskField();\n      if (unmask) unmask.value = result.unmasked;\n    }\n    this.#flag(\"data-mask-complete\", result.complete);\n    this.#flag(\"data-mask-empty\", result.masked.length === 0);\n\n    if (result.masked !== previous) {\n      this.dispatch(\"change\", {\n        detail: { masked: result.masked, unmasked: result.unmasked, complete: result.complete },\n      });\n    }\n  }\n\n  /** Places the caret after the `n`-th token char (skipping following literals). */\n  #restoreCaret(input: HTMLInputElement, tokenFlags: readonly boolean[], n: number): void {\n    let position: number;\n    if (n <= 0) {\n      // Sit after any leading literals, before the first token slot.\n      let i = 0;\n      while (i < tokenFlags.length && !tokenFlags[i]) i += 1;\n      position = i;\n    } else {\n      let seen = 0;\n      position = tokenFlags.length;\n      for (let i = 0; i < tokenFlags.length; i += 1) {\n        if (!tokenFlags[i]) continue;\n        seen += 1;\n        if (seen === n) {\n          let j = i + 1;\n          while (j < tokenFlags.length && !tokenFlags[j]) j += 1;\n          position = j;\n          break;\n        }\n      }\n    }\n    try {\n      input.setSelectionRange(position, position);\n    } catch {\n      /* selection unsupported for this input type — value formatting still applies */\n    }\n  }\n\n  /**\n   * The hidden raw-value sink for this input, resolved so several masked inputs\n   * can coexist in one form:\n   *\n   * 1. **Explicit pairing** — a sink whose attribute value names this input's\n   *    `id` (`data-stimeo--input-mask-unmask=\"zip\"`), looked up across the form\n   *    (or the document when the input is form-less).\n   * 2. **Nearest container** — otherwise, walking up from the input (stopping at\n   *    the form boundary), the first *value-less* sink in the closest ancestor.\n   *    Wrapped input+sink pairs each find their own sink, and the single\n   *    form-level sink keeps working unchanged. A sink claimed by another\n   *    input's id is never matched here.\n   */\n  #unmaskField(): HTMLInputElement | null {\n    // Runs on every keystroke (via format → #apply), so each step is a single\n    // engine-side `querySelector` scoped to `input` — no candidate loops in JS.\n    const id = this.element.id;\n    if (id.length > 0) {\n      const scope: ParentNode = this.element.form ?? document;\n      // Escape `\"` / `\\` so an authored id cannot break out of the quoted selector.\n      const quoted = id.replace(/[\"\\\\]/g, \"\\\\$&\");\n      const paired = scope.querySelector<HTMLInputElement>(`input[${UNMASK_ATTR}=\"${quoted}\"]`);\n      if (paired) return paired;\n    }\n    // `[attr=\"\"]` matches bare (value-less) attributes, so a sink naming another\n    // input's id can never be claimed by this fallback.\n    for (let node = this.element.parentElement; node !== null; node = node.parentElement) {\n      const sink = node.querySelector<HTMLInputElement>(`input[${UNMASK_ATTR}=\"\"]`);\n      if (sink) return sink;\n      if (node === this.element.form) break;\n    }\n    return null;\n  }\n\n  /** Counts characters in `text` that fill any token (the caret-significant chars). */\n  #countSignificant(text: string, tokens: ReadonlyMap<string, RegExp>): number {\n    let count = 0;\n    for (const char of text) {\n      for (const regex of tokens.values()) {\n        if (regex.test(char)) {\n          count += 1;\n          break;\n        }\n      }\n    }\n    return count;\n  }\n\n  /** Compiles the effective token map (defaults with the user `tokens` merged over). */\n  #tokenRegexes(): Map<string, RegExp> {\n    const map = new Map<string, RegExp>();\n    for (const [key, source] of Object.entries({ ...DEFAULT_TOKENS, ...this.tokensValue })) {\n      try {\n        map.set(key, new RegExp(`^(?:${source})$`));\n      } catch {\n        /* skip an invalid token regex rather than breaking the whole mask */\n      }\n    }\n    return map;\n  }\n\n  /** Sets a boolean `data-*` flag to `\"true\"` when `on`, else removes it. */\n  #flag(name: string, on: boolean): void {\n    if (on) this.element.setAttribute(name, \"true\");\n    else this.element.removeAttribute(name);\n  }\n}\n"]}

package/dist/controllers/lazy_frame_controller.d.ts

@@ -0,0 +1,53 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless **lazy frame**: defers a `<turbo-frame>`'s load until it nears the viewport
+ * (or focus reaches it), to keep the initial render light. Turbo's own `loading="lazy"`
+ * fires on *render*, not on viewport entry, so this drives an explicit `IntersectionObserver`
+ * with a configurable `rootMargin` for early loading, plus a focus fallback so keyboard /
+ * assistive-tech users trigger the load too (no APG pattern).
+ *
+ * Markup contract (identifier: `stimeo--lazy-frame`):
+ *   <turbo-frame id="comments" data-controller="stimeo--lazy-frame"
+ *     data-stimeo--lazy-frame-url-value="/posts/1/comments"
+ *     data-stimeo--lazy-frame-root-margin-value="200px">Loading…</turbo-frame>
+ *
+ * The URL is *held* in the `url` value (not on `src`) so Turbo does not load it eagerly;
+ * when the frame intersects (within `rootMargin`) or focus enters it, the controller
+ * writes `url` to `src` — which starts the Turbo load — marks `data-lazy-loaded`, and
+ * emits `load`. With `once` (default) it then stops observing; otherwise re-entry asks
+ * Turbo to `reload()` the frame.
+ *
+ * @remarks
+ * Behavior only — the load itself and the frame's content are Turbo's / the server's job,
+ * and the loading UI (skeleton / `aria-busy`) belongs to Frame Loading State. The trigger
+ * is idempotent (`data-lazy-loaded` guards a double load and is honored on a Turbo cache
+ * restore — a frame that already loaded is not observed again). The `IntersectionObserver`
+ * and focus listener are released once loaded (when `once`) and on `disconnect()` (Turbo
+ * navigation included).
+ */
+declare class LazyFrameController extends Controller<HTMLElement> {
+    #private;
+    static values: {
+        url: {
+            type: StringConstructor;
+            default: string;
+        };
+        rootMargin: {
+            type: StringConstructor;
+            default: string;
+        };
+        once: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+    };
+    static events: readonly ["load"];
+    urlValue: string;
+    rootMarginValue: string;
+    onceValue: boolean;
+    connect(): void;
+    disconnect(): void;
+}
+
+export { LazyFrameController };

package/dist/controllers/lazy_frame_controller.js

@@ -0,0 +1,68 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/lazy_frame_controller.ts
+var LazyFrameController = class extends Controller {
+  static values = {
+    url: { type: String, default: "" },
+    rootMargin: { type: String, default: "0px" },
+    once: { type: Boolean, default: true }
+  };
+  static events = ["load"];
+  #observer = null;
+  #loaded = false;
+  /** Focus reaching the frame triggers the load before it intersects (keyboard / AT). */
+  #onFocus = () => this.#trigger();
+  connect() {
+    if (this.element.hasAttribute("data-lazy-loaded")) {
+      this.#loaded = true;
+      return;
+    }
+    if (!this.urlValue) return;
+    this.element.addEventListener("focusin", this.#onFocus);
+    if (typeof IntersectionObserver !== "undefined") {
+      this.#observer = new IntersectionObserver((entries) => this.#onIntersect(entries), {
+        rootMargin: this.rootMarginValue
+      });
+      this.#observer.observe(this.element);
+    }
+  }
+  disconnect() {
+    this.#stopObserving();
+  }
+  #onIntersect(entries) {
+    for (const entry of entries) {
+      if (entry.isIntersecting) {
+        this.#trigger();
+        return;
+      }
+    }
+  }
+  #trigger() {
+    if (!this.#loaded) this.#load();
+    else if (!this.onceValue) this.#reload();
+  }
+  /** Starts the load by writing the held URL to `src`. */
+  #load() {
+    this.#loaded = true;
+    this.element.setAttribute("src", this.urlValue);
+    this.element.setAttribute("data-lazy-loaded", "true");
+    this.dispatch("load", { detail: { url: this.urlValue } });
+    if (this.onceValue) this.#stopObserving();
+  }
+  /** Re-entry while `once` is off: ask Turbo to reload the frame's current `src`. */
+  #reload() {
+    const frame = this.element;
+    if (typeof frame.reload !== "function") return;
+    frame.reload();
+    this.dispatch("load", { detail: { url: this.urlValue } });
+  }
+  #stopObserving() {
+    this.#observer?.disconnect();
+    this.#observer = null;
+    this.element.removeEventListener("focusin", this.#onFocus);
+  }
+};
+
+export { LazyFrameController };
+//# sourceMappingURL=lazy_frame_controller.js.map
+//# sourceMappingURL=lazy_frame_controller.js.map

package/dist/controllers/lazy_frame_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/controllers/lazy_frame_controller.ts"],"names":[],"mappings":";;;AA4BO,IAAM,mBAAA,GAAN,cAAkC,UAAA,CAAwB;AAAA,EAC/D,OAAgB,MAAA,GAAS;AAAA,IACvB,GAAA,EAAK,EAAE,IAAA,EAAM,MAAA,EAAQ,SAAS,EAAA,EAAG;AAAA,IACjC,UAAA,EAAY,EAAE,IAAA,EAAM,MAAA,EAAQ,SAAS,KAAA,EAAM;AAAA,IAC3C,IAAA,EAAM,EAAE,IAAA,EAAM,OAAA,EAAS,SAAS,IAAA;AAAK,GACvC;AAAA,EACA,OAAO,MAAA,GAAS,CAAC,MAAM,CAAA;AAAA,EAMvB,SAAA,GAAyC,IAAA;AAAA,EACzC,OAAA,GAAU,KAAA;AAAA;AAAA,EAGD,QAAA,GAAW,MAAY,IAAA,CAAK,QAAA,EAAS;AAAA,EAErC,OAAA,GAAgB;AAEvB,IAAA,IAAI,IAAA,CAAK,OAAA,CAAQ,YAAA,CAAa,kBAAkB,CAAA,EAAG;AACjD,MAAA,IAAA,CAAK,OAAA,GAAU,IAAA;AACf,MAAA;AAAA,IACF;AACA,IAAA,IAAI,CAAC,KAAK,QAAA,EAAU;AAEpB,IAAA,IAAA,CAAK,OAAA,CAAQ,gBAAA,CAAiB,SAAA,EAAW,IAAA,CAAK,QAAQ,CAAA;AACtD,IAAA,IAAI,OAAO,yBAAyB,WAAA,EAAa;AAC/C,MAAA,IAAA,CAAK,SAAA,GAAY,IAAI,oBAAA,CAAqB,CAAC,YAAY,IAAA,CAAK,YAAA,CAAa,OAAO,CAAA,EAAG;AAAA,QACjF,YAAY,IAAA,CAAK;AAAA,OAClB,CAAA;AACD,MAAA,IAAA,CAAK,SAAA,CAAU,OAAA,CAAQ,IAAA,CAAK,OAAO,CAAA;AAAA,IACrC;AAAA,EACF;AAAA,EAES,UAAA,GAAmB;AAC1B,IAAA,IAAA,CAAK,cAAA,EAAe;AAAA,EACtB;AAAA,EAEA,aAAa,OAAA,EAA4C;AACvD,IAAA,KAAA,MAAW,SAAS,OAAA,EAAS;AAC3B,MAAA,IAAI,MAAM,cAAA,EAAgB;AACxB,QAAA,IAAA,CAAK,QAAA,EAAS;AACd,QAAA;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAAA,EAEA,QAAA,GAAiB;AACf,IAAA,IAAI,CAAC,IAAA,CAAK,OAAA,EAAS,IAAA,CAAK,KAAA,EAAM;AAAA,SAAA,IACrB,CAAC,IAAA,CAAK,SAAA,EAAW,IAAA,CAAK,OAAA,EAAQ;AAAA,EACzC;AAAA;AAAA,EAGA,KAAA,GAAc;AACZ,IAAA,IAAA,CAAK,OAAA,GAAU,IAAA;AACf,IAAA,IAAA,CAAK,OAAA,CAAQ,YAAA,CAAa,KAAA,EAAO,IAAA,CAAK,QAAQ,CAAA;AAC9C,IAAA,IAAA,CAAK,OAAA,CAAQ,YAAA,CAAa,kBAAA,EAAoB,MAAM,CAAA;AACpD,IAAA,IAAA,CAAK,QAAA,CAAS,QAAQ,EAAE,MAAA,EAAQ,EAAE,GAAA,EAAK,IAAA,CAAK,QAAA,EAAS,EAAG,CAAA;AACxD,IAAA,IAAI,IAAA,CAAK,SAAA,EAAW,IAAA,CAAK,cAAA,EAAe;AAAA,EAC1C;AAAA;AAAA,EAGA,OAAA,GAAgB;AACd,IAAA,MAAM,QAAQ,IAAA,CAAK,OAAA;AAGnB,IAAA,IAAI,OAAO,KAAA,CAAM,MAAA,KAAW,UAAA,EAAY;AACxC,IAAA,KAAA,CAAM,MAAA,EAAO;AACb,IAAA,IAAA,CAAK,QAAA,CAAS,QAAQ,EAAE,MAAA,EAAQ,EAAE,GAAA,EAAK,IAAA,CAAK,QAAA,EAAS,EAAG,CAAA;AAAA,EAC1D;AAAA,EAEA,cAAA,GAAuB;AACrB,IAAA,IAAA,CAAK,WAAW,UAAA,EAAW;AAC3B,IAAA,IAAA,CAAK,SAAA,GAAY,IAAA;AACjB,IAAA,IAAA,CAAK,OAAA,CAAQ,mBAAA,CAAoB,SAAA,EAAW,IAAA,CAAK,QAAQ,CAAA;AAAA,EAC3D;AACF","file":"lazy_frame_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\n\n/**\n * Headless **lazy frame**: defers a `<turbo-frame>`'s load until it nears the viewport\n * (or focus reaches it), to keep the initial render light. Turbo's own `loading=\"lazy\"`\n * fires on *render*, not on viewport entry, so this drives an explicit `IntersectionObserver`\n * with a configurable `rootMargin` for early loading, plus a focus fallback so keyboard /\n * assistive-tech users trigger the load too (no APG pattern).\n *\n * Markup contract (identifier: `stimeo--lazy-frame`):\n *   <turbo-frame id=\"comments\" data-controller=\"stimeo--lazy-frame\"\n *     data-stimeo--lazy-frame-url-value=\"/posts/1/comments\"\n *     data-stimeo--lazy-frame-root-margin-value=\"200px\">Loading…</turbo-frame>\n *\n * The URL is *held* in the `url` value (not on `src`) so Turbo does not load it eagerly;\n * when the frame intersects (within `rootMargin`) or focus enters it, the controller\n * writes `url` to `src` — which starts the Turbo load — marks `data-lazy-loaded`, and\n * emits `load`. With `once` (default) it then stops observing; otherwise re-entry asks\n * Turbo to `reload()` the frame.\n *\n * @remarks\n * Behavior only — the load itself and the frame's content are Turbo's / the server's job,\n * and the loading UI (skeleton / `aria-busy`) belongs to Frame Loading State. The trigger\n * is idempotent (`data-lazy-loaded` guards a double load and is honored on a Turbo cache\n * restore — a frame that already loaded is not observed again). The `IntersectionObserver`\n * and focus listener are released once loaded (when `once`) and on `disconnect()` (Turbo\n * navigation included).\n */\nexport class LazyFrameController extends Controller<HTMLElement> {\n  static override values = {\n    url: { type: String, default: \"\" },\n    rootMargin: { type: String, default: \"0px\" },\n    once: { type: Boolean, default: true },\n  };\n  static events = [\"load\"] as const;\n\n  declare urlValue: string;\n  declare rootMarginValue: string;\n  declare onceValue: boolean;\n\n  #observer: IntersectionObserver | null = null;\n  #loaded = false;\n\n  /** Focus reaching the frame triggers the load before it intersects (keyboard / AT). */\n  readonly #onFocus = (): void => this.#trigger();\n\n  override connect(): void {\n    // A cache restore may bring back an already-loaded frame; respect it, do not reload.\n    if (this.element.hasAttribute(\"data-lazy-loaded\")) {\n      this.#loaded = true;\n      return;\n    }\n    if (!this.urlValue) return;\n\n    this.element.addEventListener(\"focusin\", this.#onFocus);\n    if (typeof IntersectionObserver !== \"undefined\") {\n      this.#observer = new IntersectionObserver((entries) => this.#onIntersect(entries), {\n        rootMargin: this.rootMarginValue,\n      });\n      this.#observer.observe(this.element);\n    }\n  }\n\n  override disconnect(): void {\n    this.#stopObserving();\n  }\n\n  #onIntersect(entries: IntersectionObserverEntry[]): void {\n    for (const entry of entries) {\n      if (entry.isIntersecting) {\n        this.#trigger();\n        return;\n      }\n    }\n  }\n\n  #trigger(): void {\n    if (!this.#loaded) this.#load();\n    else if (!this.onceValue) this.#reload();\n  }\n\n  /** Starts the load by writing the held URL to `src`. */\n  #load(): void {\n    this.#loaded = true;\n    this.element.setAttribute(\"src\", this.urlValue);\n    this.element.setAttribute(\"data-lazy-loaded\", \"true\");\n    this.dispatch(\"load\", { detail: { url: this.urlValue } });\n    if (this.onceValue) this.#stopObserving();\n  }\n\n  /** Re-entry while `once` is off: ask Turbo to reload the frame's current `src`. */\n  #reload(): void {\n    const frame = this.element as HTMLElement & { reload?: () => void };\n    // Only signal `load` when a reload actually happens. On a non-`<turbo-frame>`\n    // host (no `reload()`), firing it would announce a load that never occurred.\n    if (typeof frame.reload !== \"function\") return;\n    frame.reload();\n    this.dispatch(\"load\", { detail: { url: this.urlValue } });\n  }\n\n  #stopObserving(): void {\n    this.#observer?.disconnect();\n    this.#observer = null;\n    this.element.removeEventListener(\"focusin\", this.#onFocus);\n  }\n}\n"]}

package/dist/controllers/listbox_controller.d.ts

@@ -0,0 +1,88 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless, accessible select-only listbox behavior.
+ *
+ * Markup contract (identifier: `stimeo--listbox`):
+ *   <div data-controller="stimeo--listbox">
+ *     <span id="lb-label">Favorite fruit</span>
+ *     <button type="button" role="combobox" aria-haspopup="listbox"
+ *             aria-expanded="false" aria-controls="lb-list" aria-activedescendant=""
+ *             aria-labelledby="lb-label lb-value"
+ *             data-stimeo--listbox-target="trigger"
+ *             data-action="click->stimeo--listbox#toggle
+ *                          keydown->stimeo--listbox#onTriggerKeydown">
+ *       <span id="lb-value" data-stimeo--listbox-target="value">Choose…</span>
+ *     </button>
+ *     <ul id="lb-list" role="listbox" aria-label="Options" hidden
+ *         data-stimeo--listbox-target="list">
+ *       <li id="opt-1" role="option" aria-selected="false" data-value="1"
+ *           data-stimeo--listbox-target="option"
+ *           data-action="click->stimeo--listbox#select">Option 1</li>
+ *       <!-- more options -->
+ *     </ul>
+ *     <input type="hidden" data-stimeo--listbox-target="field" />
+ *   </div>
+ *
+ * Implements the WAI-ARIA APG **Listbox** pattern in its collapsed
+ * (Select-Only Combobox) form. Focus stays on the trigger; the active option is
+ * tracked with `aria-activedescendant` rather than by moving DOM focus. For a
+ * text-filtered popup use {@link ComboboxController | Combobox}; for multiple
+ * selection use Multi-Select.
+ *
+ * @remarks
+ * Behavior only. Static placement is the consumer's CSS; dynamic placement is
+ * delegated to the opt-in `stimeo-ui/positioning` module. The look is keyed off
+ * `aria-selected` / `data-active`. Because `role="combobox"` is not named by its
+ * contents, give the trigger an accessible name via `aria-labelledby` (a visible
+ * label plus the value span) or `aria-label`.
+ *
+ * Behavior provided:
+ * - Open/close the list, syncing `aria-expanded` and the list's `hidden`.
+ * - `ArrowDown`/`ArrowUp` (wrapping), `Home`/`End`, and printable-character
+ *   typeahead move the active option; opening picks the selected option (else
+ *   the first).
+ * - Single selection syncs `aria-selected`, reflects the label into the trigger
+ *   value and the field's value, and dispatches `stimeo--listbox:change` plus a
+ *   native bubbling `change` on the field when its value actually changed.
+ *   Making the field a validatable mirror (`<input type="text" hidden required>`
+ *   instead of `type="hidden"`) lets `stimeo--form-validation` enforce native
+ *   constraints on the committed value with no extra JavaScript.
+ * - `Enter`/`Space` select and close; `Escape` and outside click / `Tab` close;
+ *   closing via select/Escape returns focus to the trigger.
+ */
+declare class ListboxController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static actions: readonly ["close", "onTriggerKeydown", "open", "select", "toggle"];
+    static events: readonly ["change"];
+    readonly triggerTarget: HTMLElement;
+    readonly valueTarget: HTMLElement;
+    readonly listTarget: HTMLElement;
+    readonly optionTargets: HTMLElement[];
+    readonly fieldTarget: HTMLInputElement;
+    readonly hasTriggerTarget: boolean;
+    readonly hasValueTarget: boolean;
+    readonly hasListTarget: boolean;
+    readonly hasFieldTarget: boolean;
+    /** Starts closed and registers the outside-click listener. */
+    connect(): void;
+    /** Removes the document listener and clears the typeahead timer. */
+    disconnect(): void;
+    /**
+     * Toggles the list on a real mouse click. Keyboard activation of the
+     * `<button>` also fires a click (`detail === 0`); the keydown handler already
+     * drives that, so the synthetic click is ignored to avoid double-toggling.
+     */
+    toggle(event: MouseEvent): void;
+    /** Routes trigger keyboard interaction per the APG select-only model. */
+    onTriggerKeydown(event: KeyboardEvent): void;
+    /** Selects the clicked option and closes, returning focus to the trigger. */
+    select(event: Event): void;
+    /** Opens the list and activates the selected option (else the first). */
+    open(): void;
+    /** Closes the list, clears the active option, and resets the typeahead buffer. */
+    close(): void;
+}
+
+export { ListboxController };