stimeo-ui 0.14.0 → 0.16.0

data/dist/controllers/tags_input_controller.js

@@ -35,6 +35,25 @@ 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/element_part.ts
+function matchingPart(root, selector) {
+  return root.matches(selector) ? root : root.querySelector(selector);
+}
+function writeLabel(slot, text) {
+  if (slot.childElementCount === 0) {
+    slot.textContent = text;
+    return;
+  }
+  let first = null;
+  for (const node of Array.from(slot.childNodes)) {
+    if (node.nodeType !== Node.TEXT_NODE) continue;
+    if (first) node.remove();
+    else first = node;
+  }
+  if (first) first.nodeValue = text;
+  else slot.prepend(text);
+}
+
 // src/utils/roving_tabindex.ts
 var RovingTabindex = class {
   /** Returns the current ordered item elements; called on every operation. */
@@ -82,7 +101,7 @@ var ChipRow = class {
   constructor(options) {
     this.#directionElement = options.directionElement;
     this.#getItems = options.getItems;
-    this.#getButton = options.getButton ?? ((item) => item.querySelector("button"));
+    this.#getButton = options.getButton ?? ((item) => matchingPart(item, "button"));
     this.#onRemove = options.onRemove;
     this.#focusAfterEnd = options.focusAfterEnd;
   }
@@ -207,11 +226,19 @@ var ChipRow = class {
 };
 
 // src/utils/composition_tracker.ts
+var COMPOSITION_INPUT_TYPES = /* @__PURE__ */ new Set([
+  "insertCompositionText",
+  "insertFromComposition",
+  "deleteCompositionText",
+  "deleteByComposition"
+]);
 var CompositionTracker = class {
   #observedTargets = /* @__PURE__ */ new Set();
   #activeTargets = /* @__PURE__ */ new Set();
   #onStart;
   #onEnd;
+  /** The field whose confirming `input` is still owed, while the window is open. */
+  #confirmedTarget = null;
   constructor(options = {}) {
     this.#onStart = options.onStart;
     this.#onEnd = options.onEnd;
@@ -221,6 +248,7 @@ var CompositionTracker = class {
     if (this.#observedTargets.has(target)) return;
     target.addEventListener("compositionstart", this.#handleStart);
     target.addEventListener("compositionend", this.#handleEnd);
+    target.addEventListener("keydown", this.#handleKeydown);
     this.#observedTargets.add(target);
   }
   /** Stops tracking one target and clears any active composition it owned. */
@@ -228,31 +256,77 @@ var CompositionTracker = class {
     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);
+    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.#observedTargets.clear();
     this.#activeTargets.clear();
+    this.#confirmedTarget = 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`.
+   */
+  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);
+  }
   #handleStart = (event) => {
+    this.#confirmedTarget = null;
     if (event.currentTarget) this.#activeTargets.add(event.currentTarget);
     this.#onStart?.(event);
   };
   #handleEnd = (event) => {
     if (event.currentTarget) this.#activeTargets.delete(event.currentTarget);
+    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 = () => {
+    this.#confirmedTarget = null;
+  };
 };
 
+// src/utils/field_mirror.ts
+function writeFields(container, values, { name, form = "" }) {
+  const current = [...container.children];
+  const submits = current.length === values.length && current.every(
+    (child, index) => child instanceof HTMLInputElement && child.type === "hidden" && child.value === values[index] && child.name === name && (child.getAttribute("form") ?? "") === form
+  );
+  if (submits) return false;
+  container.replaceChildren(
+    ...values.map((value) => {
+      const input = document.createElement("input");
+      input.type = "hidden";
+      input.name = name;
+      input.value = value;
+      if (form !== "") input.setAttribute("form", form);
+      return input;
+    })
+  );
+  return true;
+}
+function commitField(target) {
+  target.dispatchEvent(new Event("change", { bubbles: true }));
+}
+
 // src/utils/microtask_coalescer.ts
 var MicrotaskCoalescer = class {
   #run;
@@ -286,6 +360,85 @@ var MicrotaskCoalescer = class {
   }
 };
 
+// src/utils/target_selector.ts
+function targetSelector(identifier, name) {
+  return `[data-${identifier}-target~="${name}"]`;
+}
+
+// src/utils/template_row.ts
+function cloneTemplateRoot(template) {
+  const root = template.content.firstElementChild;
+  return root instanceof HTMLElement ? root.cloneNode(true) : null;
+}
+var TemplateRow = class {
+  #options;
+  #warned = false;
+  constructor(options) {
+    this.#options = options;
+  }
+  /** The attribute selector for one declared part, in this controller's namespace. */
+  selector(name) {
+    return targetSelector(this.#options.identifier, name);
+  }
+  /** Re-arms the once-per-connection diagnostic. */
+  connect() {
+    this.#warned = false;
+  }
+  /**
+   * Names one missing part on the console, at most once per connection, and
+   * returns `null` so a caller can hand it straight back.
+   */
+  report(missing) {
+    return this.#say(`lacks ${missing}`);
+  }
+  /** Writes one diagnostic per connection, saying what the template got wrong. */
+  #say(problem) {
+    if (this.#warned) return null;
+    this.#warned = true;
+    const { identifier, outcome, noun } = this.#options;
+    console.warn(`Stimeo UI: "${identifier}" ${outcome} because its ${noun} ${problem}.`);
+    return null;
+  }
+  /**
+   * Clones the row and resolves its parts, or names what the template got wrong
+   * and returns `null`. `values` fills the button's authored `aria-label`.
+   */
+  instantiate(template, values) {
+    const { root: rootName, required, optional, button: buttonName } = this.#options;
+    const root = cloneTemplateRoot(template);
+    if (!root?.matches(this.selector(rootName))) {
+      return this.report(`${this.#article(rootName)} "${rootName}" root`);
+    }
+    const count = template.content.children.length;
+    if (count !== 1) {
+      return this.#say(`holds ${count} elements, and the row has to be its only one`);
+    }
+    const slots = {};
+    for (const name2 of required) {
+      const part = this.#resolve(root, name2);
+      if (!part) return this.report(`${this.#article(name2)} "${name2}" target`);
+      slots[name2] = part;
+    }
+    for (const name2 of optional ?? []) slots[name2] = this.#resolve(root, name2);
+    const named = this.#resolve(root, buttonName);
+    if (!(named instanceof HTMLButtonElement)) {
+      return this.report(`${this.#article(buttonName)} "${buttonName}" target <button>`);
+    }
+    const button = named;
+    const name = button.getAttribute("aria-label")?.trim() ?? "";
+    if (name === "") return this.report(`a non-empty aria-label on its "${buttonName}" target`);
+    button.setAttribute("aria-label", fillTemplate(name, values));
+    return { root, slots, button };
+  }
+  /** The row may be its own part; otherwise the first descendant carrying the target. */
+  #resolve(root, name) {
+    return matchingPart(root, this.selector(name));
+  }
+  #article(name) {
+    return /^[aeiou]/i.test(name) ? "an" : "a";
+  }
+};
+
 // src/controllers/tags_input_controller.ts
 var TagsInputController = class extends Controller {
   static targets = ["input", "tags", "tag", "tagTemplate", "label", "remove", "fields"];
@@ -294,6 +447,7 @@ var TagsInputController = class extends Controller {
     max: { type: Number, default: 0 },
     allowDuplicates: { type: Boolean, default: false },
     name: { type: String, default: "tags[]" },
+    form: { type: String, default: "" },
     announceText: { type: String, default: "" },
     announceRemovedText: { type: String, default: "" }
   };
@@ -301,14 +455,21 @@ var TagsInputController = class extends Controller {
   static events = ["change", "reconcile", "reject"];
   /** Last reconciled tag order, separating user edits from DOM/Turbo repair. */
   #tagValues = [];
-  /** Whether this connection already reported its unusable chip template. */
-  #warnedTemplate = false;
+  /** Builds one chip from the authored template and owns its diagnostic. */
+  #rows = new TemplateRow({
+    identifier: this.identifier,
+    root: "tag",
+    required: ["label"],
+    button: "remove",
+    outcome: "added no tag",
+    noun: "chip template"
+  });
   /** Collapses one target/Value mutation batch into one final-DOM repair pass. */
   #reconcile = new MicrotaskCoalescer(() => this.#reconcileTags());
   #chipRow = new ChipRow({
     directionElement: this.element,
     getItems: () => this.tagTargets,
-    getButton: (tag) => tag.querySelector('button[data-stimeo--tags-input-target~="remove"]'),
+    getButton: (tag) => matchingPart(tag, `button${this.#rows.selector("remove")}`),
     onRemove: (index) => this.#removeAt(index),
     focusAfterEnd: () => this.#focusInput()
   });
@@ -316,7 +477,7 @@ var TagsInputController = class extends Controller {
   #composition = new CompositionTracker();
   /** Wires tag-list keyboard navigation and removal, and seeds the single Tab stop. */
   connect() {
-    this.#warnedTemplate = false;
+    this.#rows.connect();
     if (this.hasInputTarget) this.#composition.observe(this.inputTarget);
     if (this.hasTagsTarget) this.#chipRow.connect(this.tagsTarget);
     const tags = this.#values;
@@ -363,6 +524,10 @@ var TagsInputController = class extends Controller {
   nameValueChanged() {
     this.#reconcile.schedule();
   }
+  /** Repoints submitted fields when the owning form changes at runtime. */
+  formValueChanged() {
+    this.#reconcile.schedule();
+  }
   /** Recomputes the full hook when the cap changes at runtime. */
   maxValueChanged() {
     this.#reconcile.schedule();
@@ -393,7 +558,11 @@ var TagsInputController = class extends Controller {
       }
     }
   }
-  /** Validates and adds the current input value as a tag, then clears the input. */
+  /**
+   * Validates and adds the current input value as a tag, then clears the input.
+   *
+   * @stimeoRuntimeOnly `max` and `allowDuplicates` decide whether this one entry is taken.
+   */
   #commitInput() {
     const value = this.inputTarget.value.trim();
     if (value === "") {
@@ -411,53 +580,31 @@ var TagsInputController = class extends Controller {
     if (!this.#appendTag(value)) return;
     this.inputTarget.value = "";
     const tags = this.#values;
-    this.#syncState(tags);
+    this.#syncState(tags, true);
     this.#tagValues = tags;
     this.#announceTransition(true, value, tags.length);
     this.dispatch("change", { detail: { tags } });
   }
-  /** Builds one chip from the template and appends it to the tag list. */
-  #appendTag(value) {
-    if (!this.hasTagsTarget) return false;
-    if (!this.hasTagTemplateTarget) return this.#warnTemplate('a "tagTemplate" target');
-    const fragment = this.tagTemplateTarget.content.cloneNode(true);
-    const tag = fragment.querySelector('[data-stimeo--tags-input-target~="tag"]');
-    const label = fragment.querySelector('[data-stimeo--tags-input-target~="label"]');
-    const button = fragment.querySelector(
-      'button[data-stimeo--tags-input-target~="remove"]'
-    );
-    const removeName = button?.getAttribute("aria-label")?.trim() ?? "";
-    if (!tag) return this.#warnTemplate('a "tag" target');
-    if (!label) return this.#warnTemplate('a "label" target');
-    if (!button) return this.#warnTemplate('a "remove" target <button>');
-    if (removeName === "") {
-      return this.#warnTemplate('a non-empty aria-label on its "remove" target');
-    }
-    tag.dataset.value = value;
-    label.textContent = value;
-    button.setAttribute("aria-label", fillTemplate(removeName, { label: value, value }));
-    button.tabIndex = -1;
-    this.tagsTarget.appendChild(fragment);
-    return true;
-  }
   /**
-   * Reports an unusable chip template to the author, once per connection.
+   * Builds one chip from the template and appends it to the tag list.
    *
-   * The commit itself stays a no-op — nothing about the input, the tag set, the
-   * hidden fields, the announcement, or the events changes. Without this line
-   * the only symptom is a field that accepts no tags at all, and the two causes
-   * the Inspector cannot see statically (a name that renders empty from a
-   * missing translation, a server-rendered template) would have no diagnostic
-   * anywhere.
+   * A refused row leaves the commit a no-op — nothing about the input, the tag
+   * set, the hidden fields, the announcement, or the events changes — and the
+   * row reports why on the console once per connection.
    */
-  #warnTemplate(missing) {
-    if (!this.#warnedTemplate) {
-      this.#warnedTemplate = true;
-      console.warn(
-        `Stimeo UI: "${this.identifier}" added no tag because its chip template lacks ${missing}.`
-      );
+  #appendTag(value) {
+    if (!this.hasTagsTarget) return false;
+    if (!this.hasTagTemplateTarget) {
+      this.#rows.report('a "tagTemplate" target');
+      return false;
     }
-    return false;
+    const row = this.#rows.instantiate(this.tagTemplateTarget, { label: value, value });
+    if (!row) return false;
+    row.root.dataset.value = value;
+    writeLabel(row.slots.label, value);
+    row.button.tabIndex = -1;
+    this.tagsTarget.appendChild(row.root);
+    return true;
   }
   /** Removes the tag at `index`, then applies the interaction-origin focus policy. */
   #removeAt(index, focus = "neighbor") {
@@ -466,7 +613,7 @@ var TagsInputController = class extends Controller {
     const value = tag.dataset.value ?? "";
     tag.remove();
     const tags = this.#values;
-    this.#syncState(tags);
+    this.#syncState(tags, true);
     this.#tagValues = tags;
     this.#announceTransition(false, value, tags.length);
     this.dispatch("change", { detail: { tags } });
@@ -480,21 +627,20 @@ var TagsInputController = class extends Controller {
   #focusInput() {
     if (this.hasInputTarget) this.inputTarget.focus();
   }
-  /** Rebuilds the hidden form fields, the `full` flag, and the roving Tab stop. */
-  #syncState(values) {
+  /**
+   * Rebuilds the hidden form fields, the `full` flag, and the roving Tab stop.
+   *
+   * @stimeoRenderRoot
+   */
+  #syncState(values, notify = false) {
     if (this.hasFieldsTarget) {
-      this.fieldsTarget.replaceChildren(
-        ...values.map((value) => {
-          const input = document.createElement("input");
-          input.type = "hidden";
-          input.name = this.nameValue;
-          input.value = value;
-          return input;
-        })
-      );
+      const options = { name: this.nameValue, form: this.formValue };
+      if (writeFields(this.fieldsTarget, values, options) && notify) {
+        commitField(this.fieldsTarget);
+      }
     }
     const full = this.maxValue > 0 && values.length >= this.maxValue;
-    this.element.toggleAttribute("data-stimeo--tags-input-full", full);
+    this.element.toggleAttribute(`data-${this.identifier}-full`, full);
     this.#chipRow.ensureTabStop();
   }
   /** Repairs derived state after DOM/Turbo changes and reports a changed tag order. */
@@ -507,7 +653,11 @@ var TagsInputController = class extends Controller {
     this.#tagValues = tags;
     if (changed) this.dispatch("reconcile", { detail: { tags } });
   }
-  /** Sends one localized tag transition through the page's shared announcer. */
+  /**
+   * Sends one localized tag transition through the page's shared announcer.
+   *
+   * @stimeoRuntimeOnly The texts word the one announcement of this change.
+   */
   #announceTransition(added, value, count) {
     const template = added ? this.announceTextValue : this.announceRemovedTextValue;
     announce(fillTemplate(template, { label: value, value, count }));

data/dist/controllers/textarea_autosize_controller.js

@@ -8,10 +8,15 @@ var LayoutObserver = class {
   #resizeObserverFactory;
   #resizeObserver = null;
   #observingViewport = false;
+  #loadContainer = null;
   /** Stable bound handler so add/removeEventListener target the same reference. */
   #handleViewportResize = () => {
     this.#callback();
   };
+  /** Stable bound handler for the capture-phase `load`; see {@link observeDescendantLoads}. */
+  #handleDescendantLoad = () => {
+    this.#callback();
+  };
   constructor(callback, options = {}) {
     this.#callback = callback;
     this.#resizeObserverFactory = options.resizeObserverFactory ?? (typeof ResizeObserver === "undefined" ? null : (cb) => new ResizeObserver(cb));
@@ -47,14 +52,35 @@ var LayoutObserver = class {
     window.removeEventListener("resize", this.#handleViewportResize);
   }
   /**
-   * Releases every observation: disconnects the {@link ResizeObserver} and
-   * removes the viewport listener. Safe to call multiple times. Call this from a
-   * controller's `disconnect()`.
+   * Starts reporting a `load` from anywhere inside `container` — an image or a
+   * frame settling changes the box it sits in, and it measures as zero high until
+   * then. `load` does not bubble, so the subscription is a capture-phase listener
+   * on the container itself and nothing the caller spells.
+   *
+   * **One container at a time.** A further call moves the observation, so a widget
+   * whose content element is swapped at runtime releases the element it let go by
+   * naming the new one — there is no second place for the release to drift from.
+   */
+  observeDescendantLoads(container) {
+    this.unobserveDescendantLoads();
+    this.#loadContainer = container;
+    container.addEventListener("load", this.#handleDescendantLoad, true);
+  }
+  /** Stops reporting descendant loads without affecting element or viewport observation. */
+  unobserveDescendantLoads() {
+    this.#loadContainer?.removeEventListener("load", this.#handleDescendantLoad, true);
+    this.#loadContainer = null;
+  }
+  /**
+   * Releases every observation: disconnects the {@link ResizeObserver} and removes
+   * the viewport and descendant-load listeners. Safe to call multiple times. Call
+   * this from a controller's `disconnect()`.
    */
   disconnect() {
     this.#resizeObserver?.disconnect();
     this.#resizeObserver = null;
     this.unobserveViewport();
+    this.unobserveDescendantLoads();
   }
 };
 

data/dist/controllers/theme_controller.js

@@ -113,20 +113,20 @@ var ThemeController = class extends Controller {
     target: { type: String, default: DEFAULT_TARGET }
   };
   static actions = ["set", "toggle"];
-  static events = ["change"];
+  static events = ["change", "reconcile"];
   /** The OS dark-mode query, watched so `system` tracks live changes. */
   #media = null;
-  /** Gate for the target callbacks, which Stimulus runs before `connect()`. */
+  /** Gate for the target and `mode` callbacks, which Stimulus runs before `connect()`. */
   #connected = false;
   /** The `target` declaration after validation; the default when unparsable. */
   #targetSelector = DEFAULT_TARGET;
   /** Owns the single Tab stop across the option set (APG radiogroup). */
   #roving = new RovingTabindex(() => this.optionTargets);
   /**
-   * The pair last reported, so a move can be told from a repeat. Neither side is
-   * readable after the fact — assigning the Value updates the mode before any
-   * comparison, and the OS query has already flipped by the time it notifies —
-   * so what was reported has to be kept rather than recomputed.
+   * The pair on screen as last reported or re-seeded, so a move can be told from a
+   * repeat. Neither side is readable after the fact — assigning the Value updates the
+   * mode before any comparison, and the OS query has already flipped by the time it
+   * notifies — so what was reported has to be kept rather than recomputed.
    */
   #published = {
     mode: DEFAULT_MODE,
@@ -189,13 +189,32 @@ var ThemeController = class extends Controller {
   targetValueChanged() {
     this.#targetSelector = validSelector(this.element, this.targetValue, DEFAULT_TARGET);
   }
+  /**
+   * Re-renders for a `mode` declaration changed after connect — a Turbo morph
+   * re-rendering the server's markup over the live element, or a script.
+   *
+   * A stored choice outranks the declaration: a Value that disagrees with it is written
+   * back to it, so a morph that brings the server's default never overrides what the
+   * user saved. Without one, the declaration is applied. Either way storage is left
+   * alone, and a pair on screen that moved is reported as `reconcile`, not `change` —
+   * the page moved the declaration, not a selection. The reported pair is re-seeded
+   * first, so the next selection is compared with what is on screen.
+   */
+  modeValueChanged() {
+    if (!this.#connected) return;
+    if (this.modeValue === this.#published.mode) return;
+    const stored = this.#readStored();
+    if (stored !== null && this.modeValue !== stored) this.modeValue = stored;
+    this.#applyTheme();
+    this.#reconcileControls();
+  }
   /** Re-derives the single Tab stop and ARIA for an option set that changed. */
   optionTargetConnected() {
-    if (this.#connected) this.#syncControls();
+    if (this.#connected) this.#reconcileControls();
   }
   /** Re-derives them again when an option leaves, so a Tab stop always remains. */
   optionTargetDisconnected() {
-    if (this.#connected) this.#syncControls();
+    if (this.#connected) this.#reconcileControls();
   }
   /**
    * Selects the mode the activated option declares.
@@ -227,18 +246,45 @@ var ThemeController = class extends Controller {
   #commit() {
     this.#applyTheme();
     this.#syncControls();
+    const moved = this.#settle();
+    if (moved) this.dispatch("change", { detail: moved });
+  }
+  /**
+   * Re-derives the controls from the mode on screen for a change the page made — a
+   * `mode` declaration or an option set — and reports a pair that moved since the
+   * last report as `reconcile`. An option coming or going moves neither half of the
+   * pair, so of these changes only a declaration reports.
+   */
+  #reconcileControls() {
+    this.#syncControls();
+    const moved = this.#settle();
+    if (moved) this.dispatch("reconcile", { detail: moved });
+  }
+  /**
+   * Takes the pair on screen as the reported one and returns it when it differs
+   * from the one reported before, or `null` when neither half moved.
+   *
+   * The baseline moves before anything is dispatched, so a listener that selects
+   * another mode is measured from the pair it was just told about. What is
+   * returned is a copy: the baseline has to survive a listener that writes to what
+   * it was handed, or the next unchanged operation reads as a move.
+   */
+  #settle() {
     const next = this.#current;
     const last = this.#published;
     this.#published = next;
-    if (last.mode !== next.mode || last.resolved !== next.resolved) {
-      this.dispatch("change", { detail: { ...next } });
-    }
+    if (last.mode === next.mode && last.resolved === next.resolved) return null;
+    return { ...next };
   }
-  /** The pair the `change` detail carries, read from current state. */
+  /** The pair the `change` and `reconcile` details carry, read from current state. */
   get #current() {
     return { mode: this.#mode, resolved: this.#resolved() };
   }
-  /** Writes `data-theme` + `color-scheme` (the resolved theme) onto the target. */
+  /**
+   * Writes `data-theme` + `color-scheme` (the resolved theme) onto the target.
+   *
+   * @stimeoRenderRoot
+   */
   #applyTheme() {
     const root = this.#targetElement();
     if (!root) return;
@@ -246,7 +292,11 @@ var ThemeController = class extends Controller {
     root.setAttribute("data-theme", resolved);
     root.style.setProperty("color-scheme", resolved);
   }
-  /** Keeps the radiogroup (aria-checked + roving tabindex) or toggle (aria-pressed) in sync. */
+  /**
+   * Keeps the radiogroup (aria-checked + roving tabindex) or toggle (aria-pressed) in sync.
+   *
+   * @stimeoRenderRoot
+   */
   #syncControls() {
     const options = this.optionTargets;
     if (options.length > 0) {

data/dist/controllers/time_picker_controller.js

@@ -18,6 +18,16 @@ 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/field_mirror.ts
+function writeField(field, value) {
+  if (field.value === value) return false;
+  field.value = value;
+  return true;
+}
+function commitField(target) {
+  target.dispatchEvent(new Event("change", { bubbles: true }));
+}
+
 // src/utils/microtask_coalescer.ts
 var MicrotaskCoalescer = class {
   #run;
@@ -51,6 +61,11 @@ var MicrotaskCoalescer = class {
   }
 };
 
+// src/utils/target_selector.ts
+function targetSelector(identifier, name) {
+  return `[data-${identifier}-target~="${name}"]`;
+}
+
 // src/controllers/time_picker_controller.ts
 var AM = 0;
 var PM = 1;
@@ -68,7 +83,10 @@ var TimePickerController = class extends Controller {
   };
   static actions = ["onKeydown"];
   static events = ["change", "reconcile"];
-  /** Collapses target, Value, and retained-attribute morphs into one silent render. */
+  /**
+   * Collapses target, Value, and retained-attribute morphs into one render that
+   * dispatches no `change`.
+   */
   #reconcile = new MicrotaskCoalescer(() => this.#reconcileDom());
   /** Canonical state; the displayed hour and meridiem are derived from this value. */
   #state = { hour: 0, minute: 0, second: 0 };
@@ -133,7 +151,7 @@ var TimePickerController = class extends Controller {
   onKeydown(event) {
     if (isReservedArrowChord(event)) return;
     const segment = event.target?.closest(
-      "[data-stimeo--time-picker-target~='segment']"
+      targetSelector(this.identifier, "segment")
     );
     if (!segment || !this.segmentTargets.includes(segment)) return;
     const kind = this.#kindOf(segment);
@@ -180,7 +198,7 @@ var TimePickerController = class extends Controller {
   /** Clears direct-entry state when Tab, Shift+Tab, or pointer focus leaves a segment. */
   #onFocusOut = (event) => {
     const segment = event.target?.closest(
-      "[data-stimeo--time-picker-target~='segment']"
+      targetSelector(this.identifier, "segment")
     );
     if (!segment || !this.segmentTargets.includes(segment)) return;
     this.#clearTypeBuffer();
@@ -316,8 +334,7 @@ var TimePickerController = class extends Controller {
   #commitRender() {
     this.#renderSegments();
     const value = this.#composedValue;
-    const fieldChanged = this.#writeField(value);
-    if (fieldChanged) this.fieldTarget.dispatchEvent(new Event("change", { bubbles: true }));
+    if (this.#writeField(value)) commitField(this.fieldTarget);
     if (value !== this.#lastValue) this.dispatch("change", { detail: { value } });
     this.#lastValue = value;
   }
@@ -336,9 +353,7 @@ var TimePickerController = class extends Controller {
   }
   /** Writes a composed value to the optional form field and reports whether it changed. */
   #writeField(value) {
-    if (!this.hasFieldTarget || this.fieldTarget.value === value) return false;
-    this.fieldTarget.value = value;
-    return true;
+    return this.hasFieldTarget && writeField(this.fieldTarget, value);
   }
   /** The canonical form value composed as `HH:MM[:SS]`. */
   get #composedValue() {