stimeo-ui 0.1.0-alpha.1

package/dist/controllers/auto_submit_controller.d.ts

@@ -0,0 +1,74 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless **debounced auto-submit** for forms (no dedicated APG pattern). Submits
+ * the form a configurable delay after `input`/`change`, so Rails search/filter
+ * forms refresh via Turbo without a submit button.
+ *
+ * Markup contract (identifier: `stimeo--auto-submit`):
+ *   <form data-controller="stimeo--auto-submit"
+ *         data-stimeo--auto-submit-debounce-value="300"
+ *         data-action="input->stimeo--auto-submit#submit
+ *                      change->stimeo--auto-submit#submit">
+ *     <input type="search" name="q">
+ *   </form>
+ *
+ *   <!-- Or with the form as a target nested under the controller element: -->
+ *   <div data-controller="stimeo--auto-submit">
+ *     <form data-stimeo--auto-submit-target="form"> … </form>
+ *   </div>
+ *
+ * @remarks
+ * Behavior only — it owns *triggering* the submit (debounce + `requestSubmit`),
+ * never the submit itself (Turbo / native form submission) or validation. It
+ * **never moves focus** (WCAG 2.2 3.2.2 / 4.1.3): auto-submitting must not yank the
+ * caret out of the field. While a result swap is silent for screen-reader users,
+ * setting `announce` bridges the completion to the shared `stimeo--announcer`
+ * as a safety net; apps can also listen for `stimeo--auto-submit:done`
+ * and announce richer text themselves. `aria-busy` marks the in-flight window and
+ * `data-auto-submit-pending` the debounce window, for consumer CSS. During IME
+ * composition it holds the submit until `compositionend` (the confirmed
+ * conversion) so it does not fire on each intermediate keystroke. The debounce
+ * timer and the `turbo:submit-end`/composition listeners are torn down on
+ * `disconnect()`.
+ */
+declare class AutoSubmitController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        debounce: {
+            type: NumberConstructor;
+            default: number;
+        };
+        on: {
+            type: StringConstructor;
+            default: string;
+        };
+        announce: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        message: {
+            type: StringConstructor;
+            default: string;
+        };
+    };
+    static actions: readonly ["submit"];
+    static events: readonly ["submit", "done"];
+    readonly formTarget: HTMLFormElement;
+    readonly hasFormTarget: boolean;
+    debounceValue: number;
+    onValue: string;
+    announceValue: boolean;
+    messageValue: string;
+    connect(): void;
+    disconnect(): void;
+    /**
+     * Schedules a debounced submit. Wired to `input`/`change`; the `on` value is an
+     * allowlist so a configured subset (e.g. only `change`) is honored even when both
+     * are bound in markup. Coalesces rapid events into a single `requestSubmit`.
+     */
+    submit(event: Event): void;
+}
+
+export { AutoSubmitController };

package/dist/controllers/auto_submit_controller.js

@@ -0,0 +1,147 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/auto_submit_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/auto_submit_controller.ts
+var AutoSubmitController = class extends Controller {
+  static targets = ["form"];
+  static values = {
+    debounce: { type: Number, default: 300 },
+    on: { type: String, default: "input change" },
+    announce: { type: Boolean, default: false },
+    message: { type: String, default: "" }
+  };
+  static actions = ["submit"];
+  static events = ["submit", "done"];
+  /** Debounce timer registry; one `clearAll()` in disconnect tears it down. */
+  #timers = new SafeTimeout();
+  /** Id of the pending debounce timer, so a new keystroke can reset it. */
+  #pendingId = 0;
+  /** Clears `aria-busy` and emits completion once Turbo finishes the submit. */
+  #onSubmitEnd = () => {
+    this.#form.removeAttribute("aria-busy");
+    const message = this.messageValue;
+    this.dispatch("done", { detail: { message: message || void 0 } });
+    if (this.announceValue && message) {
+      window.dispatchEvent(new CustomEvent("stimeo--announcer:announce", { detail: { message } }));
+    }
+  };
+  /** True while an IME composition is in progress on one of the form's fields. */
+  #composing = false;
+  /** Marks composition active so `input` events mid-conversion don't submit. */
+  #onCompositionStart = () => {
+    this.#composing = true;
+  };
+  /**
+   * Composition finished (the IME conversion is confirmed): clear the flag and
+   * schedule a submit as if `input` fired, so the settled text triggers a submit
+   * even on browsers whose post-composition `input` still reads `isComposing`.
+   */
+  #onCompositionEnd = (event) => {
+    this.#composing = false;
+    if (this.#triggers("input")) this.#schedule(event.target ?? null);
+  };
+  connect() {
+    this.#form.addEventListener("turbo:submit-end", this.#onSubmitEnd);
+    this.#form.addEventListener("compositionstart", this.#onCompositionStart);
+    this.#form.addEventListener("compositionend", this.#onCompositionEnd);
+  }
+  disconnect() {
+    this.#timers.clearAll();
+    this.#pendingId = 0;
+    this.#composing = false;
+    this.#form.removeAttribute("data-auto-submit-pending");
+    this.#form.removeEventListener("turbo:submit-end", this.#onSubmitEnd);
+    this.#form.removeEventListener("compositionstart", this.#onCompositionStart);
+    this.#form.removeEventListener("compositionend", this.#onCompositionEnd);
+  }
+  /**
+   * Schedules a debounced submit. Wired to `input`/`change`; the `on` value is an
+   * allowlist so a configured subset (e.g. only `change`) is honored even when both
+   * are bound in markup. Coalesces rapid events into a single `requestSubmit`.
+   */
+  submit(event) {
+    if (!this.#triggers(event.type)) return;
+    if (event.type === "input" && (this.#composing || event.isComposing)) return;
+    this.#schedule(event.target ?? null);
+  }
+  /** Schedules (and coalesces) the debounced submit for the given trigger. */
+  #schedule(trigger) {
+    this.#form.setAttribute("data-auto-submit-pending", "true");
+    if (this.#pendingId) this.#timers.clear(this.#pendingId);
+    this.#pendingId = this.#timers.set(() => {
+      this.#pendingId = 0;
+      this.#form.removeAttribute("data-auto-submit-pending");
+      this.dispatch("submit", { detail: { trigger } });
+      if (this.#form.checkValidity()) {
+        this.#form.setAttribute("aria-busy", "true");
+      }
+      this.#form.requestSubmit();
+    }, this.debounceValue);
+  }
+  /** Resolves the form element (explicit `form` target, else the controller root). */
+  get #form() {
+    return this.hasFormTarget ? this.formTarget : this.element;
+  }
+  /** Whether `type` is one of the whitespace-separated event types in `on`. */
+  #triggers(type) {
+    return this.onValue.split(/\s+/).filter(Boolean).includes(type);
+  }
+};
+
+export { AutoSubmitController };
+//# sourceMappingURL=auto_submit_controller.js.map
+//# sourceMappingURL=auto_submit_controller.js.map

package/dist/controllers/auto_submit_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/safe_timeout.ts","../../src/controllers/auto_submit_controller.ts"],"names":[],"mappings":"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","file":"auto_submit_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 **debounced auto-submit** for forms (no dedicated APG pattern). Submits\n * the form a configurable delay after `input`/`change`, so Rails search/filter\n * forms refresh via Turbo without a submit button.\n *\n * Markup contract (identifier: `stimeo--auto-submit`):\n *   <form data-controller=\"stimeo--auto-submit\"\n *         data-stimeo--auto-submit-debounce-value=\"300\"\n *         data-action=\"input->stimeo--auto-submit#submit\n *                      change->stimeo--auto-submit#submit\">\n *     <input type=\"search\" name=\"q\">\n *   </form>\n *\n *   <!-- Or with the form as a target nested under the controller element: -->\n *   <div data-controller=\"stimeo--auto-submit\">\n *     <form data-stimeo--auto-submit-target=\"form\"> … </form>\n *   </div>\n *\n * @remarks\n * Behavior only — it owns *triggering* the submit (debounce + `requestSubmit`),\n * never the submit itself (Turbo / native form submission) or validation. It\n * **never moves focus** (WCAG 2.2 3.2.2 / 4.1.3): auto-submitting must not yank the\n * caret out of the field. While a result swap is silent for screen-reader users,\n * setting `announce` bridges the completion to the shared `stimeo--announcer`\n * as a safety net; apps can also listen for `stimeo--auto-submit:done`\n * and announce richer text themselves. `aria-busy` marks the in-flight window and\n * `data-auto-submit-pending` the debounce window, for consumer CSS. During IME\n * composition it holds the submit until `compositionend` (the confirmed\n * conversion) so it does not fire on each intermediate keystroke. The debounce\n * timer and the `turbo:submit-end`/composition listeners are torn down on\n * `disconnect()`.\n */\nexport class AutoSubmitController extends Controller<HTMLElement> {\n  static override targets = [\"form\"];\n  static override values = {\n    debounce: { type: Number, default: 300 },\n    on: { type: String, default: \"input change\" },\n    announce: { type: Boolean, default: false },\n    message: { type: String, default: \"\" },\n  };\n  static actions = [\"submit\"] as const;\n  static events = [\"submit\", \"done\"] as const;\n\n  declare readonly formTarget: HTMLFormElement;\n  declare readonly hasFormTarget: boolean;\n\n  declare debounceValue: number;\n  declare onValue: string;\n  declare announceValue: boolean;\n  declare messageValue: string;\n\n  /** Debounce timer registry; one `clearAll()` in disconnect tears it down. */\n  readonly #timers = new SafeTimeout();\n  /** Id of the pending debounce timer, so a new keystroke can reset it. */\n  #pendingId = 0;\n\n  /** Clears `aria-busy` and emits completion once Turbo finishes the submit. */\n  readonly #onSubmitEnd = (): void => {\n    this.#form.removeAttribute(\"aria-busy\");\n    const message = this.messageValue;\n    this.dispatch(\"done\", { detail: { message: message || undefined } });\n    // Bridge the silent result swap to the shared Announcer so SR users hear it.\n    if (this.announceValue && message) {\n      window.dispatchEvent(new CustomEvent(\"stimeo--announcer:announce\", { detail: { message } }));\n    }\n  };\n\n  /** True while an IME composition is in progress on one of the form's fields. */\n  #composing = false;\n\n  /** Marks composition active so `input` events mid-conversion don't submit. */\n  readonly #onCompositionStart = (): void => {\n    this.#composing = true;\n  };\n\n  /**\n   * Composition finished (the IME conversion is confirmed): clear the flag and\n   * schedule a submit as if `input` fired, so the settled text triggers a submit\n   * even on browsers whose post-composition `input` still reads `isComposing`.\n   */\n  readonly #onCompositionEnd = (event: Event): void => {\n    this.#composing = false;\n    if (this.#triggers(\"input\")) this.#schedule((event.target as HTMLElement | null) ?? null);\n  };\n\n  override connect(): void {\n    this.#form.addEventListener(\"turbo:submit-end\", this.#onSubmitEnd);\n    this.#form.addEventListener(\"compositionstart\", this.#onCompositionStart);\n    this.#form.addEventListener(\"compositionend\", this.#onCompositionEnd);\n  }\n\n  override disconnect(): void {\n    this.#timers.clearAll();\n    this.#pendingId = 0;\n    // Reset so a same-instance reconnect (e.g. Turbo cache restore mid-composition)\n    // never starts with submits suppressed.\n    this.#composing = false;\n    this.#form.removeAttribute(\"data-auto-submit-pending\");\n    this.#form.removeEventListener(\"turbo:submit-end\", this.#onSubmitEnd);\n    this.#form.removeEventListener(\"compositionstart\", this.#onCompositionStart);\n    this.#form.removeEventListener(\"compositionend\", this.#onCompositionEnd);\n  }\n\n  /**\n   * Schedules a debounced submit. Wired to `input`/`change`; the `on` value is an\n   * allowlist so a configured subset (e.g. only `change`) is honored even when both\n   * are bound in markup. Coalesces rapid events into a single `requestSubmit`.\n   */\n  submit(event: Event): void {\n    if (!this.#triggers(event.type)) return;\n    // Ignore `input` events fired mid-IME-composition (e.g. typing kana before the\n    // Japanese conversion is confirmed); the confirmed text submits on\n    // `compositionend` and the browser's final post-composition `input`.\n    if (event.type === \"input\" && (this.#composing || (event as InputEvent).isComposing)) return;\n    this.#schedule((event.target as HTMLElement | null) ?? null);\n  }\n\n  /** Schedules (and coalesces) the debounced submit for the given trigger. */\n  #schedule(trigger: HTMLElement | null): void {\n    this.#form.setAttribute(\"data-auto-submit-pending\", \"true\");\n    if (this.#pendingId) this.#timers.clear(this.#pendingId);\n\n    this.#pendingId = this.#timers.set(() => {\n      this.#pendingId = 0;\n      this.#form.removeAttribute(\"data-auto-submit-pending\");\n      this.dispatch(\"submit\", { detail: { trigger } });\n      // `requestSubmit()` runs native constraint validation. If the form is\n      // invalid the actual submit never happens — the browser blocks it (or, when\n      // a `stimeo--form-validation` set `novalidate`, that controller cancels the\n      // submit) — so no `turbo:submit-end` arrives to clear `aria-busy`. Only mark\n      // the form busy when the submit will really proceed; still call\n      // `requestSubmit()` either way so the validation surfaces to the user.\n      if (this.#form.checkValidity()) {\n        this.#form.setAttribute(\"aria-busy\", \"true\");\n      }\n      this.#form.requestSubmit();\n    }, this.debounceValue);\n  }\n\n  /** Resolves the form element (explicit `form` target, else the controller root). */\n  get #form(): HTMLFormElement {\n    return this.hasFormTarget ? this.formTarget : (this.element as HTMLFormElement);\n  }\n\n  /** Whether `type` is one of the whitespace-separated event types in `on`. */\n  #triggers(type: string): boolean {\n    return this.onValue.split(/\\s+/).filter(Boolean).includes(type);\n  }\n}\n"]}

package/dist/controllers/avatar_controller.d.ts

@@ -0,0 +1,50 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless **Avatar** behavior with image-load fallback. No dedicated APG
+ * pattern; it follows the non-text-content practice (WCAG 1.1.1).
+ *
+ * Markup contract (identifier: `stimeo--avatar`):
+ *   <span data-controller="stimeo--avatar" role="img" aria-label="Jane Doe"
+ *         data-stimeo--avatar-src-value="/u/123.jpg">
+ *     <img alt="" aria-hidden="true"
+ *          data-stimeo--avatar-target="image"
+ *          data-action="load->stimeo--avatar#onLoad error->stimeo--avatar#onError" />
+ *     <span aria-hidden="true" hidden data-stimeo--avatar-target="fallback">JD</span>
+ *   </span>
+ *
+ * Watches the `<img>` `load`/`error` events and swaps to the author-provided
+ * fallback when the image fails or no `src` is given. The accessible name lives
+ * on the container (`role="img"` + `aria-label`); the inner `<img>` and the
+ * fallback are `aria-hidden` so assistive tech reads the name once, regardless of
+ * which side is visible.
+ *
+ * @remarks
+ * Behavior only — shape, size, and colour are the consumer's CSS. Initials or
+ * colour generation are out of scope: the fallback content comes from markup. The
+ * loading/loaded/error phase is exposed on `data-state` so CSS can style each.
+ */
+declare class AvatarController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        src: {
+            type: StringConstructor;
+            default: string;
+        };
+    };
+    static actions: readonly ["onError", "onLoad"];
+    static events: readonly ["error"];
+    readonly imageTarget: HTMLImageElement;
+    readonly fallbackTarget: HTMLElement;
+    readonly hasImageTarget: boolean;
+    readonly hasFallbackTarget: boolean;
+    srcValue: string;
+    connect(): void;
+    /** Reveals the image once it has loaded successfully. */
+    onLoad(): void;
+    /** Swaps to the fallback when the image fails and emits `error`. */
+    onError(): void;
+}
+
+export { AvatarController };

package/dist/controllers/avatar_controller.js

@@ -0,0 +1,66 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/avatar_controller.ts
+var AvatarController = class extends Controller {
+  static targets = ["image", "fallback"];
+  static values = {
+    src: { type: String, default: "" }
+  };
+  static actions = ["onError", "onLoad"];
+  static events = ["error"];
+  connect() {
+    if (!this.hasImageTarget) {
+      this.#showFallback();
+      return;
+    }
+    if (this.srcValue) {
+      this.imageTarget.src = this.srcValue;
+    }
+    const src = this.imageTarget.getAttribute("src");
+    if (!src) {
+      this.#showFallback();
+      return;
+    }
+    if (this.imageTarget.complete && this.imageTarget.naturalWidth > 0) {
+      this.#showImage();
+      return;
+    }
+    if (this.imageTarget.complete && this.imageTarget.naturalWidth === 0 && src) {
+      this.onError();
+      return;
+    }
+    this.#enterLoading();
+  }
+  /** Reveals the image once it has loaded successfully. */
+  onLoad() {
+    this.#showImage();
+  }
+  /** Swaps to the fallback when the image fails and emits `error`. */
+  onError() {
+    const src = this.hasImageTarget ? this.imageTarget.getAttribute("src") ?? "" : "";
+    this.#showFallback();
+    this.dispatch("error", { detail: { src } });
+  }
+  /** Loading phase: keep the image visible (per markup) while it fetches. */
+  #enterLoading() {
+    if (this.hasImageTarget) this.imageTarget.hidden = false;
+    if (this.hasFallbackTarget) this.fallbackTarget.hidden = true;
+    this.element.setAttribute("data-state", "loading");
+  }
+  /** Loaded phase: image visible, fallback hidden. */
+  #showImage() {
+    if (this.hasImageTarget) this.imageTarget.hidden = false;
+    if (this.hasFallbackTarget) this.fallbackTarget.hidden = true;
+    this.element.setAttribute("data-state", "loaded");
+  }
+  /** Error / no-src phase: fallback visible, image hidden. */
+  #showFallback() {
+    if (this.hasImageTarget) this.imageTarget.hidden = true;
+    if (this.hasFallbackTarget) this.fallbackTarget.hidden = false;
+    this.element.setAttribute("data-state", "error");
+  }
+};
+
+export { AvatarController };
+//# sourceMappingURL=avatar_controller.js.map
+//# sourceMappingURL=avatar_controller.js.map

package/dist/controllers/avatar_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/controllers/avatar_controller.ts"],"names":[],"mappings":";;;AA0BO,IAAM,gBAAA,GAAN,cAA+B,UAAA,CAAwB;AAAA,EAC5D,OAAgB,OAAA,GAAU,CAAC,OAAA,EAAS,UAAU,CAAA;AAAA,EAC9C,OAAgB,MAAA,GAAS;AAAA,IACvB,GAAA,EAAK,EAAE,IAAA,EAAM,MAAA,EAAQ,SAAS,EAAA;AAAG,GACnC;AAAA,EACA,OAAO,OAAA,GAAU,CAAC,SAAA,EAAW,QAAQ,CAAA;AAAA,EACrC,OAAO,MAAA,GAAS,CAAC,OAAO,CAAA;AAAA,EASf,OAAA,GAAgB;AACvB,IAAA,IAAI,CAAC,KAAK,cAAA,EAAgB;AAExB,MAAA,IAAA,CAAK,aAAA,EAAc;AACnB,MAAA;AAAA,IACF;AAIA,IAAA,IAAI,KAAK,QAAA,EAAU;AACjB,MAAA,IAAA,CAAK,WAAA,CAAY,MAAM,IAAA,CAAK,QAAA;AAAA,IAC9B;AAEA,IAAA,MAAM,GAAA,GAAM,IAAA,CAAK,WAAA,CAAY,YAAA,CAAa,KAAK,CAAA;AAC/C,IAAA,IAAI,CAAC,GAAA,EAAK;AAGR,MAAA,IAAA,CAAK,aAAA,EAAc;AACnB,MAAA;AAAA,IACF;AAIA,IAAA,IAAI,KAAK,WAAA,CAAY,QAAA,IAAY,IAAA,CAAK,WAAA,CAAY,eAAe,CAAA,EAAG;AAClE,MAAA,IAAA,CAAK,UAAA,EAAW;AAChB,MAAA;AAAA,IACF;AACA,IAAA,IAAI,KAAK,WAAA,CAAY,QAAA,IAAY,KAAK,WAAA,CAAY,YAAA,KAAiB,KAAK,GAAA,EAAK;AAE3E,MAAA,IAAA,CAAK,OAAA,EAAQ;AACb,MAAA;AAAA,IACF;AAEA,IAAA,IAAA,CAAK,aAAA,EAAc;AAAA,EACrB;AAAA;AAAA,EAGA,MAAA,GAAe;AACb,IAAA,IAAA,CAAK,UAAA,EAAW;AAAA,EAClB;AAAA;AAAA,EAGA,OAAA,GAAgB;AACd,IAAA,MAAM,GAAA,GAAM,KAAK,cAAA,GAAkB,IAAA,CAAK,YAAY,YAAA,CAAa,KAAK,KAAK,EAAA,GAAM,EAAA;AACjF,IAAA,IAAA,CAAK,aAAA,EAAc;AACnB,IAAA,IAAA,CAAK,SAAS,OAAA,EAAS,EAAE,QAAQ,EAAE,GAAA,IAAO,CAAA;AAAA,EAC5C;AAAA;AAAA,EAGA,aAAA,GAAsB;AACpB,IAAA,IAAI,IAAA,CAAK,cAAA,EAAgB,IAAA,CAAK,WAAA,CAAY,MAAA,GAAS,KAAA;AACnD,IAAA,IAAI,IAAA,CAAK,iBAAA,EAAmB,IAAA,CAAK,cAAA,CAAe,MAAA,GAAS,IAAA;AACzD,IAAA,IAAA,CAAK,OAAA,CAAQ,YAAA,CAAa,YAAA,EAAc,SAAS,CAAA;AAAA,EACnD;AAAA;AAAA,EAGA,UAAA,GAAmB;AACjB,IAAA,IAAI,IAAA,CAAK,cAAA,EAAgB,IAAA,CAAK,WAAA,CAAY,MAAA,GAAS,KAAA;AACnD,IAAA,IAAI,IAAA,CAAK,iBAAA,EAAmB,IAAA,CAAK,cAAA,CAAe,MAAA,GAAS,IAAA;AACzD,IAAA,IAAA,CAAK,OAAA,CAAQ,YAAA,CAAa,YAAA,EAAc,QAAQ,CAAA;AAAA,EAClD;AAAA;AAAA,EAGA,aAAA,GAAsB;AACpB,IAAA,IAAI,IAAA,CAAK,cAAA,EAAgB,IAAA,CAAK,WAAA,CAAY,MAAA,GAAS,IAAA;AACnD,IAAA,IAAI,IAAA,CAAK,iBAAA,EAAmB,IAAA,CAAK,cAAA,CAAe,MAAA,GAAS,KAAA;AACzD,IAAA,IAAA,CAAK,OAAA,CAAQ,YAAA,CAAa,YAAA,EAAc,OAAO,CAAA;AAAA,EACjD;AACF","file":"avatar_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\n\n/**\n * Headless **Avatar** behavior with image-load fallback. No dedicated APG\n * pattern; it follows the non-text-content practice (WCAG 1.1.1).\n *\n * Markup contract (identifier: `stimeo--avatar`):\n *   <span data-controller=\"stimeo--avatar\" role=\"img\" aria-label=\"Jane Doe\"\n *         data-stimeo--avatar-src-value=\"/u/123.jpg\">\n *     <img alt=\"\" aria-hidden=\"true\"\n *          data-stimeo--avatar-target=\"image\"\n *          data-action=\"load->stimeo--avatar#onLoad error->stimeo--avatar#onError\" />\n *     <span aria-hidden=\"true\" hidden data-stimeo--avatar-target=\"fallback\">JD</span>\n *   </span>\n *\n * Watches the `<img>` `load`/`error` events and swaps to the author-provided\n * fallback when the image fails or no `src` is given. The accessible name lives\n * on the container (`role=\"img\"` + `aria-label`); the inner `<img>` and the\n * fallback are `aria-hidden` so assistive tech reads the name once, regardless of\n * which side is visible.\n *\n * @remarks\n * Behavior only — shape, size, and colour are the consumer's CSS. Initials or\n * colour generation are out of scope: the fallback content comes from markup. The\n * loading/loaded/error phase is exposed on `data-state` so CSS can style each.\n */\nexport class AvatarController extends Controller<HTMLElement> {\n  static override targets = [\"image\", \"fallback\"];\n  static override values = {\n    src: { type: String, default: \"\" },\n  };\n  static actions = [\"onError\", \"onLoad\"] as const;\n  static events = [\"error\"] as const;\n\n  declare readonly imageTarget: HTMLImageElement;\n  declare readonly fallbackTarget: HTMLElement;\n  declare readonly hasImageTarget: boolean;\n  declare readonly hasFallbackTarget: boolean;\n\n  declare srcValue: string;\n\n  override connect(): void {\n    if (!this.hasImageTarget) {\n      // Nothing to monitor: surface the fallback so the container is not empty.\n      this.#showFallback();\n      return;\n    }\n\n    // A `src` Value, when present, is the source of truth and is applied to the\n    // image; otherwise the markup's own `src` attribute (if any) is honored.\n    if (this.srcValue) {\n      this.imageTarget.src = this.srcValue;\n    }\n\n    const src = this.imageTarget.getAttribute(\"src\");\n    if (!src) {\n      // No image to load at all — go straight to the fallback without emitting an\n      // error event (there was no failed load attempt).\n      this.#showFallback();\n      return;\n    }\n\n    // A cached image may already be complete by the time the controller connects,\n    // in which case the `load` event has fired and won't fire again.\n    if (this.imageTarget.complete && this.imageTarget.naturalWidth > 0) {\n      this.#showImage();\n      return;\n    }\n    if (this.imageTarget.complete && this.imageTarget.naturalWidth === 0 && src) {\n      // Complete but with no intrinsic size means the load already failed.\n      this.onError();\n      return;\n    }\n\n    this.#enterLoading();\n  }\n\n  /** Reveals the image once it has loaded successfully. */\n  onLoad(): void {\n    this.#showImage();\n  }\n\n  /** Swaps to the fallback when the image fails and emits `error`. */\n  onError(): void {\n    const src = this.hasImageTarget ? (this.imageTarget.getAttribute(\"src\") ?? \"\") : \"\";\n    this.#showFallback();\n    this.dispatch(\"error\", { detail: { src } });\n  }\n\n  /** Loading phase: keep the image visible (per markup) while it fetches. */\n  #enterLoading(): void {\n    if (this.hasImageTarget) this.imageTarget.hidden = false;\n    if (this.hasFallbackTarget) this.fallbackTarget.hidden = true;\n    this.element.setAttribute(\"data-state\", \"loading\");\n  }\n\n  /** Loaded phase: image visible, fallback hidden. */\n  #showImage(): void {\n    if (this.hasImageTarget) this.imageTarget.hidden = false;\n    if (this.hasFallbackTarget) this.fallbackTarget.hidden = true;\n    this.element.setAttribute(\"data-state\", \"loaded\");\n  }\n\n  /** Error / no-src phase: fallback visible, image hidden. */\n  #showFallback(): void {\n    if (this.hasImageTarget) this.imageTarget.hidden = true;\n    if (this.hasFallbackTarget) this.fallbackTarget.hidden = false;\n    this.element.setAttribute(\"data-state\", \"error\");\n  }\n}\n"]}

package/dist/controllers/breadcrumb_controller.d.ts

@@ -0,0 +1,60 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless, accessible responsive breadcrumb behavior.
+ *
+ * Markup contract (identifier: `stimeo--breadcrumb`):
+ *   <nav data-controller="stimeo--breadcrumb" aria-label="Breadcrumb">
+ *     <ol data-stimeo--breadcrumb-target="list">
+ *       <li><a href="/">Home</a></li>
+ *       <li data-stimeo--breadcrumb-target="ellipsis" hidden>
+ *         <button type="button" aria-expanded="false" aria-controls="bc-collapsed"
+ *                 aria-label="Show full path"
+ *                 data-stimeo--breadcrumb-target="trigger"
+ *                 data-action="stimeo--breadcrumb#toggle">…</button>
+ *       </li>
+ *       <li id="bc-collapsed" data-stimeo--breadcrumb-target="collapsible"><a href="/a">Section A</a></li>
+ *       <li data-stimeo--breadcrumb-target="collapsible"><a href="/a/b">Sub B</a></li>
+ *       <li><a href="/a/b/c" aria-current="page">Item C</a></li>
+ *     </ol>
+ *   </nav>
+ *
+ * Implements the WAI-ARIA APG **Breadcrumb** pattern. The base structure (`nav`
+ * + `ol` + `aria-current="page"`) lives in the markup; this controller adds the
+ * responsive behavior: when the trail overflows its container it collapses the
+ * author-marked middle items behind a disclosure (`…`) button, which expands
+ * them back on demand.
+ *
+ * @remarks
+ * Behavior only — the consumer owns separators (CSS) and the look. The items to
+ * collapse are the author-marked `collapsible` targets (the source of truth),
+ * placed between the leading and trailing items that must always stay visible.
+ *
+ * Behavior provided:
+ * - Detects overflow via {@link LayoutObserver} (element + viewport resize).
+ * - While overflowing and not expanded, hides the `collapsible` items and shows
+ *   the `ellipsis` item; when it fits, shows everything and hides the ellipsis.
+ * - The disclosure `trigger` toggles `aria-expanded` and the collapsed items,
+ *   dispatching `stimeo--breadcrumb:toggle`.
+ */
+declare class BreadcrumbController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static actions: readonly ["toggle"];
+    static events: readonly ["toggle"];
+    readonly listTarget: HTMLElement;
+    readonly collapsibleTargets: HTMLElement[];
+    readonly ellipsisTarget: HTMLElement;
+    readonly triggerTarget: HTMLElement;
+    readonly hasListTarget: boolean;
+    readonly hasEllipsisTarget: boolean;
+    readonly hasTriggerTarget: boolean;
+    /** Starts observing for overflow and renders the initial state. */
+    connect(): void;
+    /** Releases the resize observation (Turbo navigation included). */
+    disconnect(): void;
+    /** Expands or re-collapses the trail and dispatches `toggle`. */
+    toggle(): void;
+}
+
+export { BreadcrumbController };

package/dist/controllers/breadcrumb_controller.js

@@ -0,0 +1,123 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/breadcrumb_controller.ts
+
+// src/utils/layout_observer.ts
+var LayoutObserver = class {
+  #callback;
+  #resizeObserverFactory;
+  #resizeObserver = null;
+  #observingViewport = false;
+  /** Stable bound handler so add/removeEventListener target the same reference. */
+  #handleViewportResize = () => {
+    this.#callback();
+  };
+  constructor(callback, options = {}) {
+    this.#callback = callback;
+    this.#resizeObserverFactory = options.resizeObserverFactory ?? (typeof ResizeObserver === "undefined" ? null : (cb) => new ResizeObserver(cb));
+  }
+  /**
+   * Starts observing an element's size. Repeated calls observe additional
+   * elements through the same shared observer. No-ops when no
+   * `ResizeObserver` implementation is available.
+   */
+  observe(element) {
+    if (!this.#resizeObserverFactory) return;
+    if (!this.#resizeObserver) {
+      this.#resizeObserver = this.#resizeObserverFactory(() => {
+        this.#callback();
+      });
+    }
+    this.#resizeObserver.observe(element);
+  }
+  /** Stops observing a single element while leaving any others in place. */
+  unobserve(element) {
+    this.#resizeObserver?.unobserve(element);
+  }
+  /** Starts observing viewport resizes. Idempotent: the listener is added once. */
+  observeViewport() {
+    if (this.#observingViewport) return;
+    this.#observingViewport = true;
+    window.addEventListener("resize", this.#handleViewportResize);
+  }
+  /** Stops observing viewport resizes without affecting element observation. */
+  unobserveViewport() {
+    if (!this.#observingViewport) return;
+    this.#observingViewport = false;
+    window.removeEventListener("resize", this.#handleViewportResize);
+  }
+  /**
+   * Releases every observation: disconnects the {@link ResizeObserver} and
+   * removes the viewport listener. Safe to call multiple times. Call this from a
+   * controller's `disconnect()`.
+   */
+  disconnect() {
+    this.#resizeObserver?.disconnect();
+    this.#resizeObserver = null;
+    this.unobserveViewport();
+  }
+};
+
+// src/controllers/breadcrumb_controller.ts
+var BreadcrumbController = class extends Controller {
+  static targets = ["list", "collapsible", "ellipsis", "trigger"];
+  static actions = ["toggle"];
+  static events = ["toggle"];
+  /** Whether the trail currently overflows its container. */
+  #overflowing = false;
+  /** Whether the user has expanded the collapsed items via the disclosure. */
+  #expanded = false;
+  #layout = new LayoutObserver(() => this.#update());
+  /** Starts observing for overflow and renders the initial state. */
+  connect() {
+    if (this.hasListTarget) this.#layout.observe(this.listTarget);
+    this.#layout.observeViewport();
+    this.#update();
+  }
+  /** Releases the resize observation (Turbo navigation included). */
+  disconnect() {
+    this.#layout.disconnect();
+  }
+  /** Expands or re-collapses the trail and dispatches `toggle`. */
+  toggle() {
+    this.#expanded = !this.#expanded;
+    this.#render();
+    this.dispatch("toggle", { detail: { expanded: this.#expanded } });
+  }
+  /** Re-measures overflow and re-renders (e.g. on resize). */
+  #update() {
+    this.#overflowing = this.#measureOverflow();
+    if (!this.#overflowing) this.#expanded = false;
+    this.#render();
+  }
+  /**
+   * Measures overflow against the **fully expanded** layout so hiding items does
+   * not make the condition oscillate. Reveals every item, then compares the list's
+   * own scroll width to its own client width; `#render` immediately re-applies
+   * the correct hidden state afterward.
+   *
+   * Both widths are read from the list element itself (not the host `nav`) so the
+   * check is independent of any padding/border on the host — comparing against the
+   * host's `clientWidth` would over-report the available space by its padding and
+   * miss real overflow in a padded container.
+   */
+  #measureOverflow() {
+    if (!this.hasListTarget) return false;
+    for (const item of this.collapsibleTargets) item.hidden = false;
+    if (this.hasEllipsisTarget) this.ellipsisTarget.hidden = true;
+    return this.listTarget.scrollWidth > this.listTarget.clientWidth;
+  }
+  /** Applies the collapsed/expanded state to the items, ellipsis, and trigger. */
+  #render() {
+    const collapsed = this.#overflowing && !this.#expanded;
+    for (const item of this.collapsibleTargets) item.hidden = collapsed;
+    if (this.hasEllipsisTarget) this.ellipsisTarget.hidden = !this.#overflowing;
+    if (this.hasTriggerTarget) {
+      this.triggerTarget.setAttribute("aria-expanded", this.#expanded ? "true" : "false");
+    }
+  }
+};
+
+export { BreadcrumbController };
+//# sourceMappingURL=breadcrumb_controller.js.map
+//# sourceMappingURL=breadcrumb_controller.js.map

package/dist/controllers/breadcrumb_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/layout_observer.ts","../../src/controllers/breadcrumb_controller.ts"],"names":[],"mappings":";;;;;AAgDO,IAAM,iBAAN,MAAqB;AAAA,EACjB,SAAA;AAAA,EACA,sBAAA;AAAA,EACT,eAAA,GAAyC,IAAA;AAAA,EACzC,kBAAA,GAAqB,KAAA;AAAA;AAAA,EAGZ,wBAAwB,MAAY;AAC3C,IAAA,IAAA,CAAK,SAAA,EAAU;AAAA,EACjB,CAAA;AAAA,EAEA,WAAA,CAAY,QAAA,EAA0B,OAAA,GAAiC,EAAC,EAAG;AACzE,IAAA,IAAA,CAAK,SAAA,GAAY,QAAA;AACjB,IAAA,IAAA,CAAK,sBAAA,GACH,OAAA,CAAQ,qBAAA,KACP,OAAO,cAAA,KAAmB,WAAA,GAAc,IAAA,GAAO,CAAC,EAAA,KAAO,IAAI,cAAA,CAAe,EAAE,CAAA,CAAA;AAAA,EACjF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,QAAQ,OAAA,EAAwB;AAC9B,IAAA,IAAI,CAAC,KAAK,sBAAA,EAAwB;AAClC,IAAA,IAAI,CAAC,KAAK,eAAA,EAAiB;AACzB,MAAA,IAAA,CAAK,eAAA,GAAkB,IAAA,CAAK,sBAAA,CAAuB,MAAM;AACvD,QAAA,IAAA,CAAK,SAAA,EAAU;AAAA,MACjB,CAAC,CAAA;AAAA,IACH;AACA,IAAA,IAAA,CAAK,eAAA,CAAgB,QAAQ,OAAO,CAAA;AAAA,EACtC;AAAA;AAAA,EAGA,UAAU,OAAA,EAAwB;AAChC,IAAA,IAAA,CAAK,eAAA,EAAiB,UAAU,OAAO,CAAA;AAAA,EACzC;AAAA;AAAA,EAGA,eAAA,GAAwB;AACtB,IAAA,IAAI,KAAK,kBAAA,EAAoB;AAC7B,IAAA,IAAA,CAAK,kBAAA,GAAqB,IAAA;AAC1B,IAAA,MAAA,CAAO,gBAAA,CAAiB,QAAA,EAAU,IAAA,CAAK,qBAAqB,CAAA;AAAA,EAC9D;AAAA;AAAA,EAGA,iBAAA,GAA0B;AACxB,IAAA,IAAI,CAAC,KAAK,kBAAA,EAAoB;AAC9B,IAAA,IAAA,CAAK,kBAAA,GAAqB,KAAA;AAC1B,IAAA,MAAA,CAAO,mBAAA,CAAoB,QAAA,EAAU,IAAA,CAAK,qBAAqB,CAAA;AAAA,EACjE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,UAAA,GAAmB;AACjB,IAAA,IAAA,CAAK,iBAAiB,UAAA,EAAW;AACjC,IAAA,IAAA,CAAK,eAAA,GAAkB,IAAA;AACvB,IAAA,IAAA,CAAK,iBAAA,EAAkB;AAAA,EACzB;AACF,CAAA;;;ACtEO,IAAM,oBAAA,GAAN,cAAmC,UAAA,CAAwB;AAAA,EAChE,OAAgB,OAAA,GAAU,CAAC,MAAA,EAAQ,aAAA,EAAe,YAAY,SAAS,CAAA;AAAA,EACvE,OAAO,OAAA,GAAU,CAAC,QAAQ,CAAA;AAAA,EAC1B,OAAO,MAAA,GAAS,CAAC,QAAQ,CAAA;AAAA;AAAA,EAWzB,YAAA,GAAe,KAAA;AAAA;AAAA,EAEf,SAAA,GAAY,KAAA;AAAA,EAEH,UAAU,IAAI,cAAA,CAAe,MAAM,IAAA,CAAK,SAAS,CAAA;AAAA;AAAA,EAGjD,OAAA,GAAgB;AACvB,IAAA,IAAI,KAAK,aAAA,EAAe,IAAA,CAAK,OAAA,CAAQ,OAAA,CAAQ,KAAK,UAAU,CAAA;AAC5D,IAAA,IAAA,CAAK,QAAQ,eAAA,EAAgB;AAC7B,IAAA,IAAA,CAAK,OAAA,EAAQ;AAAA,EACf;AAAA;AAAA,EAGS,UAAA,GAAmB;AAC1B,IAAA,IAAA,CAAK,QAAQ,UAAA,EAAW;AAAA,EAC1B;AAAA;AAAA,EAGA,MAAA,GAAe;AACb,IAAA,IAAA,CAAK,SAAA,GAAY,CAAC,IAAA,CAAK,SAAA;AACvB,IAAA,IAAA,CAAK,OAAA,EAAQ;AACb,IAAA,IAAA,CAAK,QAAA,CAAS,UAAU,EAAE,MAAA,EAAQ,EAAE,QAAA,EAAU,IAAA,CAAK,SAAA,EAAU,EAAG,CAAA;AAAA,EAClE;AAAA;AAAA,EAGA,OAAA,GAAgB;AACd,IAAA,IAAA,CAAK,YAAA,GAAe,KAAK,gBAAA,EAAiB;AAC1C,IAAA,IAAI,CAAC,IAAA,CAAK,YAAA,EAAc,IAAA,CAAK,SAAA,GAAY,KAAA;AACzC,IAAA,IAAA,CAAK,OAAA,EAAQ;AAAA,EACf;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAaA,gBAAA,GAA4B;AAC1B,IAAA,IAAI,CAAC,IAAA,CAAK,aAAA,EAAe,OAAO,KAAA;AAChC,IAAA,KAAA,MAAW,IAAA,IAAQ,IAAA,CAAK,kBAAA,EAAoB,IAAA,CAAK,MAAA,GAAS,KAAA;AAC1D,IAAA,IAAI,IAAA,CAAK,iBAAA,EAAmB,IAAA,CAAK,cAAA,CAAe,MAAA,GAAS,IAAA;AACzD,IAAA,OAAO,IAAA,CAAK,UAAA,CAAW,WAAA,GAAc,IAAA,CAAK,UAAA,CAAW,WAAA;AAAA,EACvD;AAAA;AAAA,EAGA,OAAA,GAAgB;AACd,IAAA,MAAM,SAAA,GAAY,IAAA,CAAK,YAAA,IAAgB,CAAC,IAAA,CAAK,SAAA;AAC7C,IAAA,KAAA,MAAW,IAAA,IAAQ,IAAA,CAAK,kBAAA,EAAoB,IAAA,CAAK,MAAA,GAAS,SAAA;AAC1D,IAAA,IAAI,KAAK,iBAAA,EAAmB,IAAA,CAAK,cAAA,CAAe,MAAA,GAAS,CAAC,IAAA,CAAK,YAAA;AAC/D,IAAA,IAAI,KAAK,gBAAA,EAAkB;AACzB,MAAA,IAAA,CAAK,cAAc,YAAA,CAAa,eAAA,EAAiB,IAAA,CAAK,SAAA,GAAY,SAAS,OAAO,CAAA;AAAA,IACpF;AAAA,EACF;AACF","file":"breadcrumb_controller.js","sourcesContent":["/**\n * Unified element-size and viewport observation for Stimeo controllers.\n *\n * Layout-sensitive widgets (sliders, resizable panes, scroll spies, popovers)\n * need to react both to their *own* box changing — via {@link ResizeObserver} —\n * and to the *viewport* changing — via the `window` `resize` event. Wiring those\n * two sources by hand in every controller risks leaked listeners on\n * `disconnect()`. {@link LayoutObserver} owns both behind one callback and one\n * {@link LayoutObserver.disconnect | disconnect()} that releases everything.\n *\n * Behavior only: the helper reports *that* layout changed; it never reads or\n * writes styles. Consumers decide what to recompute.\n */\n\n/** Invoked whenever an observed element or the viewport changes size. */\nexport type LayoutCallback = () => void;\n\n/** Constructs a {@link ResizeObserver}; injectable so tests stay deterministic. */\nexport type ResizeObserverFactory = (callback: ResizeObserverCallback) => ResizeObserver;\n\n/** Options for {@link LayoutObserver}. */\nexport interface LayoutObserverOptions {\n  /**\n   * Factory for the {@link ResizeObserver} used by {@link LayoutObserver.observe}.\n   * Defaults to the global constructor; override it in tests, or to no-op in\n   * environments where `ResizeObserver` is unavailable.\n   */\n  resizeObserverFactory?: ResizeObserverFactory;\n}\n\n/**\n * Observes element resizes and/or viewport resizes through a single callback,\n * with guaranteed teardown.\n *\n * @example\n * ```ts\n * #layout = new LayoutObserver(() => this.#reposition());\n *\n * connect() {\n *   this.#layout.observe(this.panelTarget);\n *   this.#layout.observeViewport();\n * }\n *\n * disconnect() {\n *   this.#layout.disconnect();\n * }\n * ```\n */\nexport class LayoutObserver {\n  readonly #callback: LayoutCallback;\n  readonly #resizeObserverFactory: ResizeObserverFactory | null;\n  #resizeObserver: ResizeObserver | null = null;\n  #observingViewport = false;\n\n  /** Stable bound handler so add/removeEventListener target the same reference. */\n  readonly #handleViewportResize = (): void => {\n    this.#callback();\n  };\n\n  constructor(callback: LayoutCallback, options: LayoutObserverOptions = {}) {\n    this.#callback = callback;\n    this.#resizeObserverFactory =\n      options.resizeObserverFactory ??\n      (typeof ResizeObserver === \"undefined\" ? null : (cb) => new ResizeObserver(cb));\n  }\n\n  /**\n   * Starts observing an element's size. Repeated calls observe additional\n   * elements through the same shared observer. No-ops when no\n   * `ResizeObserver` implementation is available.\n   */\n  observe(element: Element): void {\n    if (!this.#resizeObserverFactory) return;\n    if (!this.#resizeObserver) {\n      this.#resizeObserver = this.#resizeObserverFactory(() => {\n        this.#callback();\n      });\n    }\n    this.#resizeObserver.observe(element);\n  }\n\n  /** Stops observing a single element while leaving any others in place. */\n  unobserve(element: Element): void {\n    this.#resizeObserver?.unobserve(element);\n  }\n\n  /** Starts observing viewport resizes. Idempotent: the listener is added once. */\n  observeViewport(): void {\n    if (this.#observingViewport) return;\n    this.#observingViewport = true;\n    window.addEventListener(\"resize\", this.#handleViewportResize);\n  }\n\n  /** Stops observing viewport resizes without affecting element observation. */\n  unobserveViewport(): void {\n    if (!this.#observingViewport) return;\n    this.#observingViewport = false;\n    window.removeEventListener(\"resize\", this.#handleViewportResize);\n  }\n\n  /**\n   * Releases every observation: disconnects the {@link ResizeObserver} and\n   * removes the viewport listener. Safe to call multiple times. Call this from a\n   * controller's `disconnect()`.\n   */\n  disconnect(): void {\n    this.#resizeObserver?.disconnect();\n    this.#resizeObserver = null;\n    this.unobserveViewport();\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { LayoutObserver } from \"../utils/layout_observer\";\n\n/**\n * Headless, accessible responsive breadcrumb behavior.\n *\n * Markup contract (identifier: `stimeo--breadcrumb`):\n *   <nav data-controller=\"stimeo--breadcrumb\" aria-label=\"Breadcrumb\">\n *     <ol data-stimeo--breadcrumb-target=\"list\">\n *       <li><a href=\"/\">Home</a></li>\n *       <li data-stimeo--breadcrumb-target=\"ellipsis\" hidden>\n *         <button type=\"button\" aria-expanded=\"false\" aria-controls=\"bc-collapsed\"\n *                 aria-label=\"Show full path\"\n *                 data-stimeo--breadcrumb-target=\"trigger\"\n *                 data-action=\"stimeo--breadcrumb#toggle\">…</button>\n *       </li>\n *       <li id=\"bc-collapsed\" data-stimeo--breadcrumb-target=\"collapsible\"><a href=\"/a\">Section A</a></li>\n *       <li data-stimeo--breadcrumb-target=\"collapsible\"><a href=\"/a/b\">Sub B</a></li>\n *       <li><a href=\"/a/b/c\" aria-current=\"page\">Item C</a></li>\n *     </ol>\n *   </nav>\n *\n * Implements the WAI-ARIA APG **Breadcrumb** pattern. The base structure (`nav`\n * + `ol` + `aria-current=\"page\"`) lives in the markup; this controller adds the\n * responsive behavior: when the trail overflows its container it collapses the\n * author-marked middle items behind a disclosure (`…`) button, which expands\n * them back on demand.\n *\n * @remarks\n * Behavior only — the consumer owns separators (CSS) and the look. The items to\n * collapse are the author-marked `collapsible` targets (the source of truth),\n * placed between the leading and trailing items that must always stay visible.\n *\n * Behavior provided:\n * - Detects overflow via {@link LayoutObserver} (element + viewport resize).\n * - While overflowing and not expanded, hides the `collapsible` items and shows\n *   the `ellipsis` item; when it fits, shows everything and hides the ellipsis.\n * - The disclosure `trigger` toggles `aria-expanded` and the collapsed items,\n *   dispatching `stimeo--breadcrumb:toggle`.\n */\nexport class BreadcrumbController extends Controller<HTMLElement> {\n  static override targets = [\"list\", \"collapsible\", \"ellipsis\", \"trigger\"];\n  static actions = [\"toggle\"] as const;\n  static events = [\"toggle\"] as const;\n\n  declare readonly listTarget: HTMLElement;\n  declare readonly collapsibleTargets: HTMLElement[];\n  declare readonly ellipsisTarget: HTMLElement;\n  declare readonly triggerTarget: HTMLElement;\n  declare readonly hasListTarget: boolean;\n  declare readonly hasEllipsisTarget: boolean;\n  declare readonly hasTriggerTarget: boolean;\n\n  /** Whether the trail currently overflows its container. */\n  #overflowing = false;\n  /** Whether the user has expanded the collapsed items via the disclosure. */\n  #expanded = false;\n\n  readonly #layout = new LayoutObserver(() => this.#update());\n\n  /** Starts observing for overflow and renders the initial state. */\n  override connect(): void {\n    if (this.hasListTarget) this.#layout.observe(this.listTarget);\n    this.#layout.observeViewport();\n    this.#update();\n  }\n\n  /** Releases the resize observation (Turbo navigation included). */\n  override disconnect(): void {\n    this.#layout.disconnect();\n  }\n\n  /** Expands or re-collapses the trail and dispatches `toggle`. */\n  toggle(): void {\n    this.#expanded = !this.#expanded;\n    this.#render();\n    this.dispatch(\"toggle\", { detail: { expanded: this.#expanded } });\n  }\n\n  /** Re-measures overflow and re-renders (e.g. on resize). */\n  #update(): void {\n    this.#overflowing = this.#measureOverflow();\n    if (!this.#overflowing) this.#expanded = false;\n    this.#render();\n  }\n\n  /**\n   * Measures overflow against the **fully expanded** layout so hiding items does\n   * not make the condition oscillate. Reveals every item, then compares the list's\n   * own scroll width to its own client width; `#render` immediately re-applies\n   * the correct hidden state afterward.\n   *\n   * Both widths are read from the list element itself (not the host `nav`) so the\n   * check is independent of any padding/border on the host — comparing against the\n   * host's `clientWidth` would over-report the available space by its padding and\n   * miss real overflow in a padded container.\n   */\n  #measureOverflow(): boolean {\n    if (!this.hasListTarget) return false;\n    for (const item of this.collapsibleTargets) item.hidden = false;\n    if (this.hasEllipsisTarget) this.ellipsisTarget.hidden = true;\n    return this.listTarget.scrollWidth > this.listTarget.clientWidth;\n  }\n\n  /** Applies the collapsed/expanded state to the items, ellipsis, and trigger. */\n  #render(): void {\n    const collapsed = this.#overflowing && !this.#expanded;\n    for (const item of this.collapsibleTargets) item.hidden = collapsed;\n    if (this.hasEllipsisTarget) this.ellipsisTarget.hidden = !this.#overflowing;\n    if (this.hasTriggerTarget) {\n      this.triggerTarget.setAttribute(\"aria-expanded\", this.#expanded ? \"true\" : \"false\");\n    }\n  }\n}\n"]}