stimeo-ui 0.15.0 → 0.16.0

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