stimeo-ui 0.5.0 → 0.7.0

package/dist/controllers/form_field_controller.js

@@ -2,6 +2,17 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/form_field_controller.ts
 
+// src/utils/announce.ts
+function announce(message, options = {}) {
+  const text = message.trim();
+  if (text.length === 0) return;
+  window.dispatchEvent(
+    new CustomEvent("stimeo--announcer:announce", {
+      detail: { message: text, assertive: options.assertive === true }
+    })
+  );
+}
+
 // src/utils/aria_ids.ts
 var counter = 0;
 function uniqueId(prefix = "stimeo") {
@@ -19,7 +30,111 @@ function ensureId(element, prefix = "stimeo") {
   return id;
 }
 
+// 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/form_field_controller.ts
+var OBSERVED_ATTRIBUTES = ["hidden", "id"];
 var FormFieldController = class _FormFieldController extends Controller {
   static targets = ["control", "description", "error"];
   static values = {
@@ -29,31 +144,85 @@ var FormFieldController = class _FormFieldController extends Controller {
   static events = ["validate"];
   /** Root attribute (CSS hook) reflecting the invalid state. */
   static #INVALID_ATTR = "data-stimeo--form-field-invalid";
-  /**
-   * `aria-describedby` tokens the consumer set on the control that the
-   * controller does not own. Captured once so composition never clobbers them.
-   */
+  /** Collapses one target/morph batch into one silent ARIA reconciliation. */
+  #reconcile = new MicrotaskCoalescer(() => this.#reconcileDom());
+  /** ARIA ownership is scoped to the current singular control target. */
+  #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
+  #ariaDescribedBy = new AttributeLease("aria-describedby");
+  #ariaErrorMessage = new AttributeLease("aria-errormessage");
+  #ariaInvalid = new AttributeLease("aria-invalid");
+  /** Watches retained target ids, error visibility, and error content. */
+  #observer = new MutationObserver((records) => {
+    if (records.some((record) => this.#isRelevantMutation(record))) {
+      this.#reconcile.schedule();
+    }
+  });
+  #activeControl = null;
   #baseDescribedBy = [];
-  /** Wires ids, captures consumer tokens, and reflects any initial error state. */
+  #explicitInvalid = false;
+  #initialized = false;
+  /** Wires the initial graph and starts retained-target reconciliation. */
   connect() {
-    for (const description of this.descriptionTargets) {
-      ensureId(description, "stimeo--form-field-desc");
-    }
-    for (const error of this.errorTargets) {
-      ensureId(error, "stimeo--form-field-error");
+    this.#reconcile.activate();
+    this.#ensureAssociationIds();
+    this.#beforeCache.activate();
+    if (!this.#initialized) {
+      this.#explicitInvalid = this.element.hasAttribute(_FormFieldController.#INVALID_ATTR) && this.#shownErrors().length === 0;
+      this.#initialized = true;
     }
-    this.#baseDescribedBy = this.#externalDescribedByTokens();
-    this.#reflect();
+    this.#reconcileDom();
+    this.#observer.observe(this.element, {
+      attributes: true,
+      attributeFilter: OBSERVED_ATTRIBUTES,
+      characterData: true,
+      childList: true,
+      subtree: true
+    });
+  }
+  /** Releases observers, queued work, and ARIA borrowed on the current control. */
+  disconnect() {
+    this.#reconcile.cancel();
+    this.#observer.disconnect();
+    this.#beforeCache.deactivate();
+    this.#activeControl && this.#releaseControl(this.#activeControl);
+  }
+  /** Reconciles a control inserted or replaced at runtime. */
+  controlTargetConnected() {
+    this.#reconcile.schedule();
+  }
+  /** Schedules restoration of authored ARIA when a control leaves this field. */
+  controlTargetDisconnected() {
+    this.#reconcile.schedule();
+  }
+  /** Reconciles a description inserted or replaced at runtime. */
+  descriptionTargetConnected() {
+    this.#reconcile.schedule();
+  }
+  /** Removes a departed description from the control's association graph. */
+  descriptionTargetDisconnected() {
+    this.#reconcile.schedule();
+  }
+  /** Reconciles an error region inserted or replaced at runtime. */
+  errorTargetConnected() {
+    this.#reconcile.schedule();
+  }
+  /** Removes a departed error from invalid state and the association graph. */
+  errorTargetDisconnected() {
+    this.#reconcile.schedule();
   }
   /**
    * Marks the field invalid and shows the error message. Bound via `data-action`
    * (`#setError`) or callable directly.
    *
+   * A non-empty shown message is announced exactly once through the shared
+   * assertive announcer. Initial/server reconciliation is deliberately silent.
+   *
    * @param arg - Either the message string, or the action event whose
    *   `data-stimeo--form-field-message-param` supplies it. When no message is
    *   resolvable, any already-populated error targets are simply (re)shown.
+   * @param options - Programmatic overrides. Stimulus actions use the Values.
    */
-  setError(arg) {
+  setError(arg, options = {}) {
     const message = this.#resolveMessage(arg);
     if (message !== null && this.hasErrorTarget) {
       this.errorTargets[0]?.replaceChildren(document.createTextNode(message));
@@ -61,70 +230,86 @@ var FormFieldController = class _FormFieldController extends Controller {
     for (const error of this.errorTargets) {
       error.hidden = (error.textContent ?? "").trim() === "";
     }
-    this.#reflect(true);
-    this.dispatch("validate", { detail: { valid: false, message: this.#shownMessage() } });
-    if (this.focusOnErrorValue && this.hasControlTarget) {
-      this.controlTarget.focus();
-    }
+    this.#explicitInvalid = true;
+    this.#reconcileDom();
+    const shownMessage = this.#shownMessage();
+    const detail = { valid: false, message: shownMessage };
+    this.dispatch("validate", { detail });
+    announce(shownMessage, { assertive: true });
+    if (options.focus ?? this.focusOnErrorValue) this.#activeControl?.focus();
   }
   /**
    * Clears the error: empties and hides every error target and marks the field
    * valid. Bound via `data-action` (`#clearError`) or callable directly.
+   *
+   * Clearing is silent: the visual/ARIA state and validation event are sufficient,
+   * while success wording remains an explicit consumer announcement.
    */
   clearError() {
     for (const error of this.errorTargets) {
       error.replaceChildren();
       error.hidden = true;
     }
-    this.#reflect();
-    this.dispatch("validate", { detail: { valid: true, message: "" } });
+    this.#explicitInvalid = false;
+    this.#reconcileDom();
+    const detail = { valid: true, message: "" };
+    this.dispatch("validate", { detail });
   }
   /**
-   * Synchronizes the control's ARIA wiring and the root CSS hook from the current
-   * error targets. Idempotent, so it is safe to call on connect and after any
-   * change (and survives Turbo morphing).
-   *
-   * @param force - When `true`, the field is marked invalid regardless of whether
-   *   a (visible, non-empty) error region exists. {@link setError} passes this so
-   *   the invalid state holds even with no error target; derivation from the DOM
-   *   (connect / {@link clearError}) leaves it `false`.
+   * Rebuilds ids and derived ARIA from the settled target graph without reporting
+   * a user validation action.
    */
-  #reflect(force = false) {
+  #reconcileDom() {
+    this.#ensureAssociationIds();
+    this.#adoptCurrentControl();
     const shown = this.#shownErrors();
-    const invalid = force || shown.length > 0;
-    if (invalid) {
-      this.element.setAttribute(_FormFieldController.#INVALID_ATTR, "");
-    } else {
-      this.element.removeAttribute(_FormFieldController.#INVALID_ATTR);
+    const invalid = this.#explicitInvalid || shown.length > 0;
+    this.element.toggleAttribute(_FormFieldController.#INVALID_ATTR, invalid);
+    const control = this.#activeControl;
+    if (!control) return;
+    this.#ariaInvalid.write(control, invalid ? "true" : "false");
+    const primaryErrorId = shown[0]?.id ?? null;
+    this.#ariaErrorMessage.write(control, primaryErrorId);
+    const associationIds = this.#orderedElements([...this.descriptionTargets, ...shown]).map(
+      (element) => element.id
+    );
+    const describedBy = this.#uniqueTokens([...this.#baseDescribedBy, ...associationIds]);
+    this.#ariaDescribedBy.write(control, describedBy.length > 0 ? describedBy.join(" ") : null);
+  }
+  /** Assigns stable ids before either capture or reflection uses them. */
+  #ensureAssociationIds() {
+    for (const description of this.descriptionTargets) {
+      ensureId(description, "stimeo--form-field-desc");
     }
-    if (!this.hasControlTarget) return;
-    const control = this.controlTarget;
-    control.setAttribute("aria-invalid", invalid ? "true" : "false");
-    const errorIds = shown.map((error) => error.id);
-    const primaryErrorId = errorIds[0];
-    if (primaryErrorId) {
-      control.setAttribute("aria-errormessage", primaryErrorId);
-    } else {
-      control.removeAttribute("aria-errormessage");
+    for (const error of this.errorTargets) {
+      ensureId(error, "stimeo--form-field-error");
     }
-    const describedBy = [
-      ...this.#baseDescribedBy,
-      ...this.descriptionTargets.map((description) => description.id),
-      ...errorIds
-    ];
-    if (describedBy.length > 0) {
-      control.setAttribute("aria-describedby", describedBy.join(" "));
-    } else {
-      control.removeAttribute("aria-describedby");
+  }
+  /** Switches ARIA ownership when the singular current control target changes. */
+  #adoptCurrentControl() {
+    const next = this.hasControlTarget ? this.controlTarget : null;
+    if (next === this.#activeControl) return;
+    this.#activeControl && this.#releaseControl(this.#activeControl);
+    this.#activeControl = next;
+    this.#baseDescribedBy = next ? this.#externalDescribedByTokens(next) : [];
+  }
+  /** Restores one departed control without overwriting later consumer edits. */
+  #releaseControl(control) {
+    this.#ariaDescribedBy.return(control);
+    this.#ariaErrorMessage.return(control);
+    this.#ariaInvalid.return(control);
+    if (control === this.#activeControl) {
+      this.#activeControl = null;
+      this.#baseDescribedBy = [];
     }
   }
-  /** Error targets currently visible and non-empty. */
+  /** Error targets currently visible and non-empty, in document order. */
   #shownErrors() {
-    return this.errorTargets.filter(
-      (error) => !error.hidden && (error.textContent ?? "").trim() !== ""
+    return this.#orderedElements(
+      this.errorTargets.filter((error) => !error.hidden && (error.textContent ?? "").trim() !== "")
     );
   }
-  /** Text of the first shown error, for the `validate` event detail. */
+  /** Text of the first shown error, for validation detail and announcement. */
   #shownMessage() {
     return (this.#shownErrors()[0]?.textContent ?? "").trim();
   }
@@ -135,17 +320,50 @@ var FormFieldController = class _FormFieldController extends Controller {
     return typeof message === "string" ? message : null;
   }
   /**
-   * Tokens already in the control's `aria-describedby` that are not ids of this
-   * controller's own description/error targets.
+   * Tokens authored on a newly adopted control, excluding ids this controller
+   * owns through its current description/error targets.
    */
-  #externalDescribedByTokens() {
-    if (!this.hasControlTarget) return [];
+  #externalDescribedByTokens(control) {
     const owned = /* @__PURE__ */ new Set([
       ...this.descriptionTargets.map((description) => description.id),
       ...this.errorTargets.map((error) => error.id)
     ]);
-    const existing = this.controlTarget.getAttribute("aria-describedby") ?? "";
-    return existing.split(/\s+/).filter((token) => token.length > 0 && !owned.has(token));
+    const existing = control.getAttribute("aria-describedby") ?? "";
+    return this.#uniqueTokens(
+      existing.split(/\s+/).filter((token) => token.length > 0 && !owned.has(token))
+    );
+  }
+  /** Deduplicates ARIA tokens without disturbing their first occurrence. */
+  #uniqueTokens(tokens) {
+    const seen = /* @__PURE__ */ new Set();
+    return tokens.filter((token) => {
+      if (token.length === 0 || seen.has(token)) return false;
+      seen.add(token);
+      return true;
+    });
+  }
+  /** Returns unique current targets in DOM order before serializing IDREF lists. */
+  #orderedElements(elements) {
+    const candidates = new Set(elements);
+    return [this.element, ...this.element.querySelectorAll("*")].filter(
+      (element) => candidates.has(element)
+    );
+  }
+  /** Whether one retained-node mutation can alter this controller's derived state. */
+  #isRelevantMutation(record) {
+    const target = record.target;
+    if (record.type === "attributes") {
+      if (record.attributeName === "hidden")
+        return this.errorTargets.includes(target);
+      return record.attributeName === "id" && [...this.descriptionTargets, ...this.errorTargets].includes(target);
+    }
+    return this.errorTargets.some((error) => error === target || error.contains(target));
+  }
+  /** Returns borrowed control ARIA before Turbo snapshots the page. */
+  #rewindForCache() {
+    this.#ariaDescribedBy.returnAll();
+    this.#ariaErrorMessage.returnAll();
+    this.#ariaInvalid.returnAll();
   }
 };
 

package/dist/controllers/form_field_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/aria_ids.ts","../../src/controllers/form_field_controller.ts"],"names":[],"mappings":"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","file":"form_field_controller.js","sourcesContent":["/**\n * Minimal id primitives for wiring ARIA relationships.\n *\n * Accessible relationships such as `aria-describedby`, `aria-errormessage`,\n * `aria-labelledby`, and `aria-activedescendant` reference their targets by DOM\n * `id`. When a controller must establish such a relationship but the consumer's\n * markup left the target without an `id`, it needs to mint one that is stable for\n * the page's lifetime and guaranteed not to collide with another generated id.\n *\n * These helpers own *only* id generation/assignment. The linking policy (which\n * attribute, what order, when to add or remove it) stays in each controller —\n * this deliberately avoids a premature generic \"ARIA linker\" abstraction.\n */\n\n/**\n * Monotonic counter backing {@link uniqueId}. Module-scoped so every generated\n * id is unique across all controller instances sharing this module in a document.\n */\nlet counter = 0;\n\n/**\n * Returns a unique, DOM-id-safe string of the form `` `${prefix}-${n}` `` where\n * `n` increases on each call.\n *\n * The counter alone guarantees uniqueness against other *generated* ids, but a\n * consumer-authored element could already own `` `${prefix}-${n}` ``. When a\n * `document` is available the candidate is therefore advanced until no element\n * with that id exists, so a generated id never collides with author markup\n * either — the minimal \"id registry\" guarantee these helpers exist to provide.\n *\n * @param prefix - Leading segment of the id (e.g. a controller's identifier).\n *   Defaults to `\"stimeo\"`.\n */\nexport function uniqueId(prefix = \"stimeo\"): string {\n  let candidate: string;\n  do {\n    counter += 1;\n    candidate = `${prefix}-${counter}`;\n  } while (typeof document !== \"undefined\" && document.getElementById(candidate) !== null);\n  return candidate;\n}\n\n/**\n * Returns `element`'s existing `id`, or assigns it a freshly generated\n * {@link uniqueId} (with the given `prefix`) and returns that. Idempotent: an\n * element that already has an id keeps it, so consumer-authored ids are never\n * overwritten.\n *\n * @param element - The element to read or stamp an `id` onto.\n * @param prefix - Prefix forwarded to {@link uniqueId} when one must be generated.\n * @returns The element's id (existing or newly assigned).\n */\nexport function ensureId(element: Element, prefix = \"stimeo\"): string {\n  if (element.id) return element.id;\n  const id = uniqueId(prefix);\n  element.id = id;\n  return id;\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { ensureId } from \"../utils/aria_ids\";\n\n/** Stimulus action params understood by {@link FormFieldController.setError}. */\ninterface SetErrorParams {\n  /** The error message to display. */\n  message?: string;\n}\n\n/** An action event carrying Stimulus `data-*-param` values. */\ntype ActionEvent = Event & { params?: SetErrorParams };\n\n/**\n * Headless, accessible form-field association behavior.\n *\n * Markup contract (identifier: `stimeo--form-field`):\n *   <div data-controller=\"stimeo--form-field\">\n *     <label for=\"email\">Email</label>\n *     <input id=\"email\" type=\"email\" aria-invalid=\"false\"\n *            data-stimeo--form-field-target=\"control\" />\n *     <p data-stimeo--form-field-target=\"description\">We'll send a confirmation.</p>\n *     <p role=\"alert\" hidden data-stimeo--form-field-target=\"error\"></p>\n *   </div>\n *\n * Not an APG widget pattern — this is the wiring substrate behind form controls:\n * it supports **Name, Role, Value** (WCAG 4.1.2) and **error identification**\n * (3.3.1 / 4.1.3) by composing the control's `aria-describedby`, toggling\n * `aria-invalid`, and pointing `aria-errormessage` at the live error region.\n *\n * @remarks\n * Behavior only — it sets semantic attributes and the `hidden` state of the\n * error region; it never validates input (the consumer / server decides) and\n * never styles. The error target should carry `role=\"alert\"` (or an\n * `aria-live` region) so a newly shown message is announced without moving focus.\n *\n * Behavior provided:\n * - On connect, assigns ids to description/error targets and composes the\n *   control's `aria-describedby` from them (preserving any pre-existing tokens).\n * - Reflects server-rendered errors: an error target that is already visible and\n *   non-empty at connect puts the field into the invalid state (progressive\n *   enhancement).\n * - {@link setError} / {@link clearError} drive the invalid state at runtime and\n *   dispatch `stimeo--form-field:validate`.\n */\nexport class FormFieldController extends Controller<HTMLElement> {\n  static override targets = [\"control\", \"description\", \"error\"];\n  static override values = {\n    focusOnError: { type: Boolean, default: false },\n  };\n  static actions = [\"clearError\", \"setError\"] as const;\n  static events = [\"validate\"] as const;\n\n  declare readonly controlTarget: HTMLElement;\n  declare readonly hasControlTarget: boolean;\n  declare readonly descriptionTargets: HTMLElement[];\n  declare readonly errorTargets: HTMLElement[];\n  declare readonly hasErrorTarget: boolean;\n  declare focusOnErrorValue: boolean;\n\n  /** Root attribute (CSS hook) reflecting the invalid state. */\n  static readonly #INVALID_ATTR = \"data-stimeo--form-field-invalid\";\n\n  /**\n   * `aria-describedby` tokens the consumer set on the control that the\n   * controller does not own. Captured once so composition never clobbers them.\n   */\n  #baseDescribedBy: string[] = [];\n\n  /** Wires ids, captures consumer tokens, and reflects any initial error state. */\n  override connect(): void {\n    for (const description of this.descriptionTargets) {\n      ensureId(description, \"stimeo--form-field-desc\");\n    }\n    for (const error of this.errorTargets) {\n      ensureId(error, \"stimeo--form-field-error\");\n    }\n    this.#baseDescribedBy = this.#externalDescribedByTokens();\n    this.#reflect();\n  }\n\n  /**\n   * Marks the field invalid and shows the error message. Bound via `data-action`\n   * (`#setError`) or callable directly.\n   *\n   * @param arg - Either the message string, or the action event whose\n   *   `data-stimeo--form-field-message-param` supplies it. When no message is\n   *   resolvable, any already-populated error targets are simply (re)shown.\n   */\n  setError(arg?: string | ActionEvent): void {\n    const message = this.#resolveMessage(arg);\n    if (message !== null && this.hasErrorTarget) {\n      this.errorTargets[0]?.replaceChildren(document.createTextNode(message));\n    }\n    for (const error of this.errorTargets) {\n      error.hidden = (error.textContent ?? \"\").trim() === \"\";\n    }\n    // setError is an explicit invalid request: mark invalid even when the field\n    // has no error region (only `control` is required), so the DOM invalid state\n    // never disagrees with the dispatched `valid: false`.\n    this.#reflect(true);\n    this.dispatch(\"validate\", { detail: { valid: false, message: this.#shownMessage() } });\n    if (this.focusOnErrorValue && this.hasControlTarget) {\n      this.controlTarget.focus();\n    }\n  }\n\n  /**\n   * Clears the error: empties and hides every error target and marks the field\n   * valid. Bound via `data-action` (`#clearError`) or callable directly.\n   */\n  clearError(): void {\n    for (const error of this.errorTargets) {\n      error.replaceChildren();\n      error.hidden = true;\n    }\n    this.#reflect();\n    this.dispatch(\"validate\", { detail: { valid: true, message: \"\" } });\n  }\n\n  /**\n   * Synchronizes the control's ARIA wiring and the root CSS hook from the current\n   * error targets. Idempotent, so it is safe to call on connect and after any\n   * change (and survives Turbo morphing).\n   *\n   * @param force - When `true`, the field is marked invalid regardless of whether\n   *   a (visible, non-empty) error region exists. {@link setError} passes this so\n   *   the invalid state holds even with no error target; derivation from the DOM\n   *   (connect / {@link clearError}) leaves it `false`.\n   */\n  #reflect(force = false): void {\n    const shown = this.#shownErrors();\n    const invalid = force || shown.length > 0;\n\n    if (invalid) {\n      this.element.setAttribute(FormFieldController.#INVALID_ATTR, \"\");\n    } else {\n      this.element.removeAttribute(FormFieldController.#INVALID_ATTR);\n    }\n\n    if (!this.hasControlTarget) return;\n    const control = this.controlTarget;\n    control.setAttribute(\"aria-invalid\", invalid ? \"true\" : \"false\");\n\n    const errorIds = shown.map((error) => error.id);\n    // aria-errormessage references a single error element (the widely-supported\n    // IDREF form); any additional errors stay in aria-describedby below.\n    const primaryErrorId = errorIds[0];\n    if (primaryErrorId) {\n      control.setAttribute(\"aria-errormessage\", primaryErrorId);\n    } else {\n      control.removeAttribute(\"aria-errormessage\");\n    }\n\n    // Compose describedby: consumer tokens, then descriptions, then shown errors\n    // (so legacy AT that ignore aria-errormessage still read the error).\n    const describedBy = [\n      ...this.#baseDescribedBy,\n      ...this.descriptionTargets.map((description) => description.id),\n      ...errorIds,\n    ];\n    if (describedBy.length > 0) {\n      control.setAttribute(\"aria-describedby\", describedBy.join(\" \"));\n    } else {\n      control.removeAttribute(\"aria-describedby\");\n    }\n  }\n\n  /** Error targets currently visible and non-empty. */\n  #shownErrors(): HTMLElement[] {\n    return this.errorTargets.filter(\n      (error) => !error.hidden && (error.textContent ?? \"\").trim() !== \"\",\n    );\n  }\n\n  /** Text of the first shown error, for the `validate` event detail. */\n  #shownMessage(): string {\n    return (this.#shownErrors()[0]?.textContent ?? \"\").trim();\n  }\n\n  /** Resolves a message from a string argument or an action event's params. */\n  #resolveMessage(arg?: string | ActionEvent): string | null {\n    if (typeof arg === \"string\") return arg;\n    const message = arg?.params?.message;\n    return typeof message === \"string\" ? message : null;\n  }\n\n  /**\n   * Tokens already in the control's `aria-describedby` that are not ids of this\n   * controller's own description/error targets.\n   */\n  #externalDescribedByTokens(): string[] {\n    if (!this.hasControlTarget) return [];\n    const owned = new Set([\n      ...this.descriptionTargets.map((description) => description.id),\n      ...this.errorTargets.map((error) => error.id),\n    ]);\n    const existing = this.controlTarget.getAttribute(\"aria-describedby\") ?? \"\";\n    return existing.split(/\\s+/).filter((token) => token.length > 0 && !owned.has(token));\n  }\n}\n"]}
+{"version":3,"sources":["../../src/utils/announce.ts","../../src/utils/aria_ids.ts","../../src/utils/attribute_lease.ts","../../src/utils/before_cache_reset.ts","../../src/utils/microtask_coalescer.ts","../../src/controllers/form_field_controller.ts"],"names":[],"mappings":"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","file":"form_field_controller.js","sourcesContent":["/**\n * Sends one message to the page's shared `stimeo--announcer`.\n *\n * A component that has to reach assistive tech does not carry a live region of its\n * own: a region only announces what changes *after* assistive tech already knows\n * about it, which a region that appears (or is un-hidden) with its message cannot\n * satisfy. The one region that can is the announcer sitting in the page from the\n * start, so state changes are handed to it as an event and it does the reading.\n *\n * The event goes to `window` because the announcer is usually a sibling high in the\n * document rather than an ancestor of the component dispatching it.\n *\n * Wording comes from the consumer — the library ships no English strings — so an\n * empty message is silently dropped and nothing is announced.\n *\n * @example\n * ```ts\n * announce(this.announceTextValue, { assertive: false });\n * ```\n */\nexport function announce(message: string, options: { assertive?: boolean } = {}): void {\n  const text = message.trim();\n  if (text.length === 0) return;\n  window.dispatchEvent(\n    new CustomEvent(\"stimeo--announcer:announce\", {\n      detail: { message: text, assertive: options.assertive === true },\n    }),\n  );\n}\n\n/**\n * Fills `{name}` placeholders in an announcement template from `values`.\n *\n * The same substitution the value-text templates use, so a consumer writes\n * `\"{percent}% complete\"` in one attribute and gets the same rules everywhere. A\n * placeholder with no matching entry is left as authored rather than blanked, which\n * keeps a typo visible instead of silently swallowing the word.\n */\nexport function fillTemplate(template: string, values: Record<string, string | number>): string {\n  return template.replace(/\\{([a-zA-Z][a-zA-Z0-9]*)\\}/g, (match, name: string) => {\n    const replacement = values[name];\n    return replacement === undefined ? match : String(replacement);\n  });\n}\n","/**\n * Minimal id primitives for wiring ARIA relationships.\n *\n * Accessible relationships such as `aria-describedby`, `aria-errormessage`,\n * `aria-labelledby`, and `aria-activedescendant` reference their targets by DOM\n * `id`. When a controller must establish such a relationship but the consumer's\n * markup left the target without an `id`, it needs to mint one that is stable for\n * the page's lifetime and guaranteed not to collide with another generated id.\n *\n * These helpers own *only* id generation/assignment. The linking policy (which\n * attribute, what order, when to add or remove it) stays in each controller —\n * this deliberately avoids a premature generic \"ARIA linker\" abstraction.\n */\n\n/**\n * Monotonic counter backing {@link uniqueId}. Module-scoped so every generated\n * id is unique across all controller instances sharing this module in a document.\n */\nlet counter = 0;\n\n/**\n * Returns a unique, DOM-id-safe string of the form `` `${prefix}-${n}` `` where\n * `n` increases on each call.\n *\n * The counter alone guarantees uniqueness against other *generated* ids, but a\n * consumer-authored element could already own `` `${prefix}-${n}` ``. When a\n * `document` is available the candidate is therefore advanced until no element\n * with that id exists, so a generated id never collides with author markup\n * either — the minimal \"id registry\" guarantee these helpers exist to provide.\n *\n * @param prefix - Leading segment of the id (e.g. a controller's identifier).\n *   Defaults to `\"stimeo\"`.\n */\nexport function uniqueId(prefix = \"stimeo\"): string {\n  let candidate: string;\n  do {\n    counter += 1;\n    candidate = `${prefix}-${counter}`;\n  } while (typeof document !== \"undefined\" && document.getElementById(candidate) !== null);\n  return candidate;\n}\n\n/**\n * Returns `element`'s existing `id`, or assigns it a freshly generated\n * {@link uniqueId} (with the given `prefix`) and returns that. Idempotent: an\n * element that already has an id keeps it, so consumer-authored ids are never\n * overwritten.\n *\n * @param element - The element to read or stamp an `id` onto.\n * @param prefix - Prefix forwarded to {@link uniqueId} when one must be generated.\n * @returns The element's id (existing or newly assigned).\n */\nexport function ensureId(element: Element, prefix = \"stimeo\"): string {\n  if (element.id) return element.id;\n  const id = uniqueId(prefix);\n  element.id = id;\n  return id;\n}\n","/** 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 { announce } from \"../utils/announce\";\nimport { ensureId } from \"../utils/aria_ids\";\nimport { AttributeLease } from \"../utils/attribute_lease\";\nimport { BeforeCacheReset } from \"../utils/before_cache_reset\";\nimport { MicrotaskCoalescer } from \"../utils/microtask_coalescer\";\n\n/** Stimulus action params understood by {@link FormFieldController.setError}. */\ninterface SetErrorParams {\n  /** The error message to display. */\n  message?: string;\n}\n\n/** An action event carrying Stimulus `data-*-param` values. */\ntype ActionEvent = Event & { params?: SetErrorParams };\n\n/** Programmatic behavior switches for {@link FormFieldController.setError}. */\nexport interface FormFieldSetErrorOptions {\n  /** Override the `focusOnError` Value for this call. */\n  focus?: boolean;\n}\n\n/** Detail dispatched with `stimeo--form-field:validate`. */\nexport interface FormFieldValidateDetail {\n  /** Whether the explicit validation action left the field valid. */\n  valid: boolean;\n  /** The first visible error message, or an empty string when valid/unavailable. */\n  message: string;\n}\n\n/** Attributes on retained association targets that can change the ARIA graph. */\nconst OBSERVED_ATTRIBUTES = [\"hidden\", \"id\"];\n\n/**\n * Headless, accessible form-field association behavior.\n *\n * Markup contract (identifier: `stimeo--form-field`):\n *   <div data-controller=\"stimeo--form-field\">\n *     <label for=\"email\">Email</label>\n *     <input id=\"email\" type=\"email\" aria-invalid=\"false\"\n *            data-stimeo--form-field-target=\"control\" />\n *     <p data-stimeo--form-field-target=\"description\">We'll send a confirmation.</p>\n *     <p hidden data-stimeo--form-field-target=\"error\"></p>\n *   </div>\n *\n * Not an APG widget pattern — this is the wiring substrate behind form controls:\n * it supports **Name, Role, Value** (WCAG 4.1.2) and **error identification**\n * (3.3.1 / 4.1.3) by composing the control's `aria-describedby`, toggling\n * `aria-invalid`, and pointing `aria-errormessage` at the visual error.\n *\n * `validate` dispatches `{ valid: boolean, message: string }`.\n *\n * @remarks\n * Behavior only — it sets semantic attributes and the `hidden` state of the\n * visual error; it never validates input (the consumer / server decides) and\n * never styles. Runtime errors are handed to a separately seated\n * `stimeo--announcer`, because showing a live region together with its first\n * message is not a reliable announcement primitive.\n *\n * Behavior provided:\n * - Assigns ids to description/error targets and composes the control's\n *   `aria-describedby` from them in DOM order (preserving the control's authored\n *   tokens and removing duplicates).\n * - Reflects server-rendered errors: an error target that is already visible and\n *   non-empty at connect puts the field into the invalid state (progressive\n *   enhancement).\n * - Reconciles added, removed, replaced, and retained/morphed targets without\n *   emitting validation events or announcements.\n * - {@link setError} / {@link clearError} drive the invalid state at runtime and\n *   dispatch `stimeo--form-field:validate`.\n */\nexport class FormFieldController extends Controller<HTMLElement> {\n  static override targets = [\"control\", \"description\", \"error\"];\n  static override values = {\n    focusOnError: { type: Boolean, default: false },\n  };\n  static actions = [\"clearError\", \"setError\"] as const;\n  static events = [\"validate\"] as const;\n\n  declare readonly controlTarget: HTMLElement;\n  declare readonly hasControlTarget: boolean;\n  declare readonly descriptionTargets: HTMLElement[];\n  declare readonly errorTargets: HTMLElement[];\n  declare readonly hasErrorTarget: boolean;\n  /** Whether an explicit {@link setError} call moves focus to the current control. */\n  declare focusOnErrorValue: boolean;\n\n  /** Root attribute (CSS hook) reflecting the invalid state. */\n  static readonly #INVALID_ATTR = \"data-stimeo--form-field-invalid\";\n\n  /** Collapses one target/morph batch into one silent ARIA reconciliation. */\n  readonly #reconcile = new MicrotaskCoalescer(() => this.#reconcileDom());\n  /** ARIA ownership is scoped to the current singular control target. */\n  readonly #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());\n  readonly #ariaDescribedBy = new AttributeLease<HTMLElement>(\"aria-describedby\");\n  readonly #ariaErrorMessage = new AttributeLease<HTMLElement>(\"aria-errormessage\");\n  readonly #ariaInvalid = new AttributeLease<HTMLElement>(\"aria-invalid\");\n  /** Watches retained target ids, error visibility, and error content. */\n  readonly #observer = new MutationObserver((records) => {\n    if (records.some((record) => this.#isRelevantMutation(record))) {\n      this.#reconcile.schedule();\n    }\n  });\n\n  #activeControl: HTMLElement | null = null;\n  #baseDescribedBy: string[] = [];\n  #explicitInvalid = false;\n  #initialized = false;\n\n  /** Wires the initial graph and starts retained-target reconciliation. */\n  override connect(): void {\n    this.#reconcile.activate();\n    this.#ensureAssociationIds();\n    this.#beforeCache.activate();\n\n    // A restored DOM can contain the invalid hook with no surviving visual\n    // message. Treat that one shape as the persisted explicit setError state;\n    // visible server errors remain derived and can clear when their DOM clears.\n    if (!this.#initialized) {\n      this.#explicitInvalid =\n        this.element.hasAttribute(FormFieldController.#INVALID_ATTR) &&\n        this.#shownErrors().length === 0;\n      this.#initialized = true;\n    }\n\n    this.#reconcileDom();\n    this.#observer.observe(this.element, {\n      attributes: true,\n      attributeFilter: OBSERVED_ATTRIBUTES,\n      characterData: true,\n      childList: true,\n      subtree: true,\n    });\n  }\n\n  /** Releases observers, queued work, and ARIA borrowed on the current control. */\n  override disconnect(): void {\n    this.#reconcile.cancel();\n    this.#observer.disconnect();\n    this.#beforeCache.deactivate();\n    this.#activeControl && this.#releaseControl(this.#activeControl);\n  }\n\n  /** Reconciles a control inserted or replaced at runtime. */\n  controlTargetConnected(): void {\n    this.#reconcile.schedule();\n  }\n\n  /** Schedules restoration of authored ARIA when a control leaves this field. */\n  controlTargetDisconnected(): void {\n    this.#reconcile.schedule();\n  }\n\n  /** Reconciles a description inserted or replaced at runtime. */\n  descriptionTargetConnected(): void {\n    this.#reconcile.schedule();\n  }\n\n  /** Removes a departed description from the control's association graph. */\n  descriptionTargetDisconnected(): void {\n    this.#reconcile.schedule();\n  }\n\n  /** Reconciles an error region inserted or replaced at runtime. */\n  errorTargetConnected(): void {\n    this.#reconcile.schedule();\n  }\n\n  /** Removes a departed error from invalid state and the association graph. */\n  errorTargetDisconnected(): void {\n    this.#reconcile.schedule();\n  }\n\n  /**\n   * Marks the field invalid and shows the error message. Bound via `data-action`\n   * (`#setError`) or callable directly.\n   *\n   * A non-empty shown message is announced exactly once through the shared\n   * assertive announcer. Initial/server reconciliation is deliberately silent.\n   *\n   * @param arg - Either the message string, or the action event whose\n   *   `data-stimeo--form-field-message-param` supplies it. When no message is\n   *   resolvable, any already-populated error targets are simply (re)shown.\n   * @param options - Programmatic overrides. Stimulus actions use the Values.\n   */\n  setError(arg?: string | ActionEvent, options: FormFieldSetErrorOptions = {}): void {\n    const message = this.#resolveMessage(arg);\n    if (message !== null && this.hasErrorTarget) {\n      this.errorTargets[0]?.replaceChildren(document.createTextNode(message));\n    }\n    for (const error of this.errorTargets) {\n      error.hidden = (error.textContent ?? \"\").trim() === \"\";\n    }\n\n    // setError is an explicit invalid request: it remains invalid even if an\n    // error target is absent or replaced before clearError is called.\n    this.#explicitInvalid = true;\n    this.#reconcileDom();\n    const shownMessage = this.#shownMessage();\n    const detail: FormFieldValidateDetail = { valid: false, message: shownMessage };\n    this.dispatch(\"validate\", { detail });\n    announce(shownMessage, { assertive: true });\n\n    if (options.focus ?? this.focusOnErrorValue) this.#activeControl?.focus();\n  }\n\n  /**\n   * Clears the error: empties and hides every error target and marks the field\n   * valid. Bound via `data-action` (`#clearError`) or callable directly.\n   *\n   * Clearing is silent: the visual/ARIA state and validation event are sufficient,\n   * while success wording remains an explicit consumer announcement.\n   */\n  clearError(): void {\n    for (const error of this.errorTargets) {\n      error.replaceChildren();\n      error.hidden = true;\n    }\n    this.#explicitInvalid = false;\n    this.#reconcileDom();\n    const detail: FormFieldValidateDetail = { valid: true, message: \"\" };\n    this.dispatch(\"validate\", { detail });\n  }\n\n  /**\n   * Rebuilds ids and derived ARIA from the settled target graph without reporting\n   * a user validation action.\n   */\n  #reconcileDom(): void {\n    this.#ensureAssociationIds();\n    this.#adoptCurrentControl();\n\n    const shown = this.#shownErrors();\n    const invalid = this.#explicitInvalid || shown.length > 0;\n    this.element.toggleAttribute(FormFieldController.#INVALID_ATTR, invalid);\n\n    const control = this.#activeControl;\n    if (!control) return;\n\n    this.#ariaInvalid.write(control, invalid ? \"true\" : \"false\");\n\n    const primaryErrorId = shown[0]?.id ?? null;\n    this.#ariaErrorMessage.write(control, primaryErrorId);\n\n    const associationIds = this.#orderedElements([...this.descriptionTargets, ...shown]).map(\n      (element) => element.id,\n    );\n    const describedBy = this.#uniqueTokens([...this.#baseDescribedBy, ...associationIds]);\n    this.#ariaDescribedBy.write(control, describedBy.length > 0 ? describedBy.join(\" \") : null);\n  }\n\n  /** Assigns stable ids before either capture or reflection uses them. */\n  #ensureAssociationIds(): void {\n    for (const description of this.descriptionTargets) {\n      ensureId(description, \"stimeo--form-field-desc\");\n    }\n    for (const error of this.errorTargets) {\n      ensureId(error, \"stimeo--form-field-error\");\n    }\n  }\n\n  /** Switches ARIA ownership when the singular current control target changes. */\n  #adoptCurrentControl(): void {\n    const next = this.hasControlTarget ? this.controlTarget : null;\n    if (next === this.#activeControl) return;\n    this.#activeControl && this.#releaseControl(this.#activeControl);\n    this.#activeControl = next;\n    this.#baseDescribedBy = next ? this.#externalDescribedByTokens(next) : [];\n  }\n\n  /** Restores one departed control without overwriting later consumer edits. */\n  #releaseControl(control: HTMLElement): void {\n    this.#ariaDescribedBy.return(control);\n    this.#ariaErrorMessage.return(control);\n    this.#ariaInvalid.return(control);\n    if (control === this.#activeControl) {\n      this.#activeControl = null;\n      this.#baseDescribedBy = [];\n    }\n  }\n\n  /** Error targets currently visible and non-empty, in document order. */\n  #shownErrors(): HTMLElement[] {\n    return this.#orderedElements(\n      this.errorTargets.filter((error) => !error.hidden && (error.textContent ?? \"\").trim() !== \"\"),\n    );\n  }\n\n  /** Text of the first shown error, for validation detail and announcement. */\n  #shownMessage(): string {\n    return (this.#shownErrors()[0]?.textContent ?? \"\").trim();\n  }\n\n  /** Resolves a message from a string argument or an action event's params. */\n  #resolveMessage(arg?: string | ActionEvent): string | null {\n    if (typeof arg === \"string\") return arg;\n    const message = arg?.params?.message;\n    return typeof message === \"string\" ? message : null;\n  }\n\n  /**\n   * Tokens authored on a newly adopted control, excluding ids this controller\n   * owns through its current description/error targets.\n   */\n  #externalDescribedByTokens(control: HTMLElement): string[] {\n    const owned = new Set([\n      ...this.descriptionTargets.map((description) => description.id),\n      ...this.errorTargets.map((error) => error.id),\n    ]);\n    const existing = control.getAttribute(\"aria-describedby\") ?? \"\";\n    return this.#uniqueTokens(\n      existing.split(/\\s+/).filter((token) => token.length > 0 && !owned.has(token)),\n    );\n  }\n\n  /** Deduplicates ARIA tokens without disturbing their first occurrence. */\n  #uniqueTokens(tokens: string[]): string[] {\n    const seen = new Set<string>();\n    return tokens.filter((token) => {\n      if (token.length === 0 || seen.has(token)) return false;\n      seen.add(token);\n      return true;\n    });\n  }\n\n  /** Returns unique current targets in DOM order before serializing IDREF lists. */\n  #orderedElements(elements: HTMLElement[]): HTMLElement[] {\n    const candidates = new Set(elements);\n    return [this.element, ...this.element.querySelectorAll<HTMLElement>(\"*\")].filter((element) =>\n      candidates.has(element),\n    );\n  }\n\n  /** Whether one retained-node mutation can alter this controller's derived state. */\n  #isRelevantMutation(record: MutationRecord): boolean {\n    const target = record.target;\n    if (record.type === \"attributes\") {\n      if (record.attributeName === \"hidden\")\n        return this.errorTargets.includes(target as HTMLElement);\n      return (\n        record.attributeName === \"id\" &&\n        [...this.descriptionTargets, ...this.errorTargets].includes(target as HTMLElement)\n      );\n    }\n\n    return this.errorTargets.some((error) => error === target || error.contains(target));\n  }\n  /** Returns borrowed control ARIA before Turbo snapshots the page. */\n  #rewindForCache(): void {\n    this.#ariaDescribedBy.returnAll();\n    this.#ariaErrorMessage.returnAll();\n    this.#ariaInvalid.returnAll();\n  }\n}\n"]}

package/dist/controllers/form_validation_controller.d.ts

@@ -11,7 +11,7 @@ import { FormFieldController } from './form_field_controller.js';
  *       <label for="email">Email</label>
  *       <input id="email" type="email" required
  *              data-stimeo--form-field-target="control" />
- *       <p role="alert" hidden data-stimeo--form-field-target="error"></p>
+ *       <p hidden data-stimeo--form-field-target="error"></p>
  *     </div>
  *     <button type="submit">Save</button>
  *   </form>
@@ -24,23 +24,25 @@ import { FormFieldController } from './form_field_controller.js';
  * `aria-describedby`) therefore lives in exactly one place — `stimeo--form-field`,
  * reached through a Stimulus **outlet** — and is never re-implemented here.
  *
+ * `valid` dispatches `{}`; `invalid` dispatches `{ invalid: HTMLElement[] }`.
+ *
  * @remarks
  * Behavior only — validation **rules** stay in the markup (native HTML
  * constraints: `required`, `type`, `pattern`, `min`/`max`, …) or in the consumer's
  * own `setCustomValidity()` calls, which `checkValidity()` surfaces transparently.
  * It sets the form's `novalidate` so it can replace the browser's default error
- * bubbles with the accessible, in-page `role="alert"` regions, and restores the
- * attribute on disconnect.
+ * bubbles with accessible in-page visual errors plus the shared Announcer, and
+ * restores the attribute on disconnect.
  *
  * Two declarative escape hatches let a field **exceed** native validation with no
  * consumer JS (author them on the control):
- * - **Per-constraint messages** — `data-stimeo--form-field-message-<constraint>`
+ * - **Per-constraint messages** — `data-stimeo--form-validation-message-<constraint>`
  *   (`value-missing`, `too-short`, `too-long`, `pattern-mismatch`, `type-mismatch`,
  *   `range-overflow`, `range-underflow`, `step-mismatch`, `bad-input`), or a generic
- *   `data-stimeo--form-field-message` fallback, override the shown text per failing
+ *   `data-stimeo--form-validation-message` fallback, override the shown text per failing
  *   `ValidityState` flag — controlled, localizable wording that also fixes headless
  *   browsers returning an empty native `validationMessage`. Falls back to native.
- * - **`data-stimeo--form-field-disallow="whitespace"`** — a built-in custom rule
+ * - **`data-stimeo--form-validation-disallow="whitespace"`** — a built-in custom rule
  *   rejecting a value that is blank after trimming (which slips past `required` /
  *   `minlength`), wired through `setCustomValidity` so it blocks submit like any
  *   native constraint.
@@ -116,8 +118,8 @@ declare class FormValidationController extends Controller<HTMLFormElement> {
     disconnect(): void;
     /**
      * Validates every control now, rendering or clearing each field's message, and
-     * returns whether the whole form is valid. Marks every control touched so a
-     * later input re-validates it. Bound via `data-action`
+     * returns whether the whole form is valid. Marks every field/group touched so
+     * a later input from any sibling re-validates it. Bound via `data-action`
      * (`#validate`) or callable directly (e.g. before a programmatic submit).
      */
     validate(): boolean;