stimeo-ui 0.4.0 → 0.6.0

data/dist/controllers/multi_select_controller.js

@@ -2,6 +2,23 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/multi_select_controller.ts
 
+// src/utils/announce.ts
+function announce(message, options = {}) {
+  const text = message.trim();
+  if (text.length === 0) return;
+  window.dispatchEvent(
+    new CustomEvent("stimeo--announcer:announce", {
+      detail: { message: text, assertive: options.assertive === true }
+    })
+  );
+}
+function fillTemplate(template, values) {
+  return template.replace(/\{([a-zA-Z][a-zA-Z0-9]*)\}/g, (match, name) => {
+    const replacement = values[name];
+    return replacement === void 0 ? match : String(replacement);
+  });
+}
+
 // src/utils/aria_ids.ts
 var counter = 0;
 function uniqueId(prefix = "stimeo") {
@@ -35,6 +52,177 @@ 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/roving_tabindex.ts
+var RovingTabindex = class {
+  /** Returns the current ordered item elements; called on every operation. */
+  #getItems;
+  /**
+   * @param getItems - Returns the current ordered item elements. Called on every
+   *   operation so the live target list is always used.
+   */
+  constructor(getItems) {
+    this.#getItems = getItems;
+  }
+  /** Index of the currently tabbable item (`tabindex="0"`), or `-1` if none. */
+  get activeIndex() {
+    return this.#getItems().findIndex((item) => item.tabIndex === 0);
+  }
+  /**
+   * Makes exactly the item at `index` tabbable (`tabindex="0"`) and removes every
+   * other item from the Tab sequence (`tabindex="-1"`). An out-of-range `index`
+   * (e.g. `-1`) leaves all items at `-1`, which a controller can use to express
+   * "nothing is currently tabbable".
+   *
+   * @param index - Position of the item to make tabbable.
+   * @param options - Pass `{ focus: true }` to also move DOM focus to that item,
+   *   and `items` to reuse an event-scoped collection snapshot.
+   */
+  setActive(index, options = {}) {
+    const { focus = false } = options;
+    const items = options.items ?? this.#getItems();
+    items.forEach((item, i) => {
+      item.tabIndex = i === index ? 0 : -1;
+    });
+    if (focus) items[index]?.focus();
+  }
+};
+
+// src/utils/chip_row.ts
+var ChipRow = class {
+  #directionElement;
+  #getItems;
+  #getButton;
+  #onRemove;
+  #focusAfterEnd;
+  #roving = new RovingTabindex(() => this.buttons);
+  #container = null;
+  constructor(options) {
+    this.#directionElement = options.directionElement;
+    this.#getItems = options.getItems;
+    this.#getButton = options.getButton ?? ((item) => item.querySelector("button"));
+    this.#onRemove = options.onRemove;
+    this.#focusAfterEnd = options.focusAfterEnd;
+  }
+  /**
+   * Binds delegation to `container`; any row currently bound is released first.
+   * Idempotent for the same node, so target callbacks may call it freely.
+   */
+  connect(container) {
+    if (this.#container === container) return;
+    this.disconnect();
+    this.#container = container;
+    container.addEventListener("click", this.#onClick);
+    container.addEventListener("keydown", this.#onKeydown);
+  }
+  /**
+   * Releases the current row. When `container` is supplied, a stale disconnect
+   * callback cannot tear listeners off a newer replacement target.
+   */
+  disconnect(container) {
+    const current = this.#container;
+    if (!current || container !== void 0 && current !== container) return;
+    current.removeEventListener("click", this.#onClick);
+    current.removeEventListener("keydown", this.#onKeydown);
+    this.#container = null;
+  }
+  /** Current remove buttons, at most one consumer-resolved button per chip item. */
+  get buttons() {
+    return this.#entries.map(({ button }) => button);
+  }
+  /** Number of currently navigable remove buttons. */
+  get length() {
+    return this.buttons.length;
+  }
+  /** Declared-item index of the last navigable chip, or `-1` for an empty row. */
+  get lastIndex() {
+    return this.#entries.at(-1)?.itemIndex ?? -1;
+  }
+  /** Keeps exactly one button tabbable, preferring the first authored Tab stop. */
+  ensureTabStop() {
+    const buttons = this.#entries.map(({ button }) => button);
+    const active = buttons.findIndex((button) => button.tabIndex === 0);
+    const count = buttons.filter((button) => button.tabIndex === 0).length;
+    if (buttons.length > 0 && count !== 1) {
+      this.#roving.setActive(active === -1 ? 0 : active, { items: buttons });
+    }
+  }
+  /** Focuses the last chip, returning false for an empty row. */
+  focusLast() {
+    const buttons = this.#entries.map(({ button }) => button);
+    const last = buttons.length - 1;
+    if (last < 0) return false;
+    this.#roving.setActive(last, { focus: true, items: buttons });
+    return true;
+  }
+  /**
+   * Focuses the chip that followed a removed index, or the new last chip.
+   * Returns false when removal emptied the row so the consumer can rescue focus.
+   */
+  focusAfterRemoval(index) {
+    const entries = this.#entries;
+    if (entries.length === 0) return false;
+    const following = entries.findIndex((entry) => entry.itemIndex >= index);
+    this.#roving.setActive(following === -1 ? entries.length - 1 : following, {
+      focus: true,
+      items: entries.map(({ button }) => button)
+    });
+    return true;
+  }
+  /** Current remove-button entries, retaining each button's declared item index. */
+  get #entries() {
+    return this.#getItems().flatMap((item, itemIndex) => {
+      const button = this.#getButton(item);
+      return button ? [{ button, itemIndex }] : [];
+    });
+  }
+  /** Resolves a delegated event to the remove button owned by a declared chip. */
+  #entry(event) {
+    const target = event.target;
+    if (!(target instanceof Element)) return null;
+    const button = target.closest("button");
+    const entries = this.#entries;
+    const buttonIndex = entries.findIndex((entry2) => entry2.button === button);
+    if (buttonIndex === -1) return null;
+    const entry = entries[buttonIndex];
+    return { ...entry, buttonIndex, buttons: entries.map(({ button: button2 }) => button2) };
+  }
+  /** Delegates removal clicks without waiting for Stimulus to wire a new chip. */
+  #onClick = (event) => {
+    const entry = this.#entry(event);
+    if (!entry) return;
+    this.#onRemove(entry.itemIndex);
+  };
+  /** Applies the shared logical-arrow and removal policy within the chip row. */
+  #onKeydown = (event) => {
+    if (event.defaultPrevented || isReservedArrowChord(event)) return;
+    const entry = this.#entry(event);
+    if (!entry) return;
+    const buttons = entry.buttons;
+    const index = entry.buttonIndex;
+    switch (logicalArrowKey(event.key, this.#directionElement)) {
+      case "ArrowLeft":
+        if (index > 0) {
+          event.preventDefault();
+          this.#roving.setActive(index - 1, { focus: true, items: buttons });
+        }
+        break;
+      case "ArrowRight":
+        event.preventDefault();
+        if (index < buttons.length - 1) {
+          this.#roving.setActive(index + 1, { focus: true, items: buttons });
+        } else {
+          this.#focusAfterEnd();
+        }
+        break;
+      case "Delete":
+      case "Backspace":
+        event.preventDefault();
+        this.#onRemove(entry.itemIndex);
+        break;
+    }
+  };
+};
+
 // src/utils/composition_tracker.ts
 var CompositionTracker = class {
   #observedTargets = /* @__PURE__ */ new Set();
@@ -127,36 +315,32 @@ function scrollOptionIntoView(list, option) {
   }
 }
 
-// src/utils/roving_tabindex.ts
-var RovingTabindex = class {
-  /** Returns the current ordered item elements; called on every operation. */
-  #getItems;
-  /**
-   * @param getItems - Returns the current ordered item elements. Called on every
-   *   operation so the live target list is always used.
-   */
-  constructor(getItems) {
-    this.#getItems = getItems;
+// src/utils/before_cache_reset.ts
+var BeforeCacheReset = class _BeforeCacheReset {
+  /** Every subscribed instance, iterated by the one shared document listener. */
+  static #subscribers = /* @__PURE__ */ new Set();
+  /** The shared listener; installed while at least one instance is subscribed. */
+  static #onBeforeCache = () => {
+    for (const subscriber of _BeforeCacheReset.#subscribers) subscriber.#rewind();
+  };
+  #rewind;
+  /** @param rewind - the pass that returns this controller's state to its initial form. */
+  constructor(rewind) {
+    this.#rewind = rewind;
   }
-  /** Index of the currently tabbable item (`tabindex="0"`), or `-1` if none. */
-  get activeIndex() {
-    return this.#getItems().findIndex((item) => item.tabIndex === 0);
+  /** Subscribes to `turbo:before-cache`; call from `connect()`. Idempotent. */
+  activate() {
+    const first = _BeforeCacheReset.#subscribers.size === 0;
+    _BeforeCacheReset.#subscribers.add(this);
+    if (first) {
+      document.addEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
+    }
   }
-  /**
-   * Makes exactly the item at `index` tabbable (`tabindex="0"`) and removes every
-   * other item from the Tab sequence (`tabindex="-1"`). An out-of-range `index`
-   * (e.g. `-1`) leaves all items at `-1`, which a controller can use to express
-   * "nothing is currently tabbable".
-   *
-   * @param index - Position of the item to make tabbable.
-   * @param options - Pass `{ focus: true }` to also move DOM focus to that item.
-   */
-  setActive(index, { focus = false } = {}) {
-    const items = this.#getItems();
-    items.forEach((item, i) => {
-      item.tabIndex = i === index ? 0 : -1;
-    });
-    if (focus) items[index]?.focus();
+  /** Unsubscribes; call from `disconnect()`. Safe when never subscribed. */
+  deactivate() {
+    _BeforeCacheReset.#subscribers.delete(this);
+    if (_BeforeCacheReset.#subscribers.size > 0) return;
+    document.removeEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
   }
 };
 
@@ -164,6 +348,8 @@ var RovingTabindex = class {
 var TabindexLoan = class {
   #value;
   #lent = /* @__PURE__ */ new Set();
+  /** Returns live loans before Turbo can copy them into its page snapshot. */
+  #beforeCache = new BeforeCacheReset(() => this.returnAll());
   /**
    * @param value - the `tabindex` to lend. `"-1"` (the default) is
    *   programmatically focusable but not a Tab stop; `"0"` is a real Tab stop,
@@ -177,6 +363,7 @@ var TabindexLoan = class {
     if (element.hasAttribute("tabindex")) return;
     element.setAttribute("tabindex", this.#value);
     this.#lent.add(element);
+    this.#beforeCache.activate();
   }
   /** Takes back every loan whose value is still the one that was lent. */
   returnAll() {
@@ -184,6 +371,7 @@ var TabindexLoan = class {
       if (element.getAttribute("tabindex") === this.#value) element.removeAttribute("tabindex");
     }
     this.#lent.clear();
+    this.#beforeCache.deactivate();
   }
 };
 
@@ -196,21 +384,26 @@ var MultiSelectController = class extends Controller {
     "tags",
     "tag",
     "tagTemplate",
-    "status",
+    "label",
+    "remove",
     "fields"
   ];
   static values = {
     max: { type: Number, default: 0 },
     name: { type: String, default: "options[]" },
-    form: { type: String, default: "" }
+    form: { type: String, default: "" },
+    announceText: { type: String, default: "" },
+    announceRemovedText: { type: String, default: "" }
   };
   static actions = ["close", "filter", "onKeydown", "open", "toggleOption"];
-  static events = ["change", "filter"];
+  static events = ["change", "filter", "reconcile"];
   /** Stable id of the active option; the current target is resolved from the DOM. */
   #activeOptionId = null;
   /** Whether the root borrowed a tab stop to catch focus, so teardown can undo it. */
   #tabindex = new TabindexLoan();
-  /** Prevents initial/teardown target callbacks from mutating authored DOM. */
+  /** Last reconciled selection, used to distinguish state changes from derived-DOM repair. */
+  #selectionValues = [];
+  /** Whether initial normalization finished, so a fields callback cannot mirror stale state. */
   #connected = false;
   /** Collapses one batch of target callbacks into a single final-DOM reconciliation. */
   #reconcile = new MicrotaskCoalescer(() => this.#reconcileOptions());
@@ -229,17 +422,26 @@ var MultiSelectController = class extends Controller {
       this.filter();
     }
   });
-  #roving = new RovingTabindex(() => this.#removeButtons);
+  /** 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"]'),
+    onRemove: (index) => this.#removeTagAt(index),
+    focusAfterEnd: () => this.#focusInput()
+  });
   /** Starts closed, syncs chips for any pre-selected options, and listens out. */
   connect() {
-    if (this.hasInputTarget) this.#composition.observe(this.inputTarget);
-    this.#normalizeSelection();
+    this.#warnedTemplate = false;
+    this.#normalizeSelection([]);
     this.close();
     if (this.hasTagsTarget) {
-      this.tagsTarget.addEventListener("keydown", this.#onTagKeydown);
-      this.tagsTarget.addEventListener("click", this.#onTagClick);
+      this.#chipRow.connect(this.tagsTarget);
       this.#rebuildTags();
     }
+    this.#selectionValues = this.#values;
     this.#syncFields();
     document.addEventListener("click", this.#onOutsideClick, true);
     this.#connected = true;
@@ -251,10 +453,16 @@ var MultiSelectController = class extends Controller {
    * cleared before deriving afresh to avoid duplicates.
    */
   #rebuildTags() {
-    if (!this.hasTagsTarget) return;
+    if (!this.hasTagsTarget || !this.hasTagTemplateTarget) return;
+    const fragments = [];
+    for (const option of this.#selectedOptions) {
+      const fragment = this.#buildTag(option);
+      if (!fragment) return;
+      fragments.push(fragment);
+    }
     for (const tag of this.tagTargets) tag.remove();
-    for (const option of this.#selectedOptions) this.#appendTag(option);
-    if (this.#removeButtons.length > 0) this.#roving.setActive(0);
+    this.tagsTarget.append(...fragments);
+    this.#chipRow.ensureTabStop();
   }
   /** Tears down document and chip listeners on disconnect (Turbo included). */
   disconnect() {
@@ -262,10 +470,7 @@ var MultiSelectController = class extends Controller {
     this.#reconcile.cancel();
     this.#composition.disconnect();
     this.#ignorePostCompositionInput = false;
-    if (this.hasTagsTarget) {
-      this.tagsTarget.removeEventListener("keydown", this.#onTagKeydown);
-      this.tagsTarget.removeEventListener("click", this.#onTagClick);
-    }
+    this.#chipRow.disconnect();
     document.removeEventListener("click", this.#onOutsideClick, true);
     this.#releaseTabindex();
   }
@@ -275,10 +480,35 @@ var MultiSelectController = class extends Controller {
   }
   /** Cleans a removed target and reconciles active state against the surviving DOM. */
   optionTargetDisconnected(option) {
-    if (!this.#connected) return;
     option.removeAttribute("data-active");
     this.#scheduleOptionReconcile();
   }
+  /** Rebinds delegated chip interaction when Turbo replaces the tags container. */
+  tagsTargetConnected(tags) {
+    this.#chipRow.connect(tags);
+    this.#scheduleOptionReconcile();
+  }
+  /** Releases only the row that actually disconnected, never a newer replacement. */
+  tagsTargetDisconnected(tags) {
+    this.#chipRow.disconnect(tags);
+    this.#scheduleOptionReconcile();
+  }
+  /** Seeds a fields target inserted after connect from the current selection. */
+  fieldsTargetConnected() {
+    if (this.#connected) this.#syncFields();
+  }
+  /** Reconciles a runtime max change, including dropping any newly invalid overflow. */
+  maxValueChanged() {
+    this.#scheduleOptionReconcile();
+  }
+  /** Rebuilds submitted fields when their public name changes at runtime. */
+  nameValueChanged() {
+    this.#scheduleOptionReconcile();
+  }
+  /** Rebuilds submitted fields when their associated form changes at runtime. */
+  formValueChanged() {
+    this.#scheduleOptionReconcile();
+  }
   /** Schedules one reconciliation after all callbacks in the mutation batch. */
   #scheduleOptionReconcile() {
     this.#reconcile.schedule();
@@ -301,7 +531,17 @@ var MultiSelectController = class extends Controller {
     const next = this.#isClosed ? null : active && !active.hidden ? active : visible[0] ?? null;
     this.#setActive(next);
     this.#reflectEmpty();
-    this.#normalizeSelection();
+    const previous = this.#selectionValues;
+    const previousLabels = new Map(
+      this.tagTargets.map((tag) => [
+        tag.dataset.value ?? "",
+        (tag.querySelector('[data-stimeo--multi-select-target~="label"]')?.textContent ?? "").trim()
+      ])
+    );
+    const priority = [
+      .../* @__PURE__ */ new Set([...this.tagTargets.map((tag) => tag.dataset.value ?? ""), ...previous])
+    ];
+    this.#normalizeSelection(priority);
     const selected = this.#selectedOptions;
     const nextValues = selected.map((option) => this.#optionValue(option)).sort();
     const tagValues = this.tagTargets.map((tag) => tag.dataset.value ?? "").sort();
@@ -309,19 +549,52 @@ var MultiSelectController = class extends Controller {
     if (unchanged) this.#refreshTagLabels(selected);
     else this.#rebuildTags();
     this.#syncFields();
+    const values = this.#values;
+    const changed = !this.#sameSelection(previous, values);
+    this.#selectionValues = values;
+    if (!changed) return;
+    const options = new Map(selected.map((option) => [this.#optionValue(option), option]));
+    for (const value of previous) {
+      if (!values.includes(value)) {
+        this.#announceTransition(false, previousLabels.get(value) || value, value, values.length);
+      }
+    }
+    for (const value of values) {
+      if (previous.includes(value)) continue;
+      const option = options.get(value);
+      this.#announceTransition(true, this.#optionLabel(option), value, values.length);
+    }
+    this.dispatch("reconcile", { detail: { values } });
   }
   /**
-   * Gives every option an explicit `aria-selected`, without changing which ones
-   * the author chose. An absent value means "not selectable" in ARIA, so a
-   * forgotten attribute hides a selectable option. Several `true` is the normal
-   * case here — the list is `aria-multiselectable` — so nothing is dropped.
+   * Gives every option an explicit `aria-selected` and enforces the current cap.
+   * Priority preserves existing chip order at runtime; a fresh connection passes
+   * no priority, so deterministic option DOM order chooses the initial survivors.
    */
-  #normalizeSelection() {
-    for (const option of this.optionTargets) {
-      if (option.getAttribute("aria-selected") !== "true") {
-        option.setAttribute("aria-selected", "false");
+  #normalizeSelection(priority) {
+    const selected = this.optionTargets.filter(
+      (option) => option.getAttribute("aria-selected") === "true"
+    );
+    const limit = this.#selectionLimit;
+    const kept = /* @__PURE__ */ new Set();
+    if (limit === 0) {
+      for (const option of selected) kept.add(option);
+    } else {
+      for (const value of priority) {
+        if (kept.size >= limit) break;
+        const option = selected.find(
+          (candidate) => !kept.has(candidate) && this.#optionValue(candidate) === value
+        );
+        if (option) kept.add(option);
+      }
+      for (const option of selected) {
+        if (kept.size >= limit) break;
+        kept.add(option);
       }
     }
+    for (const option of this.optionTargets) {
+      option.setAttribute("aria-selected", String(kept.has(option)));
+    }
   }
   /**
    * Tracks an input added initially or after connect, and makes it describe the
@@ -344,6 +617,7 @@ var MultiSelectController = class extends Controller {
   }
   /** 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;
@@ -368,10 +642,14 @@ var MultiSelectController = class extends Controller {
    * opening is skipped entirely, where {@link close} still closes.
    */
   open() {
-    if (!this.hasListTarget || !this.hasInputTarget) return;
+    if (!this.hasListTarget || !this.hasInputTarget) {
+      this.#reflectEmpty();
+      return;
+    }
     this.listTarget.hidden = false;
     this.inputTarget.setAttribute("aria-expanded", "true");
     if (!this.#activeOption) this.#setActive(this.#visibleOptions[0] ?? null);
+    this.#reflectEmpty();
   }
   /**
    * Closes the list and clears the active option.
@@ -385,16 +663,16 @@ var MultiSelectController = class extends Controller {
    * active option, so only the `aria-expanded` write is guarded.
    */
   close() {
-    if (!this.hasListTarget) return;
-    this.listTarget.hidden = true;
+    if (this.hasListTarget) this.listTarget.hidden = true;
     this.#setActive(null);
-    if (!this.hasInputTarget) return;
-    this.inputTarget.setAttribute("aria-expanded", "false");
+    if (this.hasInputTarget) this.inputTarget.setAttribute("aria-expanded", "false");
+    this.#reflectEmpty();
   }
   /** Routes input keyboard interaction per the multi-select combobox model. */
   onKeydown(event) {
     if (event.defaultPrevented) return;
     if (isReservedArrowChord(event)) return;
+    if (!this.hasInputTarget) return;
     if (this.#composition.isComposing(event)) return;
     this.#reconcileActiveForInteraction();
     switch (logicalArrowKey(event.key, this.element)) {
@@ -437,17 +715,17 @@ var MultiSelectController = class extends Controller {
         break;
       case "Backspace":
         if (this.inputTarget.value === "") {
-          const buttons = this.#removeButtons;
-          if (buttons.length > 0) {
+          const last = this.#chipRow.lastIndex;
+          if (last >= 0) {
             event.preventDefault();
-            this.#removeTagAt(buttons.length - 1);
+            this.#removeTagAt(last, "input");
           }
         }
         break;
       case "ArrowLeft":
-        if (this.inputTarget.value === "" && this.#removeButtons.length > 0) {
+        if (this.inputTarget.value === "" && this.#chipRow.length > 0) {
           event.preventDefault();
-          this.#roving.setActive(this.#removeButtons.length - 1, { focus: true });
+          this.#chipRow.focusLast();
         }
         break;
       case "Tab":
@@ -485,8 +763,8 @@ var MultiSelectController = class extends Controller {
    * Unlike the other {@link #focusInput} callers, the element that held focus has
    * just left the DOM, so "leave it alone" is not an option — the browser already
    * dropped it to `<body>`. The root borrows a `tabindex="-1"` just-in-time (not a
-   * Tab stop, handed back on teardown). Focus that landed on a real element is
-   * left alone, so a chip removed out of band never steals it.
+   * Tab stop, handed back before Turbo caches or on teardown). Focus that landed
+   * on a real element is left alone, so a chip removed out of band never steals it.
    */
   #focusAfterLastTag() {
     if (this.hasInputTarget) {
@@ -509,43 +787,40 @@ var MultiSelectController = class extends Controller {
   #releaseTabindex() {
     this.#tabindex.returnAll();
   }
-  /**
-   * Removes the chip whose remove button was clicked, deselecting its option.
-   * Delegated on the tags container (like `#onTagKeydown`) rather than bound
-   * per chip via `data-action`, so it works the instant a chip is appended without
-   * waiting on Stimulus to wire a freshly created element.
-   */
-  #onTagClick = (event) => {
-    const button = event.target.closest("button");
-    if (!button || !this.tagsTarget.contains(button)) return;
-    const index = this.#removeButtons.indexOf(button);
-    if (index !== -1) this.#removeTagAt(index);
-  };
   /** Moves the active option by `delta` among visible options, wrapping. */
   #moveActive(delta) {
     const visible = this.#visibleOptions;
-    if (visible.length === 0) return;
-    const current = this.#activeOption ? visible.indexOf(this.#activeOption) : -1;
+    const active = this.#activeOption;
+    const current = visible.indexOf(active);
     const candidate = current === -1 ? delta > 0 ? 0 : visible.length - 1 : current + delta;
     const next = (candidate + visible.length) % visible.length;
     this.#setActive(visible[next] ?? null);
   }
-  /** Selects/deselects `option`, honoring `max`, and syncs chip + live region. */
+  /** Selects/deselects `option`, honoring `max`, and syncs chip + announcement. */
   #toggleSelection(option) {
     const selected = option.getAttribute("aria-selected") === "true";
-    if (!selected && this.maxValue > 0 && this.#selectedOptions.length >= this.maxValue) {
+    const limit = this.#selectionLimit;
+    if (!selected && limit > 0 && this.#selectedOptions.length >= limit) {
       return;
     }
-    option.setAttribute("aria-selected", String(!selected));
     if (selected) {
+      option.setAttribute("aria-selected", "false");
       this.#removeTagFor(option);
     } else {
-      this.#appendTag(option);
+      if (this.hasTagTemplateTarget && !this.#appendTag(option)) return;
+      option.setAttribute("aria-selected", "true");
     }
-    this.#announce(this.#optionLabel(option));
     this.#refreshRoving();
     this.#syncFields();
-    this.dispatch("change", { detail: { values: this.#values } });
+    const values = this.#values;
+    this.#selectionValues = values;
+    this.#announceTransition(
+      !selected,
+      this.#optionLabel(option),
+      this.#optionValue(option),
+      values.length
+    );
+    this.dispatch("change", { detail: { values } });
   }
   /**
    * Re-reads each chip's label from its option, in place.
@@ -560,31 +835,81 @@ var MultiSelectController = class extends Controller {
     const options = new Map(selected.map((option) => [this.#optionValue(option), option]));
     for (const tag of this.tagTargets) {
       const option = options.get(tag.dataset.value ?? "");
-      if (!option) continue;
       const text = this.#optionLabel(option);
-      const label = tag.querySelector('[data-multi-select-slot="label"]');
-      if (label && label.textContent !== text) label.textContent = text;
-      const button = tag.querySelector("button");
-      const name = `Remove ${text}`;
-      if (button && button.getAttribute("aria-label") !== name) {
-        button.setAttribute("aria-label", name);
-      }
+      const label = tag.querySelector('[data-stimeo--multi-select-target~="label"]');
+      const button = tag.querySelector(
+        'button[data-stimeo--multi-select-target~="remove"]'
+      );
+      const name = this.#removeName(text, this.#optionValue(option));
+      if (!label || !button || !name) continue;
+      if (label.textContent !== text) label.textContent = text;
+      if (button.getAttribute("aria-label") !== name) button.setAttribute("aria-label", name);
     }
   }
   /** Builds one chip from the template for `option`. */
   #appendTag(option) {
-    if (!this.hasTagTemplateTarget || !this.hasTagsTarget) return;
+    if (!this.hasTagsTarget) {
+      this.#warnTemplate('a "tags" target to append the chip to');
+      return false;
+    }
+    const fragment = this.#buildTag(option);
+    if (!fragment) return false;
+    this.tagsTarget.appendChild(fragment);
+    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.
+   */
+  #buildTag(option) {
     const fragment = this.tagTemplateTarget.content.cloneNode(true);
-    const tag = fragment.querySelector('[data-stimeo--multi-select-target="tag"]');
-    const label = fragment.querySelector('[data-multi-select-slot="label"]');
-    const button = fragment.querySelector("button");
-    if (!tag || !button) return;
+    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);
-    tag.dataset.value = this.#optionValue(option);
-    if (label) label.textContent = text;
-    button.setAttribute("aria-label", `Remove ${text}`);
+    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;
-    this.tagsTarget.appendChild(fragment);
+    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;
+  }
+  /** 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();
+    return template ? fillTemplate(template, { label, value }) : null;
   }
   /** Removes the chip mirroring `option`, if present. */
   #removeTagFor(option) {
@@ -593,52 +918,30 @@ var MultiSelectController = class extends Controller {
     tag?.remove();
   }
   /** Removes chip `index` and deselects its option, re-homing focus. */
-  #removeTagAt(index) {
+  #removeTagAt(index, focus = "neighbor") {
     const tag = this.tagTargets[index];
     if (!tag) return;
     const value = tag.dataset.value ?? "";
     const option = this.optionTargets.find((candidate) => this.#optionValue(candidate) === value);
     if (option) option.setAttribute("aria-selected", "false");
     tag.remove();
-    this.#announce(option ? this.#optionLabel(option) : value);
     this.#refreshRoving();
     this.#syncFields();
-    this.dispatch("change", { detail: { values: this.#values } });
-    const remaining = this.#removeButtons;
-    if (remaining.length === 0) {
-      this.#focusAfterLastTag();
-    } else {
-      this.#roving.setActive(Math.min(index, remaining.length - 1), { focus: true });
+    const values = this.#values;
+    this.#selectionValues = values;
+    this.#announceTransition(
+      false,
+      option ? this.#optionLabel(option) : value,
+      value,
+      values.length
+    );
+    this.dispatch("change", { detail: { values } });
+    if (focus === "input") {
+      this.#focusInput();
+      return;
     }
+    if (!this.#chipRow.focusAfterRemoval(index)) this.#focusAfterLastTag();
   }
-  /** Arrow navigation and deletion within the chip list (delegated). */
-  #onTagKeydown = (event) => {
-    if (event.defaultPrevented) return;
-    if (isReservedArrowChord(event)) return;
-    const button = event.target.closest("button");
-    if (!button) return;
-    const buttons = this.#removeButtons;
-    const index = buttons.indexOf(button);
-    if (index === -1) return;
-    switch (logicalArrowKey(event.key, this.element)) {
-      case "ArrowLeft":
-        if (index > 0) {
-          event.preventDefault();
-          this.#roving.setActive(index - 1, { focus: true });
-        }
-        break;
-      case "ArrowRight":
-        event.preventDefault();
-        if (index < buttons.length - 1) this.#roving.setActive(index + 1, { focus: true });
-        else this.#focusInput();
-        break;
-      case "Delete":
-      case "Backspace":
-        event.preventDefault();
-        this.#removeTagAt(index);
-        break;
-    }
-  };
   /**
    * Marks `option` active via `data-active` and the input's
    * `aria-activedescendant` (the attribute is removed, not emptied, when null).
@@ -669,7 +972,7 @@ var MultiSelectController = class extends Controller {
     const resolved = this.#activeOption;
     const active = resolved && !resolved.hidden ? resolved : null;
     const marked = this.optionTargets.filter((candidate) => candidate.hasAttribute("data-active"));
-    const idref = this.hasInputTarget ? this.inputTarget.getAttribute("aria-activedescendant") : null;
+    const idref = this.inputTarget.getAttribute("aria-activedescendant");
     if (!active || marked.length !== 1 || marked[0] !== active || idref !== activeId) {
       this.#setActive(active);
     }
@@ -703,12 +1006,19 @@ var MultiSelectController = class extends Controller {
   }
   /** Keeps exactly one chip remove button tabbable after the set changes. */
   #refreshRoving() {
-    if (this.#removeButtons.length > 0 && this.#roving.activeIndex === -1)
-      this.#roving.setActive(0);
+    this.#chipRow.ensureTabStop();
   }
-  /** Mirrors the changed option label into the live region. */
-  #announce(text) {
-    if (this.hasStatusTarget) this.statusTarget.textContent = text;
+  /** Sends one localized selection transition through the page's shared announcer. */
+  #announceTransition(selected, label, value, count) {
+    const template = selected ? this.announceTextValue : this.announceRemovedTextValue;
+    announce(fillTemplate(template, { label, value, count }));
+  }
+  /** Whether two arrays represent the same selection set, independent of DOM order. */
+  #sameSelection(left, right) {
+    if (left.length !== right.length) return false;
+    const a = [...left].sort();
+    const b = [...right].sort();
+    return a.every((value, index) => value === b[index]);
   }
   /** Closes the list on a click outside the controller element. */
   #onOutsideClick = (event) => {
@@ -728,9 +1038,7 @@ var MultiSelectController = class extends Controller {
   }
   /** Current active target resolved by stable id, never a detached node reference. */
   get #activeOption() {
-    const activeId = this.#activeOptionId;
-    if (activeId === null) return null;
-    return this.optionTargets.find((option) => option.id === activeId) ?? null;
+    return this.optionTargets.find((option) => option.id === this.#activeOptionId) ?? null;
   }
   /** Options currently selected. */
   get #selectedOptions() {
@@ -740,9 +1048,10 @@ var MultiSelectController = class extends Controller {
   get #values() {
     return this.#selectedOptions.map((option) => this.#optionValue(option));
   }
-  /** The chip remove buttons in order (the roving navigation set). */
-  get #removeButtons() {
-    return this.hasTagsTarget ? Array.from(this.tagsTarget.querySelectorAll("button")) : [];
+  /** Normalized cardinality cap: zero is unlimited and positive fractions round down. */
+  get #selectionLimit() {
+    if (!Number.isFinite(this.maxValue) || this.maxValue <= 0) return 0;
+    return Math.max(1, Math.floor(this.maxValue));
   }
   /** Whether the list is currently hidden. */
   get #isClosed() {