stimeo-ui 0.15.0 → 0.16.0

package/dist/controllers/multi_select_controller.js

@@ -52,6 +52,33 @@ 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);
+}
+function readLabel(slot) {
+  if (!slot) return "";
+  let text = "";
+  for (const node of Array.from(slot.childNodes)) {
+    if (node.nodeType === Node.TEXT_NODE) text += node.nodeValue ?? "";
+  }
+  return text.trim();
+}
+
 // src/utils/roving_tabindex.ts
 var RovingTabindex = class {
   /** Returns the current ordered item elements; called on every operation. */
@@ -99,7 +126,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;
   }
@@ -224,11 +251,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;
@@ -238,6 +273,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. */
@@ -245,31 +281,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;
@@ -315,6 +397,47 @@ function scrollOptionIntoView(list, option) {
   }
 }
 
+// src/utils/state_regions.ts
+var StateRegions = class {
+  #whenTrue;
+  #whenFalse;
+  #taken = /* @__PURE__ */ new WeakSet();
+  constructor(options) {
+    this.#whenTrue = options.whenTrue;
+    this.#whenFalse = options.whenFalse ?? null;
+  }
+  /** Shows the regions inside `host` that belong to `isTrue` and hides the others. */
+  reflect(host, isTrue) {
+    const shown = this.#inside(host, this.#whenTrue());
+    if (!this.#whenFalse) {
+      for (const region of shown) this.#write(region, !isTrue);
+      return;
+    }
+    const hiddenSide = this.#inside(host, this.#whenFalse());
+    if (shown.length === 0 || hiddenSide.length === 0) {
+      for (const region of shown) this.#give(region);
+      for (const region of hiddenSide) this.#give(region);
+      return;
+    }
+    for (const region of shown) this.#write(region, !isTrue);
+    for (const region of hiddenSide) this.#write(region, isTrue);
+  }
+  /** Writes `hidden` where it moves, noting which regions it takes out of view. */
+  #write(region, hidden) {
+    if (hidden) this.#taken.add(region);
+    else this.#taken.delete(region);
+    if (region.hidden !== hidden) region.hidden = hidden;
+  }
+  /** Returns a region this instance hid; one it never hid keeps what it carries. */
+  #give(region) {
+    if (this.#taken.delete(region)) region.hidden = false;
+  }
+  /** The declared regions that sit within `host`, which may be the host itself. */
+  #inside(host, regions) {
+    return regions.filter((region) => host.contains(region));
+  }
+};
+
 // src/utils/before_cache_reset.ts
 var BeforeCacheReset = class _BeforeCacheReset {
   /** Every subscribed instance, iterated by the one shared document listener. */
@@ -375,6 +498,85 @@ var TabindexLoan = 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/multi_select_controller.ts
 var MultiSelectController = class extends Controller {
   static targets = [
@@ -386,7 +588,8 @@ var MultiSelectController = class extends Controller {
     "tagTemplate",
     "label",
     "remove",
-    "fields"
+    "fields",
+    "empty"
   ];
   static values = {
     max: { type: Number, default: 0 },
@@ -405,36 +608,37 @@ var MultiSelectController = class extends Controller {
   #selectionValues = [];
   /** Whether initial normalization finished, so a fields callback cannot mirror stale state. */
   #connected = false;
+  /** Owns `hidden` on the regions declared for the empty-result state. */
+  #emptyRegion = new StateRegions({ whenTrue: () => this.emptyTargets });
   /** Collapses one batch of target callbacks into a single final-DOM reconciliation. */
   #reconcile = new MicrotaskCoalescer(() => this.#reconcileOptions());
-  /** Absorbs the browser's redundant final input after compositionend. */
-  #ignorePostCompositionInput = false;
   /** Owns IME lifecycle state; confirmed text emits one filter result. */
   #composition = new CompositionTracker({
-    onStart: () => {
-      this.#ignorePostCompositionInput = false;
-    },
-    onEnd: () => {
-      this.#ignorePostCompositionInput = true;
-      queueMicrotask(() => {
-        this.#ignorePostCompositionInput = false;
-      });
-      this.filter();
-    }
+    // Apply the confirmed query even in browsers that omit a final input event;
+    // where one follows, the tracker folds it so consumers receive one filter
+    // event for the confirmed text, not two.
+    onEnd: () => this.filter()
+  });
+  /** Builds one chip from the authored template and owns its diagnostic. */
+  #rows = new TemplateRow({
+    identifier: this.identifier,
+    root: "tag",
+    required: ["label"],
+    button: "remove",
+    outcome: "changed no selection",
+    noun: "chip template"
   });
-  /** Whether this connection already reported its unusable chip template. */
-  #warnedTemplate = false;
   /** Shared delegated interaction for the replaceable row of removable chips. */
   #chipRow = new ChipRow({
     directionElement: this.element,
     getItems: () => this.tagTargets,
-    getButton: (tag) => tag.querySelector('button[data-stimeo--multi-select-target~="remove"]'),
+    getButton: (tag) => matchingPart(tag, `button${this.#rows.selector("remove")}`),
     onRemove: (index) => this.#removeTagAt(index),
     focusAfterEnd: () => this.#focusInput()
   });
   /** Starts closed, syncs chips for any pre-selected options, and listens out. */
   connect() {
-    this.#warnedTemplate = false;
+    this.#rows.connect();
     this.#normalizeSelection([]);
     this.close();
     if (this.hasTagsTarget) {
@@ -454,14 +658,14 @@ var MultiSelectController = class extends Controller {
    */
   #rebuildTags() {
     if (!this.hasTagsTarget || !this.hasTagTemplateTarget) return;
-    const fragments = [];
+    const chips = [];
     for (const option of this.#selectedOptions) {
-      const fragment = this.#buildTag(option);
-      if (!fragment) return;
-      fragments.push(fragment);
+      const chip = this.#buildTag(option);
+      if (!chip) return;
+      chips.push(chip);
     }
     for (const tag of this.tagTargets) tag.remove();
-    this.tagsTarget.append(...fragments);
+    this.tagsTarget.append(...chips);
     this.#chipRow.ensureTabStop();
   }
   /** Tears down document and chip listeners on disconnect (Turbo included). */
@@ -469,7 +673,6 @@ var MultiSelectController = class extends Controller {
     this.#connected = false;
     this.#reconcile.cancel();
     this.#composition.disconnect();
-    this.#ignorePostCompositionInput = false;
     this.#chipRow.disconnect();
     document.removeEventListener("click", this.#onOutsideClick, true);
     this.#releaseTabindex();
@@ -483,6 +686,10 @@ var MultiSelectController = class extends Controller {
     option.removeAttribute("data-active");
     this.#scheduleOptionReconcile();
   }
+  /** Settles a region inserted after connect on the side of the current state. */
+  emptyTargetConnected() {
+    if (this.#connected) this.#reflectEmpty();
+  }
   /** Rebinds delegated chip interaction when Turbo replaces the tags container. */
   tagsTargetConnected(tags) {
     this.#chipRow.connect(tags);
@@ -524,6 +731,8 @@ var MultiSelectController = class extends Controller {
    * for an unrelated option would drop focus from a chip's remove button to
    * `<body>`, losing the keyboard user's place for something that did not concern
    * them.
+   *
+   * @stimeoRenderRoot
    */
   #reconcileOptions() {
     const visible = this.#visibleOptions;
@@ -535,7 +744,7 @@ var MultiSelectController = class extends Controller {
     const previousLabels = new Map(
       this.tagTargets.map((tag) => [
         tag.dataset.value ?? "",
-        (tag.querySelector('[data-stimeo--multi-select-target~="label"]')?.textContent ?? "").trim()
+        readLabel(matchingPart(tag, this.#rows.selector("label")))
       ])
     );
     const priority = [
@@ -613,15 +822,11 @@ var MultiSelectController = class extends Controller {
   /** Removes composition listeners when the active input is replaced or removed. */
   inputTargetDisconnected(input) {
     this.#composition.unobserve(input);
-    this.#ignorePostCompositionInput = false;
   }
   /** Filters confirmed input text, opens, and re-seeds the active option. */
   filter(event) {
     if (!this.hasInputTarget) return;
-    if (event && this.#ignorePostCompositionInput) {
-      this.#ignorePostCompositionInput = false;
-      return;
-    }
+    if (event && this.#composition.consumesConfirmedInput(event)) return;
     if (this.#composition.isComposing(event)) return;
     const query = this.inputTarget.value.trim().toLowerCase();
     for (const option of this.optionTargets) {
@@ -639,7 +844,8 @@ var MultiSelectController = class extends Controller {
    *
    * Needs the input, which owns `aria-expanded` and `aria-activedescendant`: a
    * list shown without one is a popup no assistive technology is told about. So
-   * opening is skipped entirely, where {@link close} still closes.
+   * opening is skipped entirely, where {@link MultiSelectController.close | close}
+   * still closes.
    */
   open() {
     if (!this.hasListTarget || !this.hasInputTarget) {
@@ -811,7 +1017,7 @@ var MultiSelectController = class extends Controller {
       option.setAttribute("aria-selected", "true");
     }
     this.#refreshRoving();
-    this.#syncFields();
+    this.#syncFields(true);
     const values = this.#values;
     this.#selectionValues = values;
     this.#announceTransition(
@@ -836,79 +1042,47 @@ var MultiSelectController = class extends Controller {
     for (const tag of this.tagTargets) {
       const option = options.get(tag.dataset.value ?? "");
       const text = this.#optionLabel(option);
-      const label = tag.querySelector('[data-stimeo--multi-select-target~="label"]');
-      const button = tag.querySelector(
-        'button[data-stimeo--multi-select-target~="remove"]'
-      );
+      const label = matchingPart(tag, this.#rows.selector("label"));
+      const button = matchingPart(tag, `button${this.#rows.selector("remove")}`);
       const name = this.#removeName(text, this.#optionValue(option));
       if (!label || !button || !name) continue;
-      if (label.textContent !== text) label.textContent = text;
+      if (readLabel(label) !== text) writeLabel(label, text);
       if (button.getAttribute("aria-label") !== name) button.setAttribute("aria-label", name);
     }
   }
   /** Builds one chip from the template for `option`. */
   #appendTag(option) {
     if (!this.hasTagsTarget) {
-      this.#warnTemplate('a "tags" target to append the chip to');
+      this.#rows.report('a "tags" target to append the chip to');
       return false;
     }
-    const fragment = this.#buildTag(option);
-    if (!fragment) return false;
-    this.tagsTarget.appendChild(fragment);
+    const chip = this.#buildTag(option);
+    if (!chip) return false;
+    this.tagsTarget.appendChild(chip);
     return true;
   }
   /**
    * Builds one fully named chip without mutating the live tag row, or `null`
-   * when the authored template cannot produce one. Both callers establish the
-   * template first: a field authored without `tagTemplate` renders no chips at
-   * all — a supported configuration — and never reaches here.
+   * when the authored template cannot produce one — in which case the selection
+   * stays untouched and the row names the missing part once per connection.
+   * Both callers establish the template first: a field authored without
+   * `tagTemplate` renders no chips at all — a supported configuration — and
+   * never reaches here.
    */
   #buildTag(option) {
-    const fragment = this.tagTemplateTarget.content.cloneNode(true);
-    const tag = fragment.querySelector('[data-stimeo--multi-select-target~="tag"]');
-    const label = fragment.querySelector(
-      '[data-stimeo--multi-select-target~="label"]'
-    );
-    const button = fragment.querySelector(
-      'button[data-stimeo--multi-select-target~="remove"]'
-    );
     const text = this.#optionLabel(option);
     const value = this.#optionValue(option);
-    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 = text;
-    button.setAttribute("aria-label", fillTemplate(removeName, { label: text, value }));
-    button.tabIndex = -1;
-    return fragment;
-  }
-  /**
-   * Reports an unusable chip template to the author, once per connection.
-   *
-   * The selection itself stays untouched — no `aria-selected`, chip, hidden
-   * field, announcement, or event moves. Without this line the only symptom is
-   * a listbox whose options refuse to select, 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.
-   */
-  #warnTemplate(missing) {
-    if (!this.#warnedTemplate) {
-      this.#warnedTemplate = true;
-      console.warn(
-        `Stimeo UI: "${this.identifier}" changed no selection because its chip template lacks ${missing}.`
-      );
-    }
-    return null;
+    const row = this.#rows.instantiate(this.tagTemplateTarget, { label: text, value });
+    if (!row) return null;
+    row.root.dataset.value = value;
+    writeLabel(row.slots.label, text);
+    row.button.tabIndex = -1;
+    return row.root;
   }
   /** Expands the current template's localized remove-button name. */
   #removeName(label, value) {
     if (!this.hasTagTemplateTarget) return null;
-    const template = this.tagTemplateTarget.content.querySelector('button[data-stimeo--multi-select-target~="remove"]')?.getAttribute("aria-label")?.trim();
+    const template = this.tagTemplateTarget.content.querySelector(`button${this.#rows.selector("remove")}`)?.getAttribute("aria-label")?.trim();
     return template ? fillTemplate(template, { label, value }) : null;
   }
   /** Removes the chip mirroring `option`, if present. */
@@ -926,7 +1100,7 @@ var MultiSelectController = class extends Controller {
     if (option) option.setAttribute("aria-selected", "false");
     tag.remove();
     this.#refreshRoving();
-    this.#syncFields();
+    this.#syncFields(true);
     const values = this.#values;
     this.#selectionValues = values;
     this.#announceTransition(
@@ -947,9 +1121,9 @@ var MultiSelectController = class extends Controller {
    * `aria-activedescendant` (the attribute is removed, not emptied, when null).
    *
    * The state half runs even with no input, so a `close()` that cannot touch ARIA
-   * still clears it: {@link open} seeds an active option only when there is none,
-   * so a stale one makes the next open skip the seeding and a replacement input
-   * gets no `aria-activedescendant` at all.
+   * still clears it: {@link MultiSelectController.open | open} seeds an active
+   * option only when there is none, so a stale one makes the next open skip the
+   * seeding and a replacement input gets no `aria-activedescendant` at all.
    */
   #setActive(option) {
     const activeId = option ? ensureId(option, "stimeo-ms-opt") : null;
@@ -977,12 +1151,14 @@ var MultiSelectController = class extends Controller {
       this.#setActive(active);
     }
   }
-  /** Reflects whether the open list currently has no visible option targets. */
+  /**
+   * Reflects whether the open list currently has no visible option targets, on
+   * the root's state attribute and on the regions declared for that state.
+   */
   #reflectEmpty() {
-    this.element.toggleAttribute(
-      "data-stimeo--multi-select-empty",
-      !this.#isClosed && this.#visibleOptions.length === 0
-    );
+    const empty = !this.#isClosed && this.#visibleOptions.length === 0;
+    this.element.toggleAttribute(`data-${this.identifier}-empty`, empty);
+    this.#emptyRegion.reflect(this.element, empty);
   }
   /**
    * Mirrors the selected values into named hidden inputs under the `fields`
@@ -991,24 +1167,22 @@ var MultiSelectController = class extends Controller {
    * `form` value is set, each input gets a matching `form` attribute so the picker
    * can submit with a `<form>` it lives outside of.
    */
-  #syncFields() {
+  #syncFields(notify = false) {
     if (!this.hasFieldsTarget) return;
-    this.fieldsTarget.replaceChildren(
-      ...this.#values.map((value) => {
-        const input = document.createElement("input");
-        input.type = "hidden";
-        input.name = this.nameValue;
-        input.value = value;
-        if (this.hasFormValue && this.formValue !== "") input.setAttribute("form", this.formValue);
-        return input;
-      })
-    );
+    const options = { name: this.nameValue, form: this.formValue };
+    if (writeFields(this.fieldsTarget, this.#values, options) && notify) {
+      commitField(this.fieldsTarget);
+    }
   }
   /** Keeps exactly one chip remove button tabbable after the set changes. */
   #refreshRoving() {
     this.#chipRow.ensureTabStop();
   }
-  /** Sends one localized selection transition through the page's shared announcer. */
+  /**
+   * Sends one localized selection transition through the page's shared announcer.
+   *
+   * @stimeoRuntimeOnly The texts word the one announcement of this change.
+   */
   #announceTransition(selected, label, value, count) {
     const template = selected ? this.announceTextValue : this.announceRemovedTextValue;
     announce(fillTemplate(template, { label, value, count }));