stimeo-ui 0.5.0 → 0.7.0

package/dist/controllers/auto_submit_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/composition_tracker.ts","../../src/utils/safe_timeout.ts","../../src/controllers/auto_submit_controller.ts"],"names":[],"mappings":"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","file":"auto_submit_controller.js","sourcesContent":["/** Minimal event shape carrying the platform's per-event composition signal. */\nexport interface CompositionSignal {\n  readonly isComposing?: boolean;\n}\n\n/** Hooks that keep component-specific work outside {@link CompositionTracker}. */\nexport interface CompositionTrackerOptions {\n  /** Runs after lifecycle state is set for a `compositionstart` event. */\n  readonly onStart?: (event: Event) => void;\n  /** Runs after lifecycle state is cleared for a `compositionend` event. */\n  readonly onEnd?: (event: Event) => void;\n}\n\n/**\n * Owns IME composition listeners and transient state for one or more event targets.\n *\n * Some browsers omit `KeyboardEvent.isComposing` on the keydown that confirms a\n * conversion. Tracking `compositionstart` through `compositionend` supplies the\n * missing lifecycle signal without relying on deprecated numeric key codes.\n * Component policy stays with the consumer: filtering, validation, and submission\n * belong in the optional {@link CompositionTrackerOptions.onEnd} callback.\n *\n * @example\n * ```ts\n * #composition = new CompositionTracker({ onEnd: () => this.filter() });\n *\n * connect(): void {\n *   this.#composition.observe(this.inputTarget);\n * }\n *\n * disconnect(): void {\n *   this.#composition.disconnect();\n * }\n *\n * onKeydown(event: KeyboardEvent): void {\n *   if (this.#composition.isComposing(event)) return;\n * }\n * ```\n */\nexport class CompositionTracker {\n  readonly #observedTargets = new Set<EventTarget>();\n  readonly #activeTargets = new Set<EventTarget>();\n  readonly #onStart: ((event: Event) => void) | undefined;\n  readonly #onEnd: ((event: Event) => void) | undefined;\n\n  constructor(options: CompositionTrackerOptions = {}) {\n    this.#onStart = options.onStart;\n    this.#onEnd = options.onEnd;\n  }\n\n  /** Starts lifecycle tracking for `target`; repeated calls are idempotent. */\n  observe(target: EventTarget): void {\n    if (this.#observedTargets.has(target)) return;\n    target.addEventListener(\"compositionstart\", this.#handleStart);\n    target.addEventListener(\"compositionend\", this.#handleEnd);\n    this.#observedTargets.add(target);\n  }\n\n  /** Stops tracking one target and clears any active composition it owned. */\n  unobserve(target: EventTarget): void {\n    if (!this.#observedTargets.delete(target)) return;\n    target.removeEventListener(\"compositionstart\", this.#handleStart);\n    target.removeEventListener(\"compositionend\", this.#handleEnd);\n    this.#activeTargets.delete(target);\n  }\n\n  /** Releases every listener and clears state so reconnect starts cleanly. */\n  disconnect(): void {\n    for (const target of this.#observedTargets) {\n      target.removeEventListener(\"compositionstart\", this.#handleStart);\n      target.removeEventListener(\"compositionend\", this.#handleEnd);\n    }\n    this.#observedTargets.clear();\n    this.#activeTargets.clear();\n  }\n\n  /** True when lifecycle tracking or the current event reports composition. */\n  isComposing(event?: CompositionSignal): boolean {\n    return this.#activeTargets.size > 0 || event?.isComposing === true;\n  }\n\n  readonly #handleStart = (event: Event): void => {\n    if (event.currentTarget) this.#activeTargets.add(event.currentTarget);\n    this.#onStart?.(event);\n  };\n\n  readonly #handleEnd = (event: Event): void => {\n    if (event.currentTarget) this.#activeTargets.delete(event.currentTarget);\n    this.#onEnd?.(event);\n  };\n}\n","/**\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 { CompositionTracker } from \"../utils/composition_tracker\";\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  /** Owns delegated IME lifecycle state and submits confirmed input text. */\n  readonly #composition = new CompositionTracker({\n    onEnd: (event) => {\n      if (this.#triggers(\"input\")) this.#schedule((event.target as HTMLElement | null) ?? null);\n    },\n  });\n\n  override connect(): void {\n    this.#form.addEventListener(\"turbo:submit-end\", this.#onSubmitEnd);\n    this.#composition.observe(this.#form);\n  }\n\n  override disconnect(): void {\n    this.#timers.clearAll();\n    this.#pendingId = 0;\n    this.#composition.disconnect();\n    this.#form.removeAttribute(\"data-auto-submit-pending\");\n    this.#form.removeEventListener(\"turbo:submit-end\", this.#onSubmitEnd);\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.#composition.isComposing(event as InputEvent)) 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"]}
+{"version":3,"sources":["../../src/utils/composition_tracker.ts","../../src/utils/safe_timeout.ts","../../src/controllers/auto_submit_controller.ts"],"names":[],"mappings":"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","file":"auto_submit_controller.js","sourcesContent":["/** Minimal event shape carrying the platform's per-event composition signal. */\nexport interface CompositionSignal {\n  readonly isComposing?: boolean;\n}\n\n/** Hooks that keep component-specific work outside {@link CompositionTracker}. */\nexport interface CompositionTrackerOptions {\n  /** Runs after lifecycle state is set for a `compositionstart` event. */\n  readonly onStart?: (event: Event) => void;\n  /** Runs after lifecycle state is cleared for a `compositionend` event. */\n  readonly onEnd?: (event: Event) => void;\n}\n\n/**\n * Owns IME composition listeners and transient state for one or more event targets.\n *\n * Some browsers omit `KeyboardEvent.isComposing` on the keydown that confirms a\n * conversion. Tracking `compositionstart` through `compositionend` supplies the\n * missing lifecycle signal without relying on deprecated numeric key codes.\n * Component policy stays with the consumer: filtering, validation, and submission\n * belong in the optional {@link CompositionTrackerOptions.onEnd} callback.\n *\n * @example\n * ```ts\n * #composition = new CompositionTracker({ onEnd: () => this.filter() });\n *\n * connect(): void {\n *   this.#composition.observe(this.inputTarget);\n * }\n *\n * disconnect(): void {\n *   this.#composition.disconnect();\n * }\n *\n * onKeydown(event: KeyboardEvent): void {\n *   if (this.#composition.isComposing(event)) return;\n * }\n * ```\n */\nexport class CompositionTracker {\n  readonly #observedTargets = new Set<EventTarget>();\n  readonly #activeTargets = new Set<EventTarget>();\n  readonly #onStart: ((event: Event) => void) | undefined;\n  readonly #onEnd: ((event: Event) => void) | undefined;\n\n  constructor(options: CompositionTrackerOptions = {}) {\n    this.#onStart = options.onStart;\n    this.#onEnd = options.onEnd;\n  }\n\n  /** Starts lifecycle tracking for `target`; repeated calls are idempotent. */\n  observe(target: EventTarget): void {\n    if (this.#observedTargets.has(target)) return;\n    target.addEventListener(\"compositionstart\", this.#handleStart);\n    target.addEventListener(\"compositionend\", this.#handleEnd);\n    this.#observedTargets.add(target);\n  }\n\n  /** Stops tracking one target and clears any active composition it owned. */\n  unobserve(target: EventTarget): void {\n    if (!this.#observedTargets.delete(target)) return;\n    target.removeEventListener(\"compositionstart\", this.#handleStart);\n    target.removeEventListener(\"compositionend\", this.#handleEnd);\n    this.#activeTargets.delete(target);\n  }\n\n  /** Releases every listener and clears state so reconnect starts cleanly. */\n  disconnect(): void {\n    for (const target of this.#observedTargets) {\n      target.removeEventListener(\"compositionstart\", this.#handleStart);\n      target.removeEventListener(\"compositionend\", this.#handleEnd);\n    }\n    this.#observedTargets.clear();\n    this.#activeTargets.clear();\n  }\n\n  /** True when lifecycle tracking or the current event reports composition. */\n  isComposing(event?: CompositionSignal): boolean {\n    return this.#activeTargets.size > 0 || event?.isComposing === true;\n  }\n\n  readonly #handleStart = (event: Event): void => {\n    if (event.currentTarget) this.#activeTargets.add(event.currentTarget);\n    this.#onStart?.(event);\n  };\n\n  readonly #handleEnd = (event: Event): void => {\n    if (event.currentTarget) this.#activeTargets.delete(event.currentTarget);\n    this.#onEnd?.(event);\n  };\n}\n","/**\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 { CompositionTracker } from \"../utils/composition_tracker\";\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 * `submit` dispatches `{ trigger }`; `done` dispatches `{ message? }`.\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  /** Owns delegated IME lifecycle state and submits confirmed input text. */\n  readonly #composition = new CompositionTracker({\n    onEnd: (event) => {\n      if (this.#triggers(\"input\")) this.#schedule((event.target as HTMLElement | null) ?? null);\n    },\n  });\n\n  override connect(): void {\n    this.#form.addEventListener(\"turbo:submit-end\", this.#onSubmitEnd);\n    this.#composition.observe(this.#form);\n  }\n\n  override disconnect(): void {\n    this.#timers.clearAll();\n    this.#pendingId = 0;\n    this.#composition.disconnect();\n    this.#form.removeAttribute(\"data-auto-submit-pending\");\n    this.#form.removeEventListener(\"turbo:submit-end\", this.#onSubmitEnd);\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.#composition.isComposing(event as InputEvent)) 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

@@ -13,25 +13,28 @@ import { Controller } from '@hotwired/stimulus';
  *     <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.
+ * The `image` and `fallback` targets are optional. A present `src` Value owns the
+ * current image's `src`, including an empty Value that explicitly clears it. When
+ * the Value is absent, a directly authored `<img src>` is used instead. Runtime
+ * Value changes, direct `src` changes, and target replacements all repaint.
+ *
+ * The accessible name lives on the container (`role="img"` + `aria-label`); the
+ * inner image and fallback are `aria-hidden` so assistive technology reads the
+ * name once in every visual state.
  *
  * @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.
+ * colour generation are out of scope: fallback content comes from markup. The
+ * `empty`, `loading`, `loaded`, and `error` phases are exposed on `data-state`.
+ * A native error from the current image dispatches `stimeo--avatar:error` with
+ * `{ src: string }`; reconnecting or reconciling an already-broken image is
+ * silent because no new failure event occurred.
  */
 declare class AvatarController extends Controller<HTMLElement> {
     #private;
     static targets: string[];
     static values: {
-        src: {
-            type: StringConstructor;
-            default: string;
-        };
+        src: StringConstructor;
     };
     static actions: readonly ["onError", "onLoad"];
     static events: readonly ["error"];
@@ -40,11 +43,29 @@ declare class AvatarController extends Controller<HTMLElement> {
     readonly hasImageTarget: boolean;
     readonly hasFallbackTarget: boolean;
     srcValue: string;
+    /** Starts retained-DOM observation and silently derives the current phase. */
     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;
+    /** Cancels asynchronous work while retaining the last materialized visual state. */
+    disconnect(): void;
+    /** Repaints when application code or a Turbo morph changes the source Value. */
+    srcValueChanged(): void;
+    /** Applies the current source and phase to an image inserted or replaced at runtime. */
+    imageTargetConnected(): void;
+    /** Returns attributes borrowed from an image that leaves this live avatar. */
+    imageTargetDisconnected(image: HTMLImageElement): void;
+    /** Applies the current phase to a fallback inserted or replaced at runtime. */
+    fallbackTargetConnected(): void;
+    /** Returns authored visibility when a fallback leaves this live avatar. */
+    fallbackTargetDisconnected(fallback: HTMLElement): void;
+    /** Reveals the current image after its native `load` event. */
+    onLoad(event: Event): void;
+    /**
+     * Reveals the fallback after the current image's native `error` event.
+     *
+     * Dispatches `stimeo--avatar:error` with `{ src: string }`, where `src` is
+     * the attempted attribute value. Empty/stale/detached image events are ignored.
+     */
+    onError(event: Event): void;
 }
 
 export { AvatarController };

package/dist/controllers/avatar_controller.js

@@ -1,63 +1,260 @@
 import { Controller } from '@hotwired/stimulus';
 
+// src/controllers/avatar_controller.ts
+
+// src/utils/attribute_lease.ts
+var AttributeLease = class {
+  #attribute;
+  #records = /* @__PURE__ */ new Map();
+  /** @param attribute - The attribute whose temporary values this lease owns. */
+  constructor(attribute) {
+    this.#attribute = attribute;
+  }
+  /** Writes or removes the leased attribute while preserving its authored value. */
+  write(element, value) {
+    const existing = this.#records.get(element);
+    if (existing) {
+      existing.written = value;
+    } else {
+      this.#records.set(element, {
+        original: element.getAttribute(this.#attribute),
+        written: value
+      });
+    }
+    this.#reflect(element, value);
+  }
+  /** Returns one lease without overwriting a value subsequently authored by a consumer. */
+  return(element) {
+    const record = this.#records.get(element);
+    if (!record) return;
+    this.#records.delete(element);
+    const stillOwned = element.getAttribute(this.#attribute) === record.written;
+    if (stillOwned) this.#reflect(element, record.original);
+  }
+  /** Reflects only a real value transition, avoiding self-triggered mutation work. */
+  #reflect(element, value) {
+    if (element.getAttribute(this.#attribute) === value) return;
+    if (value === null) element.removeAttribute(this.#attribute);
+    else element.setAttribute(this.#attribute, value);
+  }
+  /** Returns every outstanding lease using the same ownership check as {@link return}. */
+  returnAll() {
+    for (const element of Array.from(this.#records.keys())) this.return(element);
+  }
+};
+
+// src/utils/before_cache_reset.ts
+var BeforeCacheReset = class _BeforeCacheReset {
+  /** Every subscribed instance, iterated by the one shared document listener. */
+  static #subscribers = /* @__PURE__ */ new Set();
+  /** The shared listener; installed while at least one instance is subscribed. */
+  static #onBeforeCache = () => {
+    for (const subscriber of _BeforeCacheReset.#subscribers) subscriber.#rewind();
+  };
+  #rewind;
+  /** @param rewind - the pass that returns this controller's state to its initial form. */
+  constructor(rewind) {
+    this.#rewind = rewind;
+  }
+  /** Subscribes to `turbo:before-cache`; call from `connect()`. Idempotent. */
+  activate() {
+    const first = _BeforeCacheReset.#subscribers.size === 0;
+    _BeforeCacheReset.#subscribers.add(this);
+    if (first) {
+      document.addEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
+    }
+  }
+  /** Unsubscribes; call from `disconnect()`. Safe when never subscribed. */
+  deactivate() {
+    _BeforeCacheReset.#subscribers.delete(this);
+    if (_BeforeCacheReset.#subscribers.size > 0) return;
+    document.removeEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
+  }
+};
+
+// src/utils/microtask_coalescer.ts
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  /** @param run - the single reconciliation pass, invoked at most once per batch. */
+  constructor(run) {
+    this.#run = run;
+  }
+  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
+  activate() {
+    this.#active = true;
+  }
+  /** Closes the window and drops any pending pass; call from `disconnect()`. */
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */
+  schedule() {
+    if (!this.#active || this.#queued) return;
+    this.#queued = true;
+    const generation = this.#generation;
+    queueMicrotask(() => {
+      if (generation !== this.#generation || !this.#queued || !this.#active) return;
+      this.#queued = false;
+      this.#run();
+    });
+  }
+};
+
 // src/controllers/avatar_controller.ts
 var AvatarController = class extends Controller {
   static targets = ["image", "fallback"];
-  static values = {
-    src: { type: String, default: "" }
-  };
+  static values = { src: String };
   static actions = ["onError", "onLoad"];
   static events = ["error"];
+  /** Collapses one morph's Value, target, and direct-attribute signals into one pass. */
+  #reconcile = new MicrotaskCoalescer(() => this.#render());
+  /** Preserves directly-authored source and visibility while targets are controlled. */
+  #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
+  #src = new AttributeLease("src");
+  #imageHidden = new AttributeLease("hidden");
+  #fallbackHidden = new AttributeLease("hidden");
+  /** True only while target departure means ownership was actually relinquished. */
+  #connected = false;
+  /** Watches the non-Value render input used by the direct `<img src>` form. */
+  #srcObserver = new MutationObserver((records) => {
+    if (records.some((record) => this.hasImageTarget && record.target === this.imageTarget)) {
+      this.#reconcile.schedule();
+    }
+  });
+  /** Starts retained-DOM observation and silently derives the current phase. */
   connect() {
-    if (!this.hasImageTarget) {
-      this.#showFallback();
-      return;
+    this.#connected = true;
+    this.#reconcile.activate();
+    this.#beforeCache.activate();
+    this.#srcObserver.observe(this.element, {
+      attributes: true,
+      attributeFilter: ["src"],
+      subtree: true
+    });
+    this.#render();
+  }
+  /** Cancels asynchronous work while retaining the last materialized visual state. */
+  disconnect() {
+    this.#connected = false;
+    this.#reconcile.cancel();
+    this.#beforeCache.deactivate();
+    this.#srcObserver.disconnect();
+  }
+  /** Repaints when application code or a Turbo morph changes the source Value. */
+  srcValueChanged() {
+    this.#reconcile.schedule();
+  }
+  /** Applies the current source and phase to an image inserted or replaced at runtime. */
+  imageTargetConnected() {
+    this.#reconcile.schedule();
+  }
+  /** Returns attributes borrowed from an image that leaves this live avatar. */
+  imageTargetDisconnected(image) {
+    if (this.#connected) {
+      this.#src.return(image);
+      this.#imageHidden.return(image);
     }
-    if (this.srcValue) {
-      this.imageTarget.src = this.srcValue;
+    this.#reconcile.schedule();
+  }
+  /** Applies the current phase to a fallback inserted or replaced at runtime. */
+  fallbackTargetConnected() {
+    this.#reconcile.schedule();
+  }
+  /** Returns authored visibility when a fallback leaves this live avatar. */
+  fallbackTargetDisconnected(fallback) {
+    if (this.#connected) this.#fallbackHidden.return(fallback);
+    this.#reconcile.schedule();
+  }
+  /** Reveals the current image after its native `load` event. */
+  onLoad(event) {
+    const image = this.#eventImage(event);
+    if (!image) return;
+    if (!image.getAttribute("src")) {
+      this.#render();
+      return;
     }
-    const src = this.imageTarget.getAttribute("src");
+    this.#reflect("loaded");
+  }
+  /**
+   * Reveals the fallback after the current image's native `error` event.
+   *
+   * Dispatches `stimeo--avatar:error` with `{ src: string }`, where `src` is
+   * the attempted attribute value. Empty/stale/detached image events are ignored.
+   */
+  onError(event) {
+    const image = this.#eventImage(event);
+    if (!image) return;
+    const src = image.getAttribute("src");
     if (!src) {
-      this.#showFallback();
+      this.#render();
       return;
     }
-    if (this.imageTarget.complete && this.imageTarget.naturalWidth > 0) {
-      this.#showImage();
+    this.#reflect("error");
+    this.dispatch("error", { detail: { src } });
+  }
+  /**
+   * Materializes the phase from the final source/target DOM after one mutation batch.
+   *
+   * Cached success and failure are state reconstruction, not new load events, so
+   * this pass never dispatches the public `error` event.
+   *
+   * @stimeoRenderRoot
+   */
+  #render() {
+    if (!this.hasImageTarget) {
+      this.#reflect("empty");
+      return;
+    }
+    const image = this.imageTarget;
+    const src = this.#applySource(image);
+    if (!src) {
+      this.#reflect("empty");
       return;
     }
-    if (this.imageTarget.complete && this.imageTarget.naturalWidth === 0 && src) {
-      this.onError();
+    if (!image.complete) {
+      this.#reflect("loading");
       return;
     }
-    this.#enterLoading();
+    this.#reflect(image.naturalWidth > 0 ? "loaded" : "error");
   }
-  /** Reveals the image once it has loaded successfully. */
-  onLoad() {
-    this.#showImage();
+  /** Applies Value precedence and returns the effective raw `src` attribute. */
+  #applySource(image) {
+    if (!this.element.hasAttribute("data-stimeo--avatar-src-value")) {
+      this.#src.return(image);
+      return image.getAttribute("src");
+    }
+    const desired = this.srcValue.length > 0 ? this.srcValue : null;
+    if (image.getAttribute("src") !== desired) this.#src.write(image, desired);
+    return desired;
   }
-  /** 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 } });
+  /** Accepts an action only from the singular image target currently controlled. */
+  #eventImage(event) {
+    const candidate = event.currentTarget;
+    if (!(candidate instanceof HTMLImageElement)) return null;
+    if (!this.hasImageTarget || candidate !== this.imageTarget) return null;
+    return candidate;
+  }
+  /** Writes the visibility pair and public root state as one controller-owned output. */
+  #reflect(state) {
+    const showImage = state === "loading" || state === "loaded";
+    if (this.hasImageTarget) {
+      this.#imageHidden.write(this.imageTarget, showImage ? null : "");
+    }
+    if (this.hasFallbackTarget) {
+      this.#fallbackHidden.write(this.fallbackTarget, showImage ? "" : null);
+    }
+    this.element.setAttribute("data-state", state);
   }
-  /** 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");
+  /** Returns borrowed image and fallback semantics before Turbo snapshots the page. */
+  #rewindForCache() {
+    this.#src.returnAll();
+    this.#imageHidden.returnAll();
+    this.#fallbackHidden.returnAll();
   }
 };
 

package/dist/controllers/avatar_controller.js.map

@@ -1 +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"]}
+{"version":3,"sources":["../../src/utils/attribute_lease.ts","../../src/utils/before_cache_reset.ts","../../src/utils/microtask_coalescer.ts","../../src/controllers/avatar_controller.ts"],"names":[],"mappings":"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","file":"avatar_controller.js","sourcesContent":["/** One temporarily controlled attribute value and the authored value it displaced. */\ninterface AttributeLeaseRecord {\n  readonly original: string | null;\n  written: string | null;\n}\n\n/**\n * Temporarily controls one attribute across a changing set of elements.\n *\n * The first write remembers the authored value, including the distinction between\n * an absent attribute and an authored empty string. Returning a lease restores that\n * value only while the attribute still matches the controller's last write. If a\n * consumer changed it in the meantime, the consumer owns the new value and teardown\n * leaves it alone.\n *\n * A `null` write deliberately removes the attribute while retaining the lease. This\n * is useful for derived ARIA whose valid absence is itself controller state, such as\n * an unbounded `aria-valuemin` or a blank spinbutton's `aria-valuenow`.\n *\n * The lease has no lifecycle of its own, so it never subscribes to document events.\n * A consumer that must not let a derived value become the authored baseline of a\n * cached page returns its leases from its own `turbo:before-cache` rewind, where the\n * matching `disconnect()` also releases the subscription.\n */\nexport class AttributeLease<T extends Element = Element> {\n  readonly #attribute: string;\n  readonly #records = new Map<T, AttributeLeaseRecord>();\n\n  /** @param attribute - The attribute whose temporary values this lease owns. */\n  constructor(attribute: string) {\n    this.#attribute = attribute;\n  }\n\n  /** Writes or removes the leased attribute while preserving its authored value. */\n  write(element: T, value: string | null): void {\n    const existing = this.#records.get(element);\n    if (existing) {\n      existing.written = value;\n    } else {\n      this.#records.set(element, {\n        original: element.getAttribute(this.#attribute),\n        written: value,\n      });\n    }\n\n    this.#reflect(element, value);\n  }\n\n  /** Returns one lease without overwriting a value subsequently authored by a consumer. */\n  return(element: T): void {\n    const record = this.#records.get(element);\n    if (!record) return;\n    this.#records.delete(element);\n    const stillOwned = element.getAttribute(this.#attribute) === record.written;\n    if (stillOwned) this.#reflect(element, record.original);\n  }\n\n  /** Reflects only a real value transition, avoiding self-triggered mutation work. */\n  #reflect(element: T, value: string | null): void {\n    if (element.getAttribute(this.#attribute) === value) return;\n    if (value === null) element.removeAttribute(this.#attribute);\n    else element.setAttribute(this.#attribute, value);\n  }\n\n  /** Returns every outstanding lease using the same ownership check as {@link return}. */\n  returnAll(): void {\n    for (const element of Array.from(this.#records.keys())) this.return(element);\n  }\n}\n","/**\n * Runs a controller's \"return to the initial state\" pass just before Turbo\n * caches the page.\n *\n * **`disconnect()` cannot do this job, for two independent reasons.** Turbo\n * queues the clone from this event rather than taking it here, and the body swap\n * that runs the controller's `disconnect()` is queued separately — so which of\n * the two lands first is not something a controller can rely on, and a rewind\n * written in `disconnect()` may reach only the DOM being thrown away. In the\n * other direction, `disconnect()` also fires on an in-page move (Stimulus tears\n * down and reconnects the same element), where rewinding would wipe a\n * legitimately in-progress interaction — a spinner mid-load would vanish. One\n * timing is unreliable, the other is too eager; `turbo:before-cache` is the only\n * point that is exactly \"the page is about to be frozen\".\n *\n * Scope is the subscription only: registering on `activate()`, unregistering on\n * `deactivate()`, and one shared document listener no matter how many instances\n * are live. *What* to return to its initial state — which `data-state`, which\n * `hidden`, which `aria-busy` — stays in the controller, because no two\n * consumers answer it the same way (the `MicrotaskCoalescer` split).\n *\n * **Rewind state, not appearance.** The pass writes attributes the controller\n * itself owns; the visual result of those attributes is the consumer's CSS, and\n * a library that reached for style or class names would be guessing at markup\n * it does not own.\n *\n * Both entry points are idempotent, so the lifecycle hooks can call them\n * unconditionally: a second `activate()` does not double-subscribe and does not\n * make the callback run twice, and `deactivate()` on an instance that never\n * subscribed is a no-op.\n *\n * This file's own doc block is dropped from `dist`, but every member comment is\n * inlined into each consumer entry (`tsup` builds with `splitting: false`), so\n * rationale belongs here and only the contract belongs on the members.\n *\n * @example\n * ```ts\n * readonly #beforeCache = new BeforeCacheReset(() => this.#rewind());\n *\n * connect()    { this.#beforeCache.activate(); }\n * disconnect() { this.#beforeCache.deactivate(); }\n * ```\n */\nexport class BeforeCacheReset {\n  /** Every subscribed instance, iterated by the one shared document listener. */\n  static readonly #subscribers = new Set<BeforeCacheReset>();\n\n  /** The shared listener; installed while at least one instance is subscribed. */\n  static readonly #onBeforeCache = (): void => {\n    for (const subscriber of BeforeCacheReset.#subscribers) subscriber.#rewind();\n  };\n\n  readonly #rewind: () => void;\n\n  /** @param rewind - the pass that returns this controller's state to its initial form. */\n  constructor(rewind: () => void) {\n    this.#rewind = rewind;\n  }\n\n  /** Subscribes to `turbo:before-cache`; call from `connect()`. Idempotent. */\n  activate(): void {\n    const first = BeforeCacheReset.#subscribers.size === 0;\n    BeforeCacheReset.#subscribers.add(this);\n    if (first) {\n      document.addEventListener(\"turbo:before-cache\", BeforeCacheReset.#onBeforeCache);\n    }\n  }\n\n  /** Unsubscribes; call from `disconnect()`. Safe when never subscribed. */\n  deactivate(): void {\n    BeforeCacheReset.#subscribers.delete(this);\n    if (BeforeCacheReset.#subscribers.size > 0) return;\n    document.removeEventListener(\"turbo:before-cache\", BeforeCacheReset.#onBeforeCache);\n  }\n}\n","/**\n * Collapses many Stimulus lifecycle callbacks from one DOM mutation into a\n * single pass.\n *\n * Stimulus fires `<name>TargetConnected` / `Disconnected` once per element and\n * `<name>ValueChanged` once per changed attribute. Replacing a list of N options\n * or morphing several render Values therefore delivers N callbacks — but the\n * useful unit of work is \"reconcile against the resulting declarative input\",\n * once, after the batch has settled. Every controller with reconcilable targets\n * or render Values needs the same shape: a `queued` flag plus `queueMicrotask`.\n *\n * **A microtask is the right horizon, and the reason is specific.** Stimulus\n * drives these callbacks from a `MutationObserver`, whose own callback already\n * runs as a microtask with the whole batch in hand; scheduling one more lands\n * after the last sibling callback of that batch and still before paint or any\n * event handler. A timer would be later than it needs to be, and reconciling\n * synchronously would run once per element against a half-applied DOM.\n *\n * **The two guards are not the same guard.** Scheduling is refused before the\n * controller connects, and running is refused after it disconnects:\n *\n * - **Before `connect()`** — Stimulus delivers initial target and Value callbacks\n *   ahead of `connect()`. Reconciling there would compute output against a\n *   controller whose own state has not been initialised, and `connect()` is\n *   about to do a full pass anyway.\n * - **After `disconnect()`** — Stimulus fires a callback for **every** target\n *   during teardown, and a microtask queued just before it would otherwise run\n *   against a detached tree. {@link MicrotaskCoalescer.cancel} exists for the\n *   teardown path to drop the pending pass outright.\n *\n * Both guards are part of one contract here rather than something each consumer\n * has to remember separately.\n *\n * Scope is the scheduling only. *What* to reconcile — keep the surviving active\n * option, fall back to the next / previous / first visible one, rebuild derived\n * chips or hidden fields — stays in the controller, because no two consumers\n * answer it the same way.\n *\n * This file's own doc block is dropped from `dist`, but every member comment is\n * inlined into each consumer entry (`tsup` builds with `splitting: false`), so\n * rationale belongs here and only the contract belongs on the members.\n *\n * @example\n * ```ts\n * readonly #reconcile = new MicrotaskCoalescer(() => this.#reconcileOptions());\n *\n * connect()    { this.#reconcile.activate(); }\n * disconnect() { this.#reconcile.cancel(); }\n *\n * optionTargetConnected()    { this.#reconcile.schedule(); }\n * optionTargetDisconnected() { this.#reconcile.schedule(); }\n * ```\n */\nexport class MicrotaskCoalescer {\n  readonly #run: () => void;\n  #queued = false;\n  #active = false;\n  #generation = 0;\n\n  /** @param run - the single reconciliation pass, invoked at most once per batch. */\n  constructor(run: () => void) {\n    this.#run = run;\n  }\n\n  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */\n  activate(): void {\n    this.#active = true;\n  }\n\n  /** Closes the window and drops any pending pass; call from `disconnect()`. */\n  cancel(): void {\n    this.#active = false;\n    this.#queued = false;\n    this.#generation += 1;\n  }\n\n  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */\n  schedule(): void {\n    if (!this.#active || this.#queued) return;\n    this.#queued = true;\n    const generation = this.#generation;\n    queueMicrotask(() => {\n      // A cancelled callback must not consume a pass queued after reconnect.\n      if (generation !== this.#generation || !this.#queued || !this.#active) return;\n      this.#queued = false;\n      this.#run();\n    });\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { AttributeLease } from \"../utils/attribute_lease\";\nimport { BeforeCacheReset } from \"../utils/before_cache_reset\";\nimport { MicrotaskCoalescer } from \"../utils/microtask_coalescer\";\n\n/** Public rendering phases exposed through the root's `data-state`. */\ntype AvatarState = \"empty\" | \"loading\" | \"loaded\" | \"error\";\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 * The `image` and `fallback` targets are optional. A present `src` Value owns the\n * current image's `src`, including an empty Value that explicitly clears it. When\n * the Value is absent, a directly authored `<img src>` is used instead. Runtime\n * Value changes, direct `src` changes, and target replacements all repaint.\n *\n * The accessible name lives on the container (`role=\"img\"` + `aria-label`); the\n * inner image and fallback are `aria-hidden` so assistive technology reads the\n * name once in every visual state.\n *\n * @remarks\n * Behavior only — shape, size, and colour are the consumer's CSS. Initials or\n * colour generation are out of scope: fallback content comes from markup. The\n * `empty`, `loading`, `loaded`, and `error` phases are exposed on `data-state`.\n * A native error from the current image dispatches `stimeo--avatar:error` with\n * `{ src: string }`; reconnecting or reconciling an already-broken image is\n * silent because no new failure event occurred.\n */\nexport class AvatarController extends Controller<HTMLElement> {\n  static override targets = [\"image\", \"fallback\"];\n  static override values = { src: String };\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  declare srcValue: string;\n\n  /** Collapses one morph's Value, target, and direct-attribute signals into one pass. */\n  readonly #reconcile = new MicrotaskCoalescer(() => this.#render());\n  /** Preserves directly-authored source and visibility while targets are controlled. */\n  readonly #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());\n  readonly #src = new AttributeLease<HTMLImageElement>(\"src\");\n  readonly #imageHidden = new AttributeLease<HTMLImageElement>(\"hidden\");\n  readonly #fallbackHidden = new AttributeLease<HTMLElement>(\"hidden\");\n  /** True only while target departure means ownership was actually relinquished. */\n  #connected = false;\n  /** Watches the non-Value render input used by the direct `<img src>` form. */\n  readonly #srcObserver = new MutationObserver((records) => {\n    if (records.some((record) => this.hasImageTarget && record.target === this.imageTarget)) {\n      this.#reconcile.schedule();\n    }\n  });\n\n  /** Starts retained-DOM observation and silently derives the current phase. */\n  override connect(): void {\n    this.#connected = true;\n    this.#reconcile.activate();\n    this.#beforeCache.activate();\n    this.#srcObserver.observe(this.element, {\n      attributes: true,\n      attributeFilter: [\"src\"],\n      subtree: true,\n    });\n    this.#render();\n  }\n\n  /** Cancels asynchronous work while retaining the last materialized visual state. */\n  override disconnect(): void {\n    this.#connected = false;\n    this.#reconcile.cancel();\n    this.#beforeCache.deactivate();\n    this.#srcObserver.disconnect();\n  }\n\n  /** Repaints when application code or a Turbo morph changes the source Value. */\n  srcValueChanged(): void {\n    this.#reconcile.schedule();\n  }\n\n  /** Applies the current source and phase to an image inserted or replaced at runtime. */\n  imageTargetConnected(): void {\n    this.#reconcile.schedule();\n  }\n\n  /** Returns attributes borrowed from an image that leaves this live avatar. */\n  imageTargetDisconnected(image: HTMLImageElement): void {\n    if (this.#connected) {\n      this.#src.return(image);\n      this.#imageHidden.return(image);\n    }\n    this.#reconcile.schedule();\n  }\n\n  /** Applies the current phase to a fallback inserted or replaced at runtime. */\n  fallbackTargetConnected(): void {\n    this.#reconcile.schedule();\n  }\n\n  /** Returns authored visibility when a fallback leaves this live avatar. */\n  fallbackTargetDisconnected(fallback: HTMLElement): void {\n    if (this.#connected) this.#fallbackHidden.return(fallback);\n    this.#reconcile.schedule();\n  }\n\n  /** Reveals the current image after its native `load` event. */\n  onLoad(event: Event): void {\n    const image = this.#eventImage(event);\n    if (!image) return;\n    if (!image.getAttribute(\"src\")) {\n      this.#render();\n      return;\n    }\n    this.#reflect(\"loaded\");\n  }\n\n  /**\n   * Reveals the fallback after the current image's native `error` event.\n   *\n   * Dispatches `stimeo--avatar:error` with `{ src: string }`, where `src` is\n   * the attempted attribute value. Empty/stale/detached image events are ignored.\n   */\n  onError(event: Event): void {\n    const image = this.#eventImage(event);\n    if (!image) return;\n    const src = image.getAttribute(\"src\");\n    if (!src) {\n      this.#render();\n      return;\n    }\n    this.#reflect(\"error\");\n    this.dispatch(\"error\", { detail: { src } });\n  }\n\n  /**\n   * Materializes the phase from the final source/target DOM after one mutation batch.\n   *\n   * Cached success and failure are state reconstruction, not new load events, so\n   * this pass never dispatches the public `error` event.\n   *\n   * @stimeoRenderRoot\n   */\n  #render(): void {\n    if (!this.hasImageTarget) {\n      this.#reflect(\"empty\");\n      return;\n    }\n\n    const image = this.imageTarget;\n    const src = this.#applySource(image);\n    if (!src) {\n      this.#reflect(\"empty\");\n      return;\n    }\n    if (!image.complete) {\n      this.#reflect(\"loading\");\n      return;\n    }\n    this.#reflect(image.naturalWidth > 0 ? \"loaded\" : \"error\");\n  }\n\n  /** Applies Value precedence and returns the effective raw `src` attribute. */\n  #applySource(image: HTMLImageElement): string | null {\n    if (!this.element.hasAttribute(\"data-stimeo--avatar-src-value\")) {\n      this.#src.return(image);\n      return image.getAttribute(\"src\");\n    }\n\n    const desired = this.srcValue.length > 0 ? this.srcValue : null;\n    if (image.getAttribute(\"src\") !== desired) this.#src.write(image, desired);\n    return desired;\n  }\n\n  /** Accepts an action only from the singular image target currently controlled. */\n  #eventImage(event: Event): HTMLImageElement | null {\n    const candidate = event.currentTarget;\n    if (!(candidate instanceof HTMLImageElement)) return null;\n    if (!this.hasImageTarget || candidate !== this.imageTarget) return null;\n    return candidate;\n  }\n\n  /** Writes the visibility pair and public root state as one controller-owned output. */\n  #reflect(state: AvatarState): void {\n    const showImage = state === \"loading\" || state === \"loaded\";\n    if (this.hasImageTarget) {\n      this.#imageHidden.write(this.imageTarget, showImage ? null : \"\");\n    }\n    if (this.hasFallbackTarget) {\n      this.#fallbackHidden.write(this.fallbackTarget, showImage ? \"\" : null);\n    }\n    this.element.setAttribute(\"data-state\", state);\n  }\n  /** Returns borrowed image and fallback semantics before Turbo snapshots the page. */\n  #rewindForCache(): void {\n    this.#src.returnAll();\n    this.#imageHidden.returnAll();\n    this.#fallbackHidden.returnAll();\n  }\n}\n"]}

package/dist/controllers/breadcrumb_controller.d.ts

@@ -25,6 +25,8 @@ import { Controller } from '@hotwired/stimulus';
  * author-marked middle items behind a disclosure (`…`) button, which expands
  * them back on demand.
  *
+ * `toggle` dispatches `{ expanded: boolean }`.
+ *
  * @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),