stimeo-ui 0.16.0 → 0.18.0

data/dist/controllers/input_mask_controller.js

@@ -1,87 +1,190 @@
 import { Controller } from '@hotwired/stimulus';
 
-// src/controllers/input_mask_controller.ts
-
-// src/utils/composition_tracker.ts
 var COMPOSITION_INPUT_TYPES = /* @__PURE__ */ new Set([
   "insertCompositionText",
   "insertFromComposition",
   "deleteCompositionText",
   "deleteByComposition"
 ]);
+function isCompositionInputType(inputType) {
+  return inputType !== void 0 && COMPOSITION_INPUT_TYPES.has(inputType);
+}
+var BEFORE_MORPH_ATTRIBUTE = "turbo:before-morph-attribute";
+var textOf = (element) => element.value;
+var holdsFocus = (element) => element instanceof Node && element.getRootNode().activeElement === element;
 var CompositionTracker = class {
   #observedTargets = /* @__PURE__ */ new Set();
-  #activeTargets = /* @__PURE__ */ new Set();
+  #composition = null;
   #onStart;
   #onEnd;
-  /** The field whose confirming `input` is still owed, while the window is open. */
+  #onAbandon;
   #confirmedTarget = null;
+  #keyComposing = false;
+  #connected = false;
+  #abandoned = null;
   constructor(options = {}) {
     this.#onStart = options.onStart;
     this.#onEnd = options.onEnd;
+    this.#onAbandon = options.onAbandon;
   }
-  /** Starts lifecycle tracking for `target`; repeated calls are idempotent. */
   observe(target) {
+    this.#connected = true;
     if (this.#observedTargets.has(target)) return;
     target.addEventListener("compositionstart", this.#handleStart);
     target.addEventListener("compositionend", this.#handleEnd);
-    target.addEventListener("keydown", this.#handleKeydown);
+    target.addEventListener("keydown", this.#handleKeydown, true);
+    target.addEventListener("beforeinput", this.#handleBeforeInput, true);
+    target.addEventListener("input", this.#handleInput, true);
+    target.addEventListener("blur", this.#handleBlur, true);
+    target.addEventListener(BEFORE_MORPH_ATTRIBUTE, this.#handleBeforeMorphAttribute);
     this.#observedTargets.add(target);
   }
-  /** Stops tracking one target and clears any active composition it owned. */
   unobserve(target) {
     if (!this.#observedTargets.delete(target)) return;
-    target.removeEventListener("compositionstart", this.#handleStart);
-    target.removeEventListener("compositionend", this.#handleEnd);
-    target.removeEventListener("keydown", this.#handleKeydown);
-    this.#activeTargets.delete(target);
+    this.#release(target);
+    if (this.#composition?.target === target) this.#letGo();
     if (this.#confirmedTarget === target) this.#confirmedTarget = null;
   }
-  /** Releases every listener and clears state so reconnect starts cleanly. */
   disconnect() {
-    for (const target of this.#observedTargets) {
-      target.removeEventListener("compositionstart", this.#handleStart);
-      target.removeEventListener("compositionend", this.#handleEnd);
-      target.removeEventListener("keydown", this.#handleKeydown);
-    }
+    this.#connected = false;
+    for (const target of this.#observedTargets) this.#release(target);
     this.#observedTargets.clear();
-    this.#activeTargets.clear();
+    this.#letGo();
     this.#confirmedTarget = null;
+    this.#keyComposing = false;
+    this.#abandoned = null;
   }
-  /** True when lifecycle tracking or the current event reports composition. */
   isComposing(event) {
-    return this.#activeTargets.size > 0 || event?.isComposing === true;
-  }
-  /**
-   * Whether `event` is the `input` echoing the composition just confirmed.
-   *
-   * Asking closes the window either way, so one confirmation is folded at most
-   * once and a consumer asks once per `input`.
-   */
+    this.#settle();
+    return event?.isComposing === true || this.#composition !== null;
+  }
+  composingElement() {
+    this.#settle();
+    return this.#composition?.element ?? null;
+  }
+  owns(event) {
+    const element = this.composingElement();
+    return event.isComposing === true || element !== null && element === event.target;
+  }
   consumesConfirmedInput(event) {
     const confirmed = this.#confirmedTarget;
     this.#confirmedTarget = null;
     if (confirmed === null || confirmed !== event.target) return false;
     const inputType = event.inputType;
-    return !inputType || COMPOSITION_INPUT_TYPES.has(inputType);
+    return !inputType || isCompositionInputType(inputType);
+  }
+  #release(target) {
+    target.removeEventListener("compositionstart", this.#handleStart);
+    target.removeEventListener("compositionend", this.#handleEnd);
+    target.removeEventListener("keydown", this.#handleKeydown, true);
+    target.removeEventListener("beforeinput", this.#handleBeforeInput, true);
+    target.removeEventListener("input", this.#handleInput, true);
+    target.removeEventListener("blur", this.#handleBlur, true);
+    target.removeEventListener(BEFORE_MORPH_ATTRIBUTE, this.#handleBeforeMorphAttribute);
   }
+  #letGo() {
+    const composition = this.#composition;
+    if (composition === null) return;
+    if (!holdsFocus(composition.element)) {
+      this.#composition = null;
+      return;
+    }
+    queueMicrotask(() => {
+      if (this.#composition !== composition || this.#observedTargets.has(composition.target)) {
+        return;
+      }
+      this.#composition = null;
+      if (!this.#connected) return;
+      this.#abandoned = { element: composition.element, inPlace: true };
+      this.#runAbandon();
+    });
+  }
+  #settle() {
+    const composition = this.#composition;
+    if (composition === null) return;
+    const { target, element, text } = composition;
+    if (target instanceof Node && element instanceof Node && !target.contains(element)) {
+      this.#composition = null;
+    } else if (textOf(element) !== text) {
+      this.#abandon(false);
+    }
+  }
+  #abandon(inPlace) {
+    this.#owe(inPlace);
+    this.#composition = null;
+    queueMicrotask(this.#runAbandon);
+  }
+  #owe(inPlace) {
+    const composition = this.#composition;
+    if (composition !== null) this.#abandoned = { element: composition.element, inPlace };
+  }
+  #runAbandon = () => {
+    const abandoned = this.#abandoned;
+    if (abandoned === null) return;
+    this.#abandoned = null;
+    this.#onAbandon?.(abandoned.element, abandoned.inPlace);
+  };
   #handleStart = (event) => {
     this.#confirmedTarget = null;
-    if (event.currentTarget) this.#activeTargets.add(event.currentTarget);
+    this.#settle();
+    this.#owe(true);
+    const target = event.currentTarget;
+    const element = event.target;
+    this.#composition = { target, element, text: textOf(element) };
+    this.#runAbandon();
     this.#onStart?.(event);
   };
   #handleEnd = (event) => {
-    if (event.currentTarget) this.#activeTargets.delete(event.currentTarget);
+    this.#runAbandon();
+    if (this.#composition?.target === event.currentTarget) this.#composition = null;
     this.#confirmedTarget = event.target;
     this.#onEnd?.(event);
   };
-  /** A key on an observed field opens an edit of its own, so no echo is owed. */
-  #handleKeydown = () => {
+  #handleKeydown = (event) => {
+    this.#settle();
+    this.#runAbandon();
     this.#confirmedTarget = null;
+    this.#keyComposing = event.isComposing === true;
+  };
+  #handleBeforeInput = (event) => {
+    const keyComposing = this.#keyComposing;
+    this.#keyComposing = false;
+    this.#settle();
+    const { isComposing, inputType } = event;
+    if (this.#composition !== null && !keyComposing && !isComposing && inputType && !isCompositionInputType(inputType)) {
+      this.#abandon(true);
+    }
+    this.#runAbandon();
+  };
+  #handleInput = (event) => {
+    const composition = this.#composition;
+    const { isTrusted, isComposing, inputType } = event;
+    if (composition !== null && event.target === composition.element && (isTrusted || isComposing || isCompositionInputType(inputType))) {
+      composition.text = textOf(composition.element);
+    } else {
+      this.#settle();
+    }
+    this.#runAbandon();
+  };
+  #handleBlur = (event) => {
+    this.#settle();
+    this.#runAbandon();
+    const composition = this.#composition;
+    if (composition === null || composition.target === composition.element) return;
+    const { element } = composition;
+    if (!(element instanceof Node) || event.target !== element) return;
+    const root = element.getRootNode();
+    if (root.activeElement !== element) this.#composition = null;
+  };
+  #handleBeforeMorphAttribute = (event) => {
+    this.#settle();
+    const composition = this.#composition;
+    if (composition?.target !== event.currentTarget || event.target !== composition.element) return;
+    const detail = event.detail;
+    if (detail?.attributeName === "value") event.preventDefault();
   };
 };
 
-// src/utils/declared_value.ts
 function parseDeclared(raw, parse, fallback) {
   try {
     return parse(raw);
@@ -105,7 +208,43 @@ function parseJsonObject(raw) {
   return parsed;
 }
 
-// src/utils/focus_candidate.ts
+var DetachGate = class _DetachGate {
+  #pending = false;
+  get pending() {
+    return this.#pending;
+  }
+  static isDetached(host) {
+    return !host.element.isConnected || !_DetachGate.#listed(host);
+  }
+  disconnected(host, teardown) {
+    const carried = _DetachGate.#carried(host);
+    if (!carried && _DetachGate.isDetached(host)) {
+      this.#pending = false;
+      teardown();
+      return;
+    }
+    this.#pending = true;
+    const probe = () => {
+      if (!this.#pending) return;
+      this.#pending = false;
+      teardown();
+    };
+    if (carried) setTimeout(probe, 0);
+    else queueMicrotask(probe);
+  }
+  static #carried(host) {
+    const element = host.element;
+    return !element.isConnected && element.closest("[data-turbo-permanent]") !== null && _DetachGate.#listed(host);
+  }
+  static #listed(host) {
+    const tokens = (host.element.getAttribute("data-controller") ?? "").split(/\s+/);
+    return tokens.includes(host.identifier);
+  }
+  cancel() {
+    this.#pending = false;
+  }
+};
+
 function inheritsFieldsetDisabled(control) {
   let fieldset = control.closest("fieldset[disabled]");
   while (fieldset) {
@@ -116,7 +255,120 @@ function inheritsFieldsetDisabled(control) {
   return false;
 }
 
-// src/utils/half_width.ts
+function sharedRegistry(key, create) {
+  const symbol = Symbol.for(key);
+  const scope = globalThis;
+  const existing = scope[symbol];
+  if (existing !== void 0) return existing;
+  const registry = create();
+  Object.defineProperty(globalThis, symbol, { value: registry });
+  return registry;
+}
+
+var PREFIX = "__stimeo_raw_v1_";
+var documents = sharedRegistry(
+  "stimeo-ui.form-data-projection.registry.v1",
+  () => /* @__PURE__ */ new WeakMap()
+);
+function decodedName(key) {
+  if (!key.startsWith(PREFIX)) return null;
+  const separator = PREFIX.length + 32;
+  if (key[separator] !== ":") return null;
+  try {
+    const name = JSON.parse(key.slice(separator + 1));
+    return typeof name === "string" ? name : null;
+  } catch {
+    return null;
+  }
+}
+function projectedFieldName(name) {
+  return decodedName(name) ?? name;
+}
+function forDocument(document2) {
+  const existing = documents.get(document2);
+  if (existing) return existing;
+  const state = {
+    fields: /* @__PURE__ */ new Map(),
+    byField: /* @__PURE__ */ new WeakMap(),
+    handle: (event) => {
+      const data = event.formData;
+      if (!data) return;
+      const entries = [...data.entries()];
+      let changed = false;
+      const projected = entries.map(([key, value]) => {
+        const name = decodedName(key);
+        if (name === null) return [key, value];
+        changed = true;
+        const field = state.fields.get(key);
+        const live = field && field.field.name === key && field.field.form === event.target;
+        return [name, live ? field.project(value) : ""];
+      });
+      if (!changed) return;
+      for (const key of new Set(data.keys())) data.delete(key);
+      for (const [name, value] of projected) data.append(name, value);
+    }
+  };
+  documents.set(document2, state);
+  document2.addEventListener("formdata", state.handle, { capture: true });
+  return state;
+}
+function prepareFormDataProjection(form) {
+  const state = forDocument(form.ownerDocument);
+  form.addEventListener("formdata", state.handle, { capture: true });
+}
+var FormDataProjection = class {
+  #held = null;
+  hold(field, project) {
+    const held = this.#held;
+    if (held?.field === field && held.key === field.name && held.document === field.ownerDocument) {
+      if (field.form) prepareFormDataProjection(field.form);
+      return;
+    }
+    this.release();
+    const name = projectedFieldName(field.name);
+    if (name === "" || field.type === "hidden" && name.toLowerCase() === "_charset_") return;
+    const state = forDocument(field.ownerDocument);
+    if (field.form) prepareFormDataProjection(field.form);
+    const previous = state.byField.get(field);
+    if (previous) {
+      state.fields.delete(previous.key);
+      field.removeEventListener("turbo:morph-element", previous.restore);
+    }
+    const nonce = Array.from(
+      crypto.getRandomValues(new Uint8Array(16)),
+      (value) => value.toString(16).padStart(2, "0")
+    ).join("");
+    const key = `${PREFIX}${nonce}:${JSON.stringify(name)}`;
+    const projection = {
+      field,
+      key,
+      name,
+      project,
+      document: field.ownerDocument,
+      state,
+      restore: () => {
+        if (field.name === name) field.name = key;
+      }
+    };
+    state.fields.set(key, projection);
+    state.byField.set(field, projection);
+    this.#held = projection;
+    field.name = key;
+    field.addEventListener("turbo:morph-element", projection.restore);
+  }
+  release() {
+    const held = this.#held;
+    this.#held = null;
+    if (held === null) return;
+    held.field.removeEventListener("turbo:morph-element", held.restore);
+    const state = held.state;
+    if (state.byField.get(held.field) !== held) return;
+    state.fields.delete(held.key);
+    state.byField.delete(held.field);
+    if (held.field.name === held.key) held.field.name = held.name;
+  }
+};
+
 var FULL_WIDTH_SHIFT = 65248;
 function halfWidthChar(char) {
   if (char >= "\uFF01" && char <= "\uFF5E") {
@@ -125,13 +377,123 @@ function halfWidthChar(char) {
   return char === "\u3000" ? " " : char;
 }
 
-// src/controllers/input_mask_controller.ts
+var ListenerSet = class {
+  #abort = new AbortController();
+  add(target, type, handler, options) {
+    target.addEventListener(type, handler, { ...options, signal: this.#abort.signal });
+  }
+  dispose() {
+    this.#abort.abort();
+    this.#abort = new AbortController();
+  }
+};
+
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  constructor(run) {
+    this.#run = run;
+  }
+  activate() {
+    this.#active = true;
+  }
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  get pending() {
+    return this.#queued;
+  }
+  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();
+    });
+  }
+};
+
+var MorphRenderWatcher = class {
+  #listeners = new ListenerSet();
+  #pass;
+  #element = null;
+  #onMorph = () => this.#pass.schedule();
+  constructor(run) {
+    this.#pass = new MicrotaskCoalescer(run);
+  }
+  observe(element) {
+    if (this.#element === element) return;
+    this.disconnect();
+    this.#element = element;
+    this.#pass.activate();
+    this.#listeners.add(element, "turbo:morph-element", this.#onMorph);
+  }
+  schedule() {
+    this.#pass.schedule();
+  }
+  get pending() {
+    return this.#pass.pending;
+  }
+  disconnect() {
+    this.#listeners.dispose();
+    this.#pass.cancel();
+    this.#element = null;
+  }
+};
+
+var TimerRegistry = class {
+  ids = /* @__PURE__ */ new Set();
+  clear(id) {
+    if (this.ids.delete(id)) {
+      this.cancel(id);
+    }
+  }
+  clearAll() {
+    for (const id of this.ids) {
+      this.cancel(id);
+    }
+    this.ids.clear();
+  }
+  get size() {
+    return this.ids.size;
+  }
+};
+var SafeTimeout = class extends TimerRegistry {
+  set(callback, delay) {
+    const id = this.schedule(() => {
+      this.ids.delete(id);
+      callback();
+    }, delay);
+    this.ids.add(id);
+    return id;
+  }
+  schedule(callback, delay) {
+    return window.setTimeout(callback, delay);
+  }
+  cancel(id) {
+    window.clearTimeout(id);
+  }
+};
+
+function prepareInputMaskForm(form) {
+  prepareFormDataProjection(form);
+}
 var DEFAULT_TOKENS = {
   "9": "\\d",
   a: "[A-Za-z]",
   "*": "[A-Za-z0-9]"
 };
 var UNMASK_ATTR = "unmask";
+var rawWriters = sharedRegistry(
+  "stimeo-ui.input-mask-raw-writer.registry.v1",
+  () => /* @__PURE__ */ new WeakMap()
+);
 function acceptedForm(regex, char) {
   if (regex.test(char)) return char;
   const half = halfWidthChar(char);
@@ -208,7 +570,6 @@ function tokenCharOffset(tokenFlags, n) {
   return -1;
 }
 var InputMaskController = class extends Controller {
-  /** The attribute above, in the namespace this controller is registered under. */
   get #unmaskAttribute() {
     return `data-${this.identifier}-${UNMASK_ATTR}`;
   }
@@ -219,19 +580,16 @@ var InputMaskController = class extends Controller {
   };
   static actions = ["format"];
   static events = ["change", "reconcile"];
-  /** The value this controller last committed, and the baseline both events compare. */
   #lastValue = null;
   #started = false;
-  /** Validated token map; the hot path never parses the `tokens` declaration. */
+  #rawSink = null;
+  #rawValue = "";
+  #rawSourceForm = null;
+  #submission = new FormDataProjection();
   #tokens = compileTokens("");
-  /** The field's text when the running composition began. */
   #textBeforeComposition = "";
-  /**
-   * Holds mid-composition input so the IME's uncommitted text is never rewritten,
-   * and formats the confirmed text once when the composition ends. A composition
-   * that ends on the text it began with committed nothing, so a re-format then is
-   * the page's: the mask changed while it ran.
-   */
+  #formatted = null;
+  #shown = { result: null, empty: true };
   #composition = new CompositionTracker({
     onStart: () => {
       this.#textBeforeComposition = this.element.value;
@@ -239,9 +597,11 @@ var InputMaskController = class extends Controller {
     onEnd: () => {
       const committedNothing = this.element.value === this.#textBeforeComposition;
       this.#reformat(committedNothing ? "reconcile" : "edit");
+    },
+    onAbandon: () => {
+      if (this.#formatted !== this.#declared) this.#reformat("reconcile");
     }
   });
-  /** Re-parses the declaration and re-formats under the tokens it now selects. */
   tokensValueChanged() {
     this.#tokens = compileTokens(this.tokensValue);
     if (this.#started) this.#reformat("reconcile");
@@ -249,41 +609,55 @@ var InputMaskController = class extends Controller {
   patternValueChanged() {
     if (this.#started) this.#reformat("reconcile");
   }
-  /** Clears a sink it stops maintaining so a submit cannot carry a stale raw value. */
   unmaskToHiddenValueChanged() {
     if (!this.#started) return;
-    if (!this.unmaskToHiddenValue) {
-      const sink = this.#resolveSink();
-      if (sink) sink.value = "";
-    }
+    if (!this.unmaskToHiddenValue) this.#withdraw();
     this.#reformat("reconcile");
   }
+  #withdraw() {
+    if (this.#retractRaw() && this.#composition.isComposing()) this.#formatted = null;
+  }
+  #morph = new MorphRenderWatcher(() => this.#reformat("reconcile"));
+  #gate = new DetachGate();
+  #adoption = new SafeTimeout();
   connect() {
+    this.#gate.cancel();
+    this.#morph.observe(this.element);
     this.#started = true;
     this.#composition.observe(this.element);
+    if (!this.unmaskToHiddenValue) this.#withdraw();
+    if (this.#composition.isComposing()) {
+      this.#reformat("reconcile");
+      return;
+    }
     this.#lastValue = this.element.value;
     this.#reformat("reconcile");
+    if (this.unmaskToHiddenValue && this.#rawSink === null) {
+      this.#adoption.set(() => this.#adoptSink(), 0);
+    }
   }
   disconnect() {
+    this.#morph.disconnect();
     this.#started = false;
     this.#composition.disconnect();
+    this.#adoption.clearAll();
+    this.#gate.disconnected(this, () => this.#retractRaw());
   }
-  /** Formats the field on input, preserving the caret. Bound via `data-action`. */
   format(event) {
     if (this.#composition.isComposing(event)) return;
     this.#reformat("edit", deletionOf(event));
   }
-  /**
-   * Core reformat: mask the current value, restore the caret, sync the sink and
-   * the state hooks, and report a moved value under the event `cause` selects.
-   *
-   * @stimeoRenderRoot
-   */
   #reformat(cause, deletion = null) {
-    if (this.#composition.isComposing()) return;
+    if (this.#composition.isComposing()) {
+      this.#showAgain();
+      return;
+    }
+    this.#formatted = this.#declared;
     const input = this.element;
     const raw = input.value;
     if (this.patternValue === "") {
+      this.#retractRaw();
+      this.#shown = { result: null, empty: raw.length === 0 };
       this.#flag("data-mask-complete", false);
       this.#flag("data-mask-empty", raw.length === 0);
       this.#lastValue = raw;
@@ -309,8 +683,10 @@ var InputMaskController = class extends Controller {
       this.#lastValue = raw;
       return;
     }
-    input.value = result.masked;
-    this.#restoreCaret(result.tokenFlags, anchor);
+    if (input.value !== result.masked) {
+      input.value = result.masked;
+      this.#restoreCaret(result.tokenFlags, anchor);
+    }
     this.#publish(result, result.masked);
     if (result.masked === this.#lastValue) return;
     this.#lastValue = result.masked;
@@ -318,24 +694,59 @@ var InputMaskController = class extends Controller {
     if (cause === "edit") this.dispatch("change", { detail });
     else this.dispatch("reconcile", { detail });
   }
-  /** Syncs the raw-value sink and the state hooks for the `shown` field text. */
+  get #declared() {
+    return JSON.stringify([this.patternValue, this.tokensValue, this.unmaskToHiddenValue]);
+  }
   #publish(result, shown) {
+    this.#shown = { result, empty: shown.length === 0 };
     if (this.unmaskToHiddenValue) {
       const sink = this.#resolveSink();
-      if (sink) sink.value = result.unmasked;
+      if (sink !== this.#rawSink) this.#retractRaw();
+      if (sink) {
+        sink.value = result.unmasked;
+        rawWriters.set(sink, this);
+        this.#rawSink = sink;
+        this.#rawValue = result.unmasked;
+        this.#rawSourceForm = this.element.form;
+        this.#submission.hold(sink, (value) => this.#submittedValue(sink, value));
+      }
     }
     this.#flag("data-mask-complete", result.complete);
     this.#flag("data-mask-empty", shown.length === 0);
   }
-  /**
-   * How many token slots the text before the caret fills. Masking that prefix is
-   * what makes a rejected character — or a literal that also matches a token —
-   * count exactly as the rendering counts it, so the caret cannot drift.
-   */
+  #showAgain() {
+    const shown = this.#shown;
+    const sink = this.#rawSink;
+    if (shown.result !== null && this.unmaskToHiddenValue && sink !== null && rawWriters.get(sink) === this && this.#resolveSink() === sink) {
+      sink.value = shown.result.unmasked;
+    }
+    this.#flag("data-mask-complete", shown.result?.complete ?? false);
+    this.#flag("data-mask-empty", shown.empty);
+  }
+  #retractRaw() {
+    const sink = this.#rawSink;
+    this.#rawSink = null;
+    this.#submission.release();
+    if (sink === null || rawWriters.get(sink) !== this) return false;
+    rawWriters.delete(sink);
+    if (sink.value === this.#rawValue) sink.value = "";
+    return true;
+  }
+  #submittedValue(sink, value) {
+    if (rawWriters.get(sink) !== this || sink.value !== this.#rawValue || value !== this.#rawValue)
+      return value;
+    const source = this.element;
+    const listed = (source.getAttribute("data-controller") ?? "").split(/\s+/).includes(this.identifier);
+    const associated = source.form === null ? this.#rawSourceForm === null : source.form === sink.form;
+    const eligible = source.isConnected && this.application.element.contains(source) && listed && this.unmaskToHiddenValue && associated;
+    return eligible ? value : "";
+  }
+  #adoptSink() {
+    if (this.#resolveSink() !== null) this.#reformat("reconcile");
+  }
   #significantBefore(prefix) {
     return applyMask(prefix, this.patternValue, this.#tokens).unmasked.length;
   }
-  /** Places the caret after the `n`-th token char (skipping following literals). */
   #restoreCaret(tokenFlags, n) {
     let position;
     if (n <= 0) {
@@ -357,23 +768,6 @@ var InputMaskController = class extends Controller {
     } catch {
     }
   }
-  /**
-   * The hidden raw-value sink for this input, resolved so several masked inputs
-   * can coexist in one form:
-   *
-   * 1. **Explicit pairing** — a sink whose attribute value names this input's
-   *    `id` (`data-stimeo--input-mask-unmask="zip"`).
-   * 2. **Nearest container** — otherwise, walking up from the input, the first
-   *    *value-less* sink in the closest ancestor. Wrapped input+sink pairs each
-   *    find their own sink, and a single form-level sink is found the same
-   *    way. A sink claimed by another input's id is never matched here.
-   *
-   * Both steps only ever consider the associated form's own controls, so a sink
-   * belonging to a different form (or to none) is never written, while one the
-   * `form` attribute associates from elsewhere in the document still resolves —
-   * for either the input or the sink, neither of which needs to contain or be
-   * contained by the form. A form-less input reads the document instead.
-   */
   #resolveSink() {
     const candidates = this.#sinkCandidates();
     const id = this.element.id;
@@ -389,12 +783,6 @@ var InputMaskController = class extends Controller {
     }
     return null;
   }
-  /**
-   * Every sink the input's form owns, in document order — one collection read per
-   * resolution, so the cost tracks the form's own controls and not the depth of
-   * the markup around it. `form.elements` lists controls the `form` attribute
-   * associates from anywhere in the document, and lists nothing another form owns.
-   */
   #sinkCandidates() {
     const form = this.element.form;
     if (form === null) {
@@ -406,13 +794,11 @@ var InputMaskController = class extends Controller {
       (element) => element instanceof HTMLInputElement && element.hasAttribute(this.#unmaskAttribute)
     );
   }
-  /** Sets a boolean `data-*` flag to `"true"` when `on`, else removes it. */
   #flag(name, on) {
     if (on) this.element.setAttribute(name, "true");
     else this.element.removeAttribute(name);
   }
 };
 
-export { InputMaskController, applyMask };
-//# sourceMappingURL=input_mask_controller.js.map
+export { InputMaskController, applyMask, prepareInputMaskForm };
 //# sourceMappingURL=input_mask_controller.js.map