stimeo-ui 0.5.0 → 0.7.0

data/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();
   }
 };