stimeo-ui 0.7.0 → 0.9.0

data/dist/controllers/otp_controller.js

@@ -2,6 +2,23 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/otp_controller.ts
 
+// src/utils/aria_ids.ts
+var counter = 0;
+function uniqueId(prefix = "stimeo") {
+  let candidate;
+  do {
+    counter += 1;
+    candidate = `${prefix}-${counter}`;
+  } while (typeof document !== "undefined" && document.getElementById(candidate) !== null);
+  return candidate;
+}
+function ensureId(element, prefix = "stimeo") {
+  if (element.id) return element.id;
+  const id = uniqueId(prefix);
+  element.id = id;
+  return id;
+}
+
 // src/utils/logical_scroll.ts
 function isRtl(element) {
   return window.getComputedStyle(element).direction === "rtl";
@@ -18,6 +35,76 @@ function isReservedArrowChord(event, allow = []) {
   return event.altKey && !allow.includes("alt") || event.ctrlKey && !allow.includes("ctrl") || event.metaKey && !allow.includes("meta") || event.shiftKey && !allow.includes("shift");
 }
 
+// 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/composition_tracker.ts
 var CompositionTracker = class {
   #observedTargets = /* @__PURE__ */ new Set();
@@ -65,135 +152,264 @@ var CompositionTracker = class {
   };
 };
 
+// src/utils/half_width.ts
+var FULL_WIDTH_SHIFT = 65248;
+function halfWidthChar(char) {
+  if (char >= "\uFF01" && char <= "\uFF5E") {
+    return String.fromCharCode(char.charCodeAt(0) - FULL_WIDTH_SHIFT);
+  }
+  return char === "\u3000" ? " " : char;
+}
+function toHalfWidth(text) {
+  let out = "";
+  for (const char of text) out += halfWidthChar(char);
+  return out;
+}
+
+// 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/otp_controller.ts
+var DEFAULT_PATTERN = "[0-9]";
+function compilePattern(source) {
+  try {
+    return new RegExp(`^${source}$`);
+  } catch {
+    return null;
+  }
+}
+function hasModifier(event) {
+  return event.altKey || event.ctrlKey || event.metaKey || event.shiftKey;
+}
+function statesDiffer(left, right) {
+  return left.value !== right.value || left.state !== right.state;
+}
 var OtpController = class extends Controller {
   static targets = ["field", "value", "error"];
   static values = {
-    length: { type: Number, default: 6 },
-    pattern: { type: String, default: "[0-9]" }
+    pattern: { type: String, default: DEFAULT_PATTERN }
   };
-  static actions = ["onInput", "onKeydown", "onPaste"];
-  static events = ["change", "complete", "invalid"];
+  static actions = ["onInput", "onKeydown", "onPaste", "onPointerDown", "clear"];
+  static events = ["change", "complete", "invalid", "reconcile"];
+  /** Validated matcher; the hot path never compiles a raw declaration. */
+  #pattern = new RegExp(`^${DEFAULT_PATTERN}$`);
+  /** Source of {@link #pattern}, reported in `invalid` so consumers can word it. */
+  #patternSource = DEFAULT_PATTERN;
+  /** Public state carried by the last dispatch; keeps a no-op sync silent. */
+  #published = null;
+  /** Field whose confirming `input` after `compositionend` is already handled. */
+  #confirmedField = null;
+  /** True between connect and disconnect, so pre-connect Value changes stay silent. */
+  #connected = false;
+  /** Digit each field last committed, restored when rejected input replaced it. */
+  #committed = /* @__PURE__ */ new WeakMap();
+  /** Collapses one batch of field target callbacks into a single reconciliation. */
+  #reconcile = new MicrotaskCoalescer(() => this.#reconcileFields());
+  #ariaInvalid = new AttributeLease("aria-invalid");
+  #ariaErrorMessage = new AttributeLease("aria-errormessage");
+  #ariaDescribedBy = new AttributeLease("aria-describedby");
+  #errorHidden = new AttributeLease("hidden");
+  #state = new AttributeLease("data-state");
+  /** Rewinds the transient error surface before Turbo freezes the page. */
+  #beforeCache = new BeforeCacheReset(() => this.#clearError());
   /** Owns IME lifecycle state across every digit field. */
   #composition = new CompositionTracker({
+    onStart: () => {
+      this.#confirmedField = null;
+    },
     onEnd: (event) => {
-      const input = event.currentTarget;
-      if (input) this.#handleInputValidation(input);
+      const input = this.#fieldFrom(event);
+      if (!input) return;
+      this.#confirmedField = input;
+      const committed = event.data ?? "";
+      this.#accept(input, committed.length > input.value.length ? committed : input.value);
     }
   });
   connect() {
-    for (const field of this.fieldTargets) {
-      field.addEventListener("focus", this.#onFieldFocus);
-      this.#composition.observe(field);
-    }
+    this.#connected = true;
+    for (const field of this.fieldTargets) this.#bind(field);
+    document.addEventListener("reset", this.#onReset, true);
+    this.#beforeCache.activate();
+    this.#reconcile.activate();
+    this.#adopt();
+    this.#sync();
   }
   disconnect() {
-    for (const field of this.fieldTargets) {
-      field.removeEventListener("focus", this.#onFieldFocus);
-    }
+    this.#connected = false;
+    for (const field of this.fieldTargets) this.#unbind(field);
     this.#composition.disconnect();
+    document.removeEventListener("reset", this.#onReset, true);
+    this.#beforeCache.deactivate();
+    this.#reconcile.cancel();
+    this.#clearError();
+    this.#state.return(this.element);
   }
   /**
    * Stimulus lifecycle callback when a new field target enters the DOM.
-   * Ensures new additions are also wired with overwriting support.
+   * Wires the new field and folds the wider digit count into one reconciliation,
+   * which stays inert until `connect()` opens the window.
    */
   fieldTargetConnected(element) {
-    element.addEventListener("focus", this.#onFieldFocus);
-    this.#composition.observe(element);
+    this.#bind(element);
+    this.#adoptField(element);
+    this.#reconcile.schedule();
   }
-  /** Removes focus listeners when fields are dropped. */
+  /** Releases a dropped field's listeners and leases, then reconciles the rest. */
   fieldTargetDisconnected(element) {
-    element.removeEventListener("focus", this.#onFieldFocus);
-    this.#composition.unobserve(element);
+    this.#unbind(element);
+    this.#returnFieldLeases(element);
+    this.#reconcile.schedule();
+  }
+  /**
+   * Re-validates a changed `pattern` declaration once and drops any entered digit
+   * the new pattern no longer accepts, so the combined value stays interpretable.
+   */
+  patternValueChanged() {
+    const compiled = compilePattern(this.patternValue);
+    this.#patternSource = compiled ? this.patternValue : DEFAULT_PATTERN;
+    this.#pattern = compiled ?? new RegExp(`^${DEFAULT_PATTERN}$`);
+    if (!this.#connected) return;
+    let dropped = false;
+    for (const field of this.fieldTargets) {
+      if (field.value === "" || !this.#isWritable(field)) continue;
+      if (this.#pattern.test(field.value)) continue;
+      this.#writeField(field, "");
+      dropped = true;
+    }
+    if (dropped) this.#syncAndDispatch();
   }
-  /** Handles keystroke inputs and advances focus to the next field. */
+  /** Handles keystroke inputs, distributes autofilled text, and advances focus. */
   onInput(event) {
-    const input = event.currentTarget;
+    const input = this.#fieldFrom(event);
     if (!input) return;
+    const confirmed = this.#confirmedField;
+    this.#confirmedField = null;
+    if (confirmed === input) return;
     if (this.#composition.isComposing(event)) return;
-    this.#handleInputValidation(input);
+    this.#accept(input);
   }
-  /** Handles Backspace retreating, arrows, and home/end navigation. */
+  /** Handles Backspace clearing, arrows, and home/end navigation. */
   onKeydown(event) {
     if (isReservedArrowChord(event)) return;
-    const input = event.currentTarget;
+    const input = this.#fieldFrom(event);
     if (!input) return;
-    const index = this.fieldTargets.indexOf(input);
-    if (index === -1) return;
+    this.#confirmedField = null;
     if (this.#composition.isComposing(event)) return;
+    const index = this.fieldTargets.indexOf(input);
+    const fields = this.fieldTargets;
     switch (logicalArrowKey(event.key, this.element)) {
       case "Backspace":
-        if (!input.value) {
-          if (index > 0) {
-            event.preventDefault();
-            const prevField = this.fieldTargets[index - 1];
-            if (prevField) {
-              prevField.value = "";
-              prevField.removeAttribute("data-filled");
-              prevField.focus();
-              this.#clearError();
-              this.#syncAndDispatch();
-            }
-          }
-        } else {
-          input.value = "";
-          input.removeAttribute("data-filled");
+        if (hasModifier(event)) break;
+        if (input.value && this.#isWritable(input)) {
+          event.preventDefault();
+          this.#writeField(input, "");
           this.#clearError();
           this.#syncAndDispatch();
+        } else {
+          const previous = this.#writableBefore(index);
+          if (previous) {
+            event.preventDefault();
+            this.#writeField(previous, "");
+            previous.focus();
+            this.#clearError();
+            this.#syncAndDispatch();
+          }
         }
         break;
-      case "ArrowLeft":
-        if (index > 0) {
+      case "ArrowLeft": {
+        const previous = this.#focusableBefore(index);
+        if (previous) {
           event.preventDefault();
-          this.fieldTargets[index - 1]?.focus();
+          previous.focus();
         }
         break;
-      case "ArrowRight":
-        if (index < this.lengthValue - 1) {
+      }
+      case "ArrowRight": {
+        const next = this.#focusableAfter(index);
+        if (next) {
           event.preventDefault();
-          this.fieldTargets[index + 1]?.focus();
+          next.focus();
         }
         break;
-      case "Home":
-        event.preventDefault();
-        this.fieldTargets[0]?.focus();
+      }
+      case "Home": {
+        if (hasModifier(event)) break;
+        const first = fields.find((field) => this.#isFocusable(field));
+        if (first) {
+          event.preventDefault();
+          first.focus();
+        }
         break;
-      case "End":
-        event.preventDefault();
-        this.fieldTargets[this.lengthValue - 1]?.focus();
+      }
+      case "End": {
+        if (hasModifier(event)) break;
+        const last = fields.slice().reverse().find((field) => this.#isFocusable(field));
+        if (last) {
+          event.preventDefault();
+          last.focus();
+        }
         break;
+      }
     }
   }
-  /** Divides pasted string characters across available input fields. */
+  /** Divides pasted string characters across the available input fields. */
   onPaste(event) {
-    const input = event.currentTarget;
+    const input = this.#fieldFrom(event);
     if (!input) return;
-    const startIndex = this.fieldTargets.indexOf(input);
-    if (startIndex === -1) return;
     event.preventDefault();
-    const rawText = event.clipboardData?.getData("text") || "";
-    const text = this.#normalizeValue(rawText);
-    const regex = new RegExp(`^${this.patternValue}$`);
-    const validChars = Array.from(text).filter((char) => regex.test(char));
-    if (validChars.length === 0) {
-      this.#showError();
-      return;
-    }
-    const limit = Math.min(validChars.length, this.lengthValue - startIndex);
-    let lastFocusedIndex = startIndex;
-    for (let i = 0; i < limit; i++) {
-      const fieldIndex = startIndex + i;
-      const field = this.fieldTargets[fieldIndex];
-      const char = validChars[i];
-      if (field && char) {
-        field.value = char;
-        field.setAttribute("data-filled", "true");
-        lastFocusedIndex = fieldIndex;
-      }
+    this.#confirmedField = null;
+    this.#distribute(input, toHalfWidth(event.clipboardData?.getData("text") ?? ""));
+  }
+  /**
+   * Redirects a pointer landing on an empty field to the earliest empty one, so
+   * a passcode is entered in order. Filled fields stay directly reachable for
+   * correction, and keyboard focus is left alone.
+   */
+  onPointerDown(event) {
+    const input = this.#fieldFrom(event);
+    if (input?.value !== "") return;
+    const first = this.fieldTargets.find((field) => this.#isWritable(field) && field.value === "");
+    if (!first || first === input) return;
+    event.preventDefault();
+    first.focus();
+  }
+  /** Empties every writable field and restarts entry at the first of them. */
+  clear() {
+    for (const field of this.fieldTargets) {
+      if (this.#isWritable(field)) this.#writeField(field, "");
     }
     this.#clearError();
-    const focusTargetIndex = lastFocusedIndex < this.lengthValue - 1 ? lastFocusedIndex + 1 : lastFocusedIndex;
-    this.fieldTargets[focusTargetIndex]?.focus();
+    this.fieldTargets.find((field) => this.#isWritable(field))?.focus();
     this.#syncAndDispatch();
   }
   #onFieldFocus = (event) => {
@@ -202,55 +418,210 @@ var OtpController = class extends Controller {
       input.select();
     }
   };
-  #handleInputValidation(input) {
-    const index = this.fieldTargets.indexOf(input);
-    if (index === -1) return;
-    const rawValue = input.value;
-    const normalized = this.#normalizeValue(rawValue);
-    const regex = new RegExp(`^${this.patternValue}$`);
-    if (normalized && regex.test(normalized)) {
-      input.value = normalized;
-      input.setAttribute("data-filled", "true");
+  /** Reconciles derived state after a non-cancelled reset restores the fields. */
+  #onReset = (event) => {
+    const form = event.target;
+    if (!(form instanceof HTMLFormElement) || !this.#ownedBy(form)) return;
+    queueMicrotask(() => {
+      if (event.defaultPrevented) return;
+      this.#adopt();
+      this.#syncAndDispatch();
+    });
+  };
+  /** Whether a form owns at least one field or the hidden combined value. */
+  #ownedBy(form) {
+    if (this.fieldTargets.some((field) => field.form === form)) return true;
+    return this.hasValueTarget && this.valueTarget.form === form;
+  }
+  #bind(field) {
+    field.addEventListener("focus", this.#onFieldFocus);
+    this.#composition.observe(field);
+  }
+  #unbind(field) {
+    field.removeEventListener("focus", this.#onFieldFocus);
+    this.#composition.unobserve(field);
+    if (this.#confirmedField === field) this.#confirmedField = null;
+  }
+  /** Reads every field back so a restored or reset group starts consistent. */
+  #adopt() {
+    for (const field of this.fieldTargets) this.#adoptField(field);
+    this.#clearError();
+    if (this.hasErrorTarget) this.errorTarget.setAttribute("hidden", "");
+  }
+  /** Takes one field's current value as the truth behind its derived state. */
+  #adoptField(field) {
+    this.#committed.set(field, field.value);
+    this.#markFilled(field, field.value);
+  }
+  /**
+   * Absorbs a batch of field additions or removals as one state transition.
+   *
+   * The page, not the user, moved the state here, so it is reported as
+   * `reconcile`: automation listening for `change` must not read a re-render as
+   * an edit, and a passcode that happens to end up full must not fire the
+   * `complete` that submits it.
+   *
+   * Completeness moves on its own when the field count changes: dropping a
+   * trailing empty field completes a passcode whose combined value never moved,
+   * and adding one un-completes it. Comparing the whole derived state, not the
+   * string it contains, is what makes those transitions reportable.
+   */
+  #reconcileFields() {
+    const previous = this.#published;
+    const current = this.#sync();
+    if (previous && !statesDiffer(previous, current)) return;
+    this.dispatch("reconcile", { detail: { value: current.value } });
+  }
+  /**
+   * Validates the text an entry point received and distributes what it accepts.
+   * `text` defaults to the field's own value; a confirmation passes the string it
+   * committed, which `maxlength` would otherwise have truncated.
+   */
+  #accept(input, text = input.value) {
+    const raw = toHalfWidth(text);
+    if (raw === "") {
+      this.#writeField(input, "");
       this.#clearError();
-      if (index < this.lengthValue - 1) {
-        const nextField = this.fieldTargets[index + 1];
-        nextField?.focus();
-      }
-    } else if (normalized) {
-      input.value = "";
-      input.removeAttribute("data-filled");
+      this.#syncAndDispatch();
+      return;
+    }
+    this.#distribute(input, raw);
+  }
+  /**
+   * Fills `text`'s accepted characters into the writable fields at and after the
+   * entry point, then leaves focus on the field after the last one filled.
+   */
+  #distribute(from, text) {
+    const accepted = Array.from(text).filter((char) => this.#pattern.test(char));
+    let reached = false;
+    const slots = this.fieldTargets.filter((field) => {
+      reached ||= field === from;
+      return reached && this.#isWritable(field);
+    });
+    const filled = Math.min(accepted.length, slots.length);
+    if (filled === 0) {
+      this.#restore(from);
       this.#showError();
-    } else {
-      input.removeAttribute("data-filled");
+      this.#sync();
+      return;
+    }
+    for (let i = 0; i < filled; i++) {
+      const field = slots[i];
+      const char = accepted[i];
+      if (field && char) this.#writeField(field, char);
     }
+    const last = slots[filled - 1];
+    if (last) (this.#writableAfter(last) ?? last).focus();
+    this.#clearError();
     this.#syncAndDispatch();
   }
-  #normalizeValue(val) {
-    return val.replace(/[０-９]/g, (s) => String.fromCharCode(s.charCodeAt(0) - 65248));
+  /** Restores the digit a field committed before rejected input replaced it. */
+  #restore(field) {
+    this.#writeField(field, this.#committed.get(field) ?? "");
   }
-  #showError() {
-    if (this.hasErrorTarget) {
-      this.errorTarget.removeAttribute("hidden");
-    }
-    this.dispatch("invalid", { detail: { pattern: this.patternValue } });
+  /** Commits one field's value and the derived hook that reports it as entered. */
+  #writeField(field, value) {
+    field.value = value;
+    this.#committed.set(field, value);
+    this.#markFilled(field, value);
   }
-  #clearError() {
-    if (this.hasErrorTarget) {
-      this.errorTarget.setAttribute("hidden", "true");
-    }
+  #markFilled(field, value) {
+    if (value) field.setAttribute("data-filled", "true");
+    else field.removeAttribute("data-filled");
   }
-  #syncAndDispatch() {
+  #isWritable(field) {
+    return !field.disabled && !field.readOnly;
+  }
+  #isFocusable(field) {
+    return !field.disabled;
+  }
+  #writableAfter(field) {
     const fields = this.fieldTargets;
-    const combinedValue = fields.map((f) => f.value).join("");
+    return fields.slice(fields.indexOf(field) + 1).find((next) => this.#isWritable(next)) ?? null;
+  }
+  #writableBefore(index) {
+    return this.#before(index).find((field) => this.#isWritable(field)) ?? null;
+  }
+  #focusableAfter(index) {
+    return this.fieldTargets.slice(index + 1).find((field) => this.#isFocusable(field)) ?? null;
+  }
+  #focusableBefore(index) {
+    return this.#before(index).find((field) => this.#isFocusable(field)) ?? null;
+  }
+  /** Fields before `index`, nearest first; empty at the first field. */
+  #before(index) {
+    return this.fieldTargets.slice(0, Math.max(index, 0)).reverse();
+  }
+  /** The event's field target, or `null` when the wiring points somewhere else. */
+  #fieldFrom(event) {
+    const input = event.currentTarget;
+    return this.fieldTargets.find((field) => field === input) ?? null;
+  }
+  #combinedValue() {
+    return this.fieldTargets.map((field) => field.value).join("");
+  }
+  /** Every field carries a character, and there is at least one field. */
+  #isComplete() {
+    const fields = this.fieldTargets;
+    return fields.length > 0 && fields.every((field) => field.value.length > 0);
+  }
+  /**
+   * Mirrors the combined value into the form and the root's readable state, and
+   * records what was published so the next pass can compare against it.
+   */
+  #sync() {
+    const combined = this.#combinedValue();
     if (this.hasValueTarget) {
-      this.valueTarget.value = combinedValue;
+      this.valueTarget.value = combined;
     }
-    this.dispatch("change", { detail: { value: combinedValue } });
-    const isCompleted = fields.every((f) => f.value.length > 0) && combinedValue.length === this.lengthValue;
-    if (isCompleted) {
-      this.dispatch("complete", { detail: { value: combinedValue } });
+    const state = this.#stateName(combined);
+    this.#state.write(this.element, state);
+    const published = { value: combined, state };
+    this.#published = published;
+    return published;
+  }
+  #stateName(combined) {
+    if (combined.length === 0) return "empty";
+    return this.#isComplete() ? "complete" : "partial";
+  }
+  #syncAndDispatch() {
+    const previous = this.#published;
+    const { value: combined } = this.#sync();
+    if (previous?.value === combined) return;
+    this.dispatch("change", { detail: { value: combined } });
+    if (this.#isComplete()) {
+      this.dispatch("complete", { detail: { value: combined } });
     }
   }
+  /** Surfaces rejected input on every field and on the optional error target. */
+  #showError() {
+    const errorId = this.hasErrorTarget ? ensureId(this.errorTarget, "stimeo--otp-error") : null;
+    for (const field of this.fieldTargets) {
+      this.#ariaInvalid.write(field, "true");
+      if (!errorId) continue;
+      this.#ariaErrorMessage.write(field, errorId);
+      this.#ariaDescribedBy.write(field, this.#describedByWith(field, errorId));
+    }
+    if (this.hasErrorTarget) this.#errorHidden.write(this.errorTarget, null);
+    this.dispatch("invalid", { detail: { pattern: this.#patternSource } });
+  }
+  /** Returns every error lease, restoring the authored error surface. */
+  #clearError() {
+    this.#ariaInvalid.returnAll();
+    this.#ariaErrorMessage.returnAll();
+    this.#ariaDescribedBy.returnAll();
+    this.#errorHidden.returnAll();
+  }
+  #returnFieldLeases(field) {
+    this.#ariaInvalid.return(field);
+    this.#ariaErrorMessage.return(field);
+    this.#ariaDescribedBy.return(field);
+  }
+  /** The field's own description tokens with the error id appended once. */
+  #describedByWith(field, errorId) {
+    const tokens = (field.getAttribute("aria-describedby") ?? "").split(/\s+/).filter((token) => token.length > 0 && token !== errorId);
+    return [...tokens, errorId].join(" ");
+  }
 };
 
 export { OtpController };