stimeo-ui 0.16.0 → 0.17.0

data/dist/controllers/multi_select_controller.js

@@ -1,8 +1,27 @@
 import { Controller } from '@hotwired/stimulus';
 
-// src/controllers/multi_select_controller.ts
+var FOCUS_EVENTS = /* @__PURE__ */ new Set(["blur", "focus", "focusin", "focusout"]);
+var POINTER_EVENTS = /* @__PURE__ */ new Set(["mouseenter", "mouseleave", "pointerenter", "pointerleave"]);
+function stateReasonFor(event) {
+  if (!event) return "api";
+  if (FOCUS_EVENTS.has(event.type)) return "focus";
+  if (POINTER_EVENTS.has(event.type)) return "pointer";
+  return "user";
+}
+
+function actionSource(source) {
+  if (source instanceof HTMLElement) {
+    return { event: null, host: source, origin: source, reason: "api" };
+  }
+  const event = source ?? null;
+  return {
+    event,
+    host: event?.currentTarget instanceof Element ? event.currentTarget : null,
+    origin: event?.target instanceof Element ? event.target : null,
+    reason: stateReasonFor(event)
+  };
+}
 
-// src/utils/announce.ts
 function announce(message, options = {}) {
   const text = message.trim();
   if (text.length === 0) return;
@@ -19,13 +38,22 @@ function fillTemplate(template, values) {
   });
 }
 
-// src/utils/aria_ids.ts
-var counter = 0;
+function sharedRegistry(key, create) {
+  const symbol = Symbol.for(key);
+  const scope = globalThis;
+  const existing = scope[symbol];
+  if (existing !== void 0) return existing;
+  const registry = create();
+  Object.defineProperty(globalThis, symbol, { value: registry });
+  return registry;
+}
+
+var ids = sharedRegistry("stimeo-ui.aria-ids.registry.v1", () => ({ counter: 0 }));
 function uniqueId(prefix = "stimeo") {
   let candidate;
   do {
-    counter += 1;
-    candidate = `${prefix}-${counter}`;
+    ids.counter += 1;
+    candidate = `${prefix}-${ids.counter}`;
   } while (typeof document !== "undefined" && document.getElementById(candidate) !== null);
   return candidate;
 }
@@ -36,12 +64,10 @@ function ensureId(element, prefix = "stimeo") {
   return id;
 }
 
-// src/utils/logical_scroll.ts
 function isRtl(element) {
   return window.getComputedStyle(element).direction === "rtl";
 }
 
-// src/utils/arrow_step.ts
 function logicalArrowKey(key, element) {
   if (key !== "ArrowRight" && key !== "ArrowLeft") return key;
   if (!isRtl(element)) return key;
@@ -52,7 +78,143 @@ 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 isAttributeValue(value) {
+  return value === null || typeof value === "string";
+}
+function readLeaseRecord(element, record) {
+  try {
+    const parsed = JSON.parse(element.getAttribute(record) ?? "null");
+    if (!Array.isArray(parsed)) return void 0;
+    const [original, written, ...rest] = parsed;
+    const linked = rest[0] !== false;
+    const beneath = linked ? rest : rest.slice(1);
+    if (!beneath.every((under) => typeof under === "string")) return void 0;
+    return isAttributeValue(original) && isAttributeValue(written) ? { original, written, linked, beneath } : void 0;
+  } catch {
+    return void 0;
+  }
+}
+var AttributeLease = class _AttributeLease {
+  static #registry = sharedRegistry(
+    "stimeo-ui.attribute-lease.registry.v1",
+    () => ({ stacks: /* @__PURE__ */ new WeakMap(), names: /* @__PURE__ */ new Map() })
+  );
+  #attribute;
+  #record;
+  #base;
+  #held = /* @__PURE__ */ new Set();
+  constructor(attribute, owner, options = {}) {
+    this.#attribute = attribute;
+    this.#record = `data-${owner}-${attribute}-lease`;
+    this.#base = options.base === true;
+    const names = _AttributeLease.#registry.names;
+    names.set(attribute, (names.get(attribute) ?? /* @__PURE__ */ new Set()).add(this.#record));
+  }
+  write(element, value) {
+    const stack = this.#stack(element);
+    const hold = this.#take(stack) ?? this.#acquire(element, stack);
+    this.#held.add(element);
+    const shows = !this.#covered(element, stack, hold);
+    hold.written = value;
+    this.#mark(element, stack);
+    if (shows) this.#reflect(element, value);
+  }
+  return(element) {
+    const held = this.#held.delete(element);
+    const known = _AttributeLease.#registry.stacks.get(element)?.has(this.#attribute);
+    const stack = held || known || element.hasAttribute(this.#record) ? this.#stack(element) : [];
+    const hold = this.#take(stack);
+    if (!hold) return false;
+    const carries = element.getAttribute(this.#attribute) === hold.written;
+    const owns = carries && !this.#covered(element, stack, hold);
+    const index = stack.indexOf(hold);
+    stack.splice(index, 1);
+    const above = stack[index];
+    if (above) above.linked &&= hold.linked;
+    this.#mark(element, stack);
+    if (!owns) return true;
+    const below = hold.linked ? stack[index - 1] : void 0;
+    this.#reflect(element, below ? below.written : hold.original);
+    return true;
+  }
+  returnAll() {
+    for (const element of Array.from(this.#held)) this.return(element);
+  }
+  #stack(element) {
+    const stacks = _AttributeLease.#registry.stacks;
+    const byAttribute = stacks.get(element) ?? /* @__PURE__ */ new Map();
+    stacks.set(element, byAttribute);
+    const stack = byAttribute.get(this.#attribute) ?? this.#seed(element);
+    byAttribute.set(this.#attribute, stack);
+    return stack;
+  }
+  #seed(element) {
+    const found = [];
+    for (const record of _AttributeLease.#registry.names.get(this.#attribute) ?? []) {
+      const read = readLeaseRecord(element, record);
+      if (read) found.push({ ...read, record });
+    }
+    const depth = ({ beneath }) => beneath.filter((name) => found.some((other) => other.record === name)).length;
+    return found.sort((one, other) => depth(one) - depth(other)).map(({ record, written, original, linked }, index) => ({
+      lease: null,
+      record,
+      written,
+      original,
+      linked: linked && index > 0
+    }));
+  }
+  #take(stack) {
+    const hold = stack.find((held) => held.lease === this) ?? stack.find((held) => held.lease === null && held.record === this.#record);
+    if (hold) hold.lease = this;
+    return hold;
+  }
+  #acquire(element, stack) {
+    const current = element.getAttribute(this.#attribute);
+    const top = stack.at(-1);
+    const bottom = stack[0];
+    const over = top?.written === current ? top : void 0;
+    const from = this.#base ? bottom : over;
+    const hold = {
+      lease: this,
+      record: this.#record,
+      written: current,
+      original: from ? from.original : current,
+      linked: !this.#base && over !== void 0
+    };
+    if (this.#base && bottom) {
+      bottom.linked = true;
+      stack.unshift(hold);
+    } else stack.push(hold);
+    return hold;
+  }
+  #covered(element, stack, hold) {
+    const current = element.getAttribute(this.#attribute);
+    return stack.slice(stack.indexOf(hold) + 1).some((above) => above.written === current);
+  }
+  #mark(element, stack) {
+    const records = /* @__PURE__ */ new Map([[this.#record, null]]);
+    stack.forEach((hold, index) => {
+      const names = stack.slice(0, index).map((under) => under.record);
+      const beneath = [...new Set(names.reverse())].filter((name) => name !== hold.record);
+      const marker = hold.linked || beneath.length === 0 ? [] : [false];
+      records.set(
+        hold.record,
+        hold.written === hold.original && beneath.length === 0 && index === stack.length - 1 ? null : JSON.stringify([hold.original, hold.written, ...marker, ...beneath])
+      );
+    });
+    for (const [name, recorded] of records) {
+      if (element.getAttribute(name) === recorded) continue;
+      if (recorded === null) element.removeAttribute(name);
+      else element.setAttribute(name, recorded);
+    }
+  }
+  #reflect(element, value) {
+    if (element.getAttribute(this.#attribute) === value) return;
+    if (value === null) element.removeAttribute(this.#attribute);
+    else element.setAttribute(this.#attribute, value);
+  }
+};
+
 function matchingPart(root, selector) {
   return root.matches(selector) ? root : root.querySelector(selector);
 }
@@ -79,31 +241,14 @@ function readLabel(slot) {
   return text.trim();
 }
 
-// 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();
@@ -114,7 +259,6 @@ var RovingTabindex = class {
   }
 };
 
-// src/utils/chip_row.ts
 var ChipRow = class {
   #directionElement;
   #getItems;
@@ -130,10 +274,6 @@ var ChipRow = class {
     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();
@@ -141,10 +281,6 @@ var ChipRow = class {
     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;
@@ -152,19 +288,15 @@ var ChipRow = class {
     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);
@@ -173,7 +305,6 @@ var ChipRow = class {
       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;
@@ -181,10 +312,6 @@ var ChipRow = class {
     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;
@@ -195,14 +322,12 @@ var ChipRow = class {
     });
     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;
@@ -213,13 +338,11 @@ var ChipRow = class {
     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);
@@ -250,7 +373,6 @@ var ChipRow = class {
   };
 };
 
-// src/utils/composition_tracker.ts
 var COMPOSITION_INPUT_TYPES = /* @__PURE__ */ new Set([
   "insertCompositionText",
   "insertFromComposition",
@@ -262,13 +384,11 @@ var CompositionTracker = class {
   #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;
   }
-  /** Starts lifecycle tracking for `target`; repeated calls are idempotent. */
   observe(target) {
     if (this.#observedTargets.has(target)) return;
     target.addEventListener("compositionstart", this.#handleStart);
@@ -276,7 +396,6 @@ var CompositionTracker = class {
     target.addEventListener("keydown", this.#handleKeydown);
     this.#observedTargets.add(target);
   }
-  /** Stops tracking one target and clears any active composition it owned. */
   unobserve(target) {
     if (!this.#observedTargets.delete(target)) return;
     target.removeEventListener("compositionstart", this.#handleStart);
@@ -285,7 +404,6 @@ var CompositionTracker = class {
     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);
@@ -296,16 +414,9 @@ var CompositionTracker = class {
     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;
@@ -323,13 +434,11 @@ var CompositionTracker = class {
     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(
@@ -352,27 +461,33 @@ function commitField(target) {
   target.dispatchEvent(new Event("change", { bubbles: true }));
 }
 
-// src/utils/microtask_coalescer.ts
+var ListenerSet = class {
+  #abort = new AbortController();
+  add(target, type, handler, options) {
+    target.addEventListener(type, handler, { ...options, signal: this.#abort.signal });
+  }
+  dispose() {
+    this.#abort.abort();
+    this.#abort = new AbortController();
+  }
+};
+
 var MicrotaskCoalescer = class {
   #run;
   #queued = false;
   #active = false;
   #generation = 0;
-  /** @param run - the single reconciliation pass, invoked at most once per batch. */
   constructor(run) {
     this.#run = run;
   }
-  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
   activate() {
     this.#active = true;
   }
-  /** Closes the window and drops any pending pass; call from `disconnect()`. */
   cancel() {
     this.#active = false;
     this.#queued = false;
     this.#generation += 1;
   }
-  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */
   schedule() {
     if (!this.#active || this.#queued) return;
     this.#queued = true;
@@ -385,7 +500,86 @@ var MicrotaskCoalescer = class {
   }
 };
 
-// src/utils/option_scroll.ts
+var MorphRenderWatcher = class {
+  #listeners = new ListenerSet();
+  #pass;
+  #element = null;
+  #onMorph = () => this.#pass.schedule();
+  constructor(run) {
+    this.#pass = new MicrotaskCoalescer(run);
+  }
+  observe(element) {
+    if (this.#element === element) return;
+    this.disconnect();
+    this.#element = element;
+    this.#pass.activate();
+    this.#listeners.add(element, "turbo:morph-element", this.#onMorph);
+  }
+  schedule() {
+    this.#pass.schedule();
+  }
+  disconnect() {
+    this.#listeners.dispose();
+    this.#pass.cancel();
+    this.#element = null;
+  }
+};
+
+var MoveCounter = class {
+  #sequence = 0;
+  record() {
+    this.#sequence += 1;
+    return this.#sequence;
+  }
+  isLatest(token) {
+    return token === this.#sequence;
+  }
+};
+
+var NUMBER_BOUNDS = {
+  finite: { finite: true }};
+function matchesNumberBounds(value, bounds) {
+  if (!Number.isFinite(value)) {
+    const direction = value === Infinity ? "positive" : value === -Infinity ? "negative" : null;
+    if (direction === null) return false;
+    if (bounds.allowInfinity !== "both" && bounds.allowInfinity !== direction) return false;
+  }
+  if (bounds.min !== void 0 && value < bounds.min) return false;
+  if (bounds.max !== void 0 && value > bounds.max) return false;
+  if (bounds.exclusiveMin !== void 0 && value <= bounds.exclusiveMin) return false;
+  if (bounds.integer && !Number.isInteger(value)) return false;
+  if (bounds.allowedValues !== void 0 && !bounds.allowedValues.includes(value)) return false;
+  return true;
+}
+
+function readNumber(raw, fallback, bounds) {
+  return matchesNumberBounds(raw, bounds) ? raw : fallback;
+}
+
+var NumberValueReader = class {
+  #lastRejected = /* @__PURE__ */ new Map();
+  read(owner, name, raw, fallback, bounds) {
+    const resolved = readNumber(raw, fallback, bounds);
+    if (matchesNumberBounds(raw, bounds)) {
+      this.#lastRejected.delete(name);
+      return resolved;
+    }
+    const attribute = `data-${owner.identifier}-${name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}-value`;
+    const literal = owner.element.getAttribute(attribute);
+    if (literal === null) {
+      this.#lastRejected.delete(name);
+      return resolved;
+    }
+    if (this.#lastRejected.get(name) !== literal) {
+      this.#lastRejected.set(name, literal);
+      console.warn(
+        `Stimeo UI: "${owner.identifier}" has an invalid number Value "${name}" declaration ${JSON.stringify(literal)}; using ${fallback}.`
+      );
+    }
+    return resolved;
+  }
+};
+
 function scrollOptionIntoView(list, option) {
   if (list.scrollHeight <= list.clientHeight) return;
   const listRect = list.getBoundingClientRect();
@@ -397,16 +591,20 @@ function scrollOptionIntoView(list, option) {
   }
 }
 
-// src/utils/state_regions.ts
-var StateRegions = class {
+var StateRegions = class _StateRegions {
+  static #registry = sharedRegistry(
+    "stimeo-ui.state-regions.registry.v1",
+    () => ({ stacks: /* @__PURE__ */ new WeakMap(), names: /* @__PURE__ */ new Set() })
+  );
   #whenTrue;
   #whenFalse;
-  #taken = /* @__PURE__ */ new WeakSet();
-  constructor(options) {
+  #record;
+  constructor(options, owner) {
     this.#whenTrue = options.whenTrue;
     this.#whenFalse = options.whenFalse ?? null;
+    this.#record = `data-${owner}-hidden-region`;
+    _StateRegions.#registry.names.add(this.#record);
   }
-  /** 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) {
@@ -422,88 +620,231 @@ var StateRegions = class {
     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. */
+  release(host) {
+    for (const region of [host, ...host.querySelectorAll("*")]) {
+      if (!(region instanceof HTMLElement)) continue;
+      const stack = this.#held(region);
+      const hold = stack && this.#take(stack);
+      if (!stack || !hold) continue;
+      const owns = region.hidden === hold.written && !this.#covered(region, stack, hold);
+      const index = stack.indexOf(hold);
+      stack.splice(index, 1);
+      const above = stack[index];
+      if (above) above.linked &&= hold.linked;
+      if (owns) {
+        const below = hold.linked ? stack[index - 1] : void 0;
+        if (below) {
+          if (region.hidden !== below.written) region.hidden = below.written;
+        } else if (region.getAttribute("hidden") !== hold.authored) {
+          if (hold.authored === null) region.removeAttribute("hidden");
+          else region.setAttribute("hidden", hold.authored);
+        }
+      }
+      this.#mark(region, stack);
+    }
+  }
   #write(region, hidden) {
-    if (hidden) this.#taken.add(region);
-    else this.#taken.delete(region);
-    if (region.hidden !== hidden) region.hidden = hidden;
+    const stack = this.#stack(region);
+    const hold = this.#take(stack) ?? this.#acquire(region, stack);
+    const shows = !this.#covered(region, stack, hold);
+    hold.written = hidden;
+    if (shows && region.hidden !== hidden) region.hidden = hidden;
+    this.#mark(region, stack);
   }
-  /** Returns a region this instance hid; one it never hid keeps what it carries. */
   #give(region) {
-    if (this.#taken.delete(region)) region.hidden = false;
+    const stack = this.#held(region);
+    if (stack && this.#take(stack)?.written) this.#write(region, false);
+  }
+  #held(region) {
+    return _StateRegions.#registry.stacks.has(region) || region.hasAttribute(this.#record) ? this.#stack(region) : void 0;
+  }
+  #stack(region) {
+    const stacks = _StateRegions.#registry.stacks;
+    const stack = stacks.get(region) ?? this.#seed(region);
+    stacks.set(region, stack);
+    return stack;
+  }
+  #seed(region) {
+    const found = [];
+    for (const record of _StateRegions.#registry.names) {
+      const read = this.#recorded(region, record);
+      if (read) found.push({ ...read, record });
+    }
+    const depth = ({ beneath }) => beneath.filter((name) => found.some((other) => other.record === name)).length;
+    return found.sort((one, other) => depth(one) - depth(other)).map(({ record, authored, written, linked }, index) => ({
+      instance: null,
+      record,
+      authored,
+      written,
+      linked: linked && index > 0
+    }));
+  }
+  #take(stack) {
+    const hold = stack.find((held) => held.instance === this) ?? stack.find((held) => held.instance === null && held.record === this.#record);
+    if (hold) hold.instance = this;
+    return hold;
+  }
+  #covered(region, stack, hold) {
+    return stack.slice(stack.indexOf(hold) + 1).some((above) => above.written === region.hidden);
+  }
+  #acquire(region, stack) {
+    const top = stack.at(-1);
+    const over = top && region.hidden === top.written ? top : void 0;
+    const hold = {
+      instance: this,
+      record: this.#record,
+      authored: over ? over.authored : region.getAttribute("hidden"),
+      written: false,
+      linked: over !== void 0
+    };
+    stack.push(hold);
+    return hold;
+  }
+  #mark(region, stack) {
+    const records = /* @__PURE__ */ new Map([[this.#record, null]]);
+    stack.forEach((hold, index) => {
+      const names = stack.slice(0, index).map((under) => under.record);
+      const beneath = [...new Set(names.reverse())].filter((name) => name !== hold.record);
+      const marker = hold.linked || beneath.length === 0 ? [] : [false];
+      records.set(
+        hold.record,
+        region.getAttribute("hidden") === hold.authored && beneath.length === 0 && index === stack.length - 1 ? null : JSON.stringify([hold.authored, hold.written, ...marker, ...beneath])
+      );
+    });
+    for (const [name, recorded] of records) {
+      if (region.getAttribute(name) === recorded) continue;
+      if (recorded === null) region.removeAttribute(name);
+      else region.setAttribute(name, recorded);
+    }
+  }
+  #recorded(region, name) {
+    try {
+      const parsed = JSON.parse(region.getAttribute(name) ?? "null");
+      if (!Array.isArray(parsed)) return null;
+      const [authored, written, ...rest] = parsed;
+      if (authored !== null && typeof authored !== "string") return null;
+      const linked = rest[0] !== false;
+      const beneath = linked ? rest : rest.slice(1);
+      if (!beneath.every((under) => typeof under === "string")) return null;
+      return typeof written === "boolean" ? { authored, written, linked, beneath } : null;
+    } catch {
+      return null;
+    }
   }
-  /** 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. */
-  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;
-  }
-  /** 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);
+function queryOpenDescendants(root, selector) {
+  const matches = [];
+  const roots = [root];
+  for (const scope of roots) {
+    matches.push(...scope.querySelectorAll(selector));
+    if (scope.nodeType === Node.ELEMENT_NODE) {
+      const shadow = scope.shadowRoot;
+      if (shadow) roots.push(shadow);
+    }
+    for (const element of scope.querySelectorAll("*")) {
+      if (element.shadowRoot) roots.push(element.shadowRoot);
     }
   }
-  /** 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);
-  }
-};
+  return matches;
+}
 
-// src/utils/tabindex_loan.ts
-var TabindexLoan = class {
+var TabindexLoan = class _TabindexLoan {
+  static #registry = sharedRegistry(
+    "stimeo-ui.tabindex-loan.registry.v1",
+    () => ({ stacks: /* @__PURE__ */ new WeakMap(), names: /* @__PURE__ */ new Set() })
+  );
   #value;
+  #record;
   #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,
-   *   which a scroll region with no focusable content of its own needs.
-   */
-  constructor(value = "-1") {
+  constructor(value, owner) {
     this.#value = value;
+    this.#record = `data-${owner}-tabindex-loan`;
+    _TabindexLoan.#registry.names.add(this.#record);
   }
-  /** Lends `element` the value; no-ops when it already carries a `tabindex`. */
   lend(element) {
-    if (element.hasAttribute("tabindex")) return;
-    element.setAttribute("tabindex", this.#value);
+    const stack = this.#stack(element);
+    const current = element.getAttribute("tabindex");
+    const held = stack.find((hold) => hold.loan === this) ?? stack.find(
+      (hold) => hold.loan === null && hold.record === this.#record && hold.value === this.#value
+    );
+    const linked = stack.at(-1)?.value === current;
+    if (!held && current !== null && !linked) return;
     this.#lent.add(element);
-    this.#beforeCache.activate();
+    if (held) held.loan = this;
+    else stack.push({ loan: this, record: this.#record, value: this.#value, linked });
+    this.#mark(element, stack);
+    if (current === null || !held && current !== this.#value) {
+      element.setAttribute("tabindex", this.#value);
+    }
   }
-  /** Takes back every loan whose value is still the one that was lent. */
   returnAll() {
     for (const element of this.#lent) {
-      if (element.getAttribute("tabindex") === this.#value) element.removeAttribute("tabindex");
+      const stack = this.#stack(element);
+      const hold = stack.find((held) => held.loan === this);
+      if (hold) this.#release(element, stack, hold);
     }
     this.#lent.clear();
-    this.#beforeCache.deactivate();
+  }
+  reclaim(element) {
+    if (element.getAttribute(this.#record) !== this.#value) return;
+    const stack = this.#stack(element);
+    const hold = stack.find((held) => held.loan === null && held.record === this.#record);
+    if (hold && !element.matches(":focus")) this.#release(element, stack, hold);
+  }
+  reclaimWithin(root) {
+    for (const element of queryOpenDescendants(root, `[${this.#record}]`)) {
+      this.reclaim(element);
+    }
+  }
+  #stack(element) {
+    const stacks = _TabindexLoan.#registry.stacks;
+    const stack = stacks.get(element) ?? this.#seed(element);
+    stacks.set(element, stack);
+    return stack;
+  }
+  #seed(element) {
+    const current = element.getAttribute("tabindex");
+    const holds = [];
+    for (const record of _TabindexLoan.#registry.names) {
+      const value = element.getAttribute(record);
+      if (value !== null) holds.push({ loan: null, record, value, linked: true });
+    }
+    holds.sort((one, other) => Number(one.value === current) - Number(other.value === current));
+    for (const [index, hold] of holds.entries()) hold.linked = index > 0;
+    return holds;
+  }
+  #release(element, stack, hold) {
+    const current = element.getAttribute("tabindex");
+    const index = stack.indexOf(hold);
+    const owns = current === hold.value && !stack.slice(index + 1).some((above2) => above2.value === current);
+    stack.splice(index, 1);
+    const above = stack[index];
+    if (above) above.linked &&= hold.linked;
+    this.#mark(element, stack);
+    if (!owns) return;
+    const below = hold.linked ? stack[index - 1] : void 0;
+    if (!below) element.removeAttribute("tabindex");
+    else if (below.value !== current) element.setAttribute("tabindex", below.value);
+  }
+  #mark(element, stack) {
+    const records = /* @__PURE__ */ new Map([[this.#record, null]]);
+    for (const hold of stack) records.set(hold.record, hold.value);
+    for (const [name, recorded] of records) {
+      if (element.getAttribute(name) === recorded) continue;
+      if (recorded === null) element.removeAttribute(name);
+      else element.setAttribute(name, recorded);
+    }
   }
 };
 
-// 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;
@@ -514,22 +855,15 @@ var TemplateRow = class {
   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;
@@ -537,10 +871,6 @@ var TemplateRow = class {
     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);
@@ -568,7 +898,6 @@ var TemplateRow = class {
     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));
   }
@@ -577,8 +906,9 @@ var TemplateRow = class {
   }
 };
 
-// src/controllers/multi_select_controller.ts
-var MultiSelectController = class extends Controller {
+var MultiSelectController = class _MultiSelectController extends Controller {
+  #numbers = new NumberValueReader();
+  #moves = new MoveCounter();
   static targets = [
     "input",
     "list",
@@ -598,28 +928,28 @@ var MultiSelectController = class extends Controller {
     announceText: { type: String, default: "" },
     announceRemovedText: { type: String, default: "" }
   };
+  static valueConstraints = {
+    max: NUMBER_BOUNDS.finite
+  };
   static actions = ["close", "filter", "onKeydown", "open", "toggleOption"];
   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();
-  /** Last reconciled selection, used to distinguish state changes from derived-DOM repair. */
+  #tabindex = new TabindexLoan("-1", this.identifier);
   #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());
-  /** Owns IME lifecycle state; confirmed text emits one filter result. */
+  #emptyRegion = new StateRegions({ whenTrue: () => this.emptyTargets }, this.identifier);
+  #listHidden = new AttributeLease("hidden", this.identifier);
+  #expanded = new AttributeLease("aria-expanded", this.identifier);
+  #activeDescendant = new AttributeLease(
+    "aria-activedescendant",
+    this.identifier
+  );
+  #open = false;
+  #openList = null;
+  #reconcile = new MorphRenderWatcher(() => this.#reconcileOptions());
   #composition = new CompositionTracker({
-    // 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",
@@ -628,7 +958,6 @@ var MultiSelectController = class extends Controller {
     outcome: "changed no selection",
     noun: "chip template"
   });
-  /** Shared delegated interaction for the replaceable row of removable chips. */
   #chipRow = new ChipRow({
     directionElement: this.element,
     getItems: () => this.tagTargets,
@@ -636,8 +965,8 @@ var MultiSelectController = class extends Controller {
     onRemove: (index) => this.#removeTagAt(index),
     focusAfterEnd: () => this.#focusInput()
   });
-  /** Starts closed, syncs chips for any pre-selected options, and listens out. */
   connect() {
+    this.#tabindex.reclaim(this.element);
     this.#rows.connect();
     this.#normalizeSelection([]);
     this.close();
@@ -649,13 +978,8 @@ var MultiSelectController = class extends Controller {
     this.#syncFields();
     document.addEventListener("click", this.#onOutsideClick, true);
     this.#connected = true;
-    this.#reconcile.activate();
+    this.#reconcile.observe(this.element);
   }
-  /**
-   * Derives the chips from the selected options, idempotently: a Turbo Drive cache
-   * restore or morph can re-connect with chips already in the DOM, so they are
-   * cleared before deriving afresh to avoid duplicates.
-   */
   #rebuildTags() {
     if (!this.hasTagsTarget || !this.hasTagTemplateTarget) return;
     const chips = [];
@@ -668,72 +992,67 @@ var MultiSelectController = class extends Controller {
     this.tagsTarget.append(...chips);
     this.#chipRow.ensureTabStop();
   }
-  /** Tears down document and chip listeners on disconnect (Turbo included). */
   disconnect() {
     this.#connected = false;
-    this.#reconcile.cancel();
+    this.#reconcile.disconnect();
     this.#composition.disconnect();
     this.#chipRow.disconnect();
     document.removeEventListener("click", this.#onOutsideClick, true);
     this.#releaseTabindex();
   }
-  /** Reconciles active state after an option target is added at runtime. */
   optionTargetConnected() {
     this.#scheduleOptionReconcile();
   }
-  /** Cleans a removed target and reconciles active state against the surviving DOM. */
   optionTargetDisconnected(option) {
     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);
     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. */
+  fieldsTargetDisconnected() {
+    this.#scheduleOptionReconcile();
+  }
+  listTargetConnected(_list) {
+    if (!this.#connected) return;
+    this.#reconcileOpenState();
+    this.#scheduleOptionReconcile();
+  }
+  listTargetDisconnected(list) {
+    if (!this.listTargets.includes(list)) {
+      if (list === this.#openList) {
+        this.#adoptPageClose();
+        this.#openList = null;
+      }
+      this.#listHidden.return(list);
+    }
+    if (!this.#connected) return;
+    this.#reconcileOpenState();
+    this.#scheduleOptionReconcile();
+  }
   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();
   }
-  /**
-   * Keeps a surviving/same-id active target, otherwise falls back to the first
-   * visible one — and brings the derived state back in line with the new option set.
-   *
-   * The baseline pass fills in any missing `aria-selected`, and the chips and
-   * hidden fields are re-derived from it, because the options are the truth source
-   * for the selection. The chips are rebuilt **only when the selected value set
-   * actually moved**: the rebuild removes and recreates every chip, so running it
-   * 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;
     const active = this.#activeOption;
@@ -762,24 +1081,23 @@ var MultiSelectController = class extends Controller {
     const changed = !this.#sameSelection(previous, values);
     this.#selectionValues = values;
     if (!changed) return;
+    const token = this.#moves.record();
     const options = new Map(selected.map((option) => [this.#optionValue(option), option]));
     for (const value of previous) {
+      if (!this.#moves.isLatest(token)) return;
       if (!values.includes(value)) {
         this.#announceTransition(false, previousLabels.get(value) || value, value, values.length);
       }
     }
     for (const value of values) {
+      if (!this.#moves.isLatest(token)) return;
       if (previous.includes(value)) continue;
       const option = options.get(value);
       this.#announceTransition(true, this.#optionLabel(option), value, values.length);
     }
+    if (!this.#moves.isLatest(token)) return;
     this.dispatch("reconcile", { detail: { values } });
   }
-  /**
-   * 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(priority) {
     const selected = this.optionTargets.filter(
       (option) => option.getAttribute("aria-selected") === "true"
@@ -805,25 +1123,36 @@ var MultiSelectController = class extends Controller {
       option.setAttribute("aria-selected", String(kept.has(option)));
     }
   }
-  /**
-   * Tracks an input added initially or after connect, and makes it describe the
-   * widget that is actually on screen: a swapped-in input arrives with the
-   * authored ARIA of a fresh node while this controller still holds the popup
-   * state, and the open path cannot repair that (it seeds an active option only
-   * when there is none), so a live list would go unannounced.
-   */
   inputTargetConnected(input) {
     this.#composition.observe(input);
-    input.setAttribute("aria-expanded", String(!this.#isClosed));
-    const active = this.#activeOption;
-    if (active) input.setAttribute("aria-activedescendant", ensureId(active, "stimeo-ms-opt"));
-    else input.removeAttribute("aria-activedescendant");
+    this.#describeInput(input);
   }
-  /** Removes composition listeners when the active input is replaced or removed. */
   inputTargetDisconnected(input) {
     this.#composition.unobserve(input);
+    if (!this.inputTargets.includes(input)) {
+      this.#expanded.return(input);
+      this.#activeDescendant.return(input);
+    }
+    if (this.#connected && this.hasInputTarget) this.#describeInput(this.inputTarget);
+  }
+  #describeInput(input) {
+    this.#expanded.write(input, String(!this.#isClosed));
+    const active = this.#activeOption;
+    this.#activeDescendant.write(input, active ? ensureId(active, "stimeo-ms-opt") : null);
+  }
+  #reconcileOpenState() {
+    if (!this.hasListTarget) return;
+    this.#adoptPageClose();
+    const list = this.listTarget;
+    if (list !== this.#openList) {
+      this.#showList(list, this.#open);
+      this.#openList = list;
+    }
+    if (this.hasInputTarget) this.#expanded.write(this.inputTarget, String(!list.hidden));
+  }
+  #adoptPageClose() {
+    if (this.#openList?.hidden) this.#open = false;
   }
-  /** Filters confirmed input text, opens, and re-seeds the active option. */
   filter(event) {
     if (!this.hasInputTarget) return;
     if (event && this.#composition.consumesConfirmedInput(event)) return;
@@ -835,46 +1164,31 @@ var MultiSelectController = class extends Controller {
     }
     this.open();
     const visible = this.#visibleOptions;
-    this.#reflectEmpty();
     this.#setActive(visible[0] ?? null);
     this.dispatch("filter", { detail: { query } });
   }
-  /**
-   * Opens the list and activates the first visible option when none is active.
-   *
-   * 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 MultiSelectController.close | close}
-   * still closes.
-   */
   open() {
     if (!this.hasListTarget || !this.hasInputTarget) {
       this.#reflectEmpty();
       return;
     }
-    this.listTarget.hidden = false;
-    this.inputTarget.setAttribute("aria-expanded", "true");
+    this.#showList(this.listTarget, true);
+    this.#open = true;
+    this.#openList = this.listTarget;
+    this.#expanded.write(this.inputTarget, "true");
     if (!this.#activeOption) this.#setActive(this.#visibleOptions[0] ?? null);
     this.#reflectEmpty();
   }
-  /**
-   * Closes the list and clears the active option.
-   *
-   * Survives a missing input in both directions. `connect()` calls this second,
-   * so dereferencing the input here would throw before the chips, the roving
-   * seed, the chip listeners, the hidden fields and the outside-click listener —
-   * and Stimulus keeps the controller alive after that throw, so none of them
-   * would ever run and the selection would silently stop submitting. An input
-   * removed while the list is open must still let it come down *and* forget its
-   * active option, so only the `aria-expanded` write is guarded.
-   */
   close() {
-    if (this.hasListTarget) this.listTarget.hidden = true;
+    this.#open = false;
+    if (this.hasListTarget) {
+      this.#showList(this.listTarget, false);
+      this.#openList = this.listTarget;
+    }
     this.#setActive(null);
-    if (this.hasInputTarget) this.inputTarget.setAttribute("aria-expanded", "false");
+    if (this.hasInputTarget) this.#expanded.write(this.inputTarget, "false");
     this.#reflectEmpty();
   }
-  /** Routes input keyboard interaction per the multi-select combobox model. */
   onKeydown(event) {
     if (event.defaultPrevented) return;
     if (isReservedArrowChord(event)) return;
@@ -939,39 +1253,20 @@ var MultiSelectController = class extends Controller {
         break;
     }
   }
-  /**
-   * Toggles the clicked option's selection. Bound via `data-action`. Focus is
-   * re-homed to the input afterwards: options are non-focusable, so the click blurs
-   * the input to `body` — and with the list deliberately staying open, every
-   * keyboard affordance (Escape, arrows, typing) is bound to the input and would
-   * otherwise go dead until the user clicks back in ("focus stays on the input").
-   */
-  toggleOption(event) {
-    const option = event.currentTarget.closest('[role="option"]');
+  toggleOption(source) {
+    const { event, host, origin, reason } = actionSource(source);
+    if (origin && origin.closest(`[data-controller~="${this.identifier}"]`) !== this.element)
+      return;
+    const option = host?.closest(targetSelector(this.identifier, "option"));
     if (!option || !this.optionTargets.includes(option)) return;
-    this.#toggleSelection(option);
-    this.#focusInput();
-  }
-  /**
-   * Re-homes focus to the input, or leaves it where it is when there is none.
-   *
-   * All three callers run *after* an option or a chip already took focus, and all
-   * three are reachable without an input — options and chips carry their own
-   * `data-action`. Throwing here would leave the chip removed but focus stranded
-   * on a detached button.
-   */
+    const focus = event !== null || this.element.contains(document.activeElement);
+    if (!this.#toggleSelection(option, reason)) return;
+    if (focus && (event !== null || this.element.contains(document.activeElement)))
+      this.#focusInput();
+  }
   #focusInput() {
     if (this.hasInputTarget) this.inputTarget.focus();
   }
-  /**
-   * Re-homes focus after the last chip was removed: to the input, else the root.
-   *
-   * 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 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) {
       this.inputTarget.focus();
@@ -985,15 +1280,9 @@ var MultiSelectController = class extends Controller {
     this.#tabindex.lend(this.element);
     this.element.focus();
   }
-  /**
-   * Returns the borrowed tab stop. Owning the borrow is not enough — the value
-   * has to still be the one this instance wrote, since a consumer that changed it
-   * afterwards owns it now.
-   */
   #releaseTabindex() {
     this.#tabindex.returnAll();
   }
-  /** Moves the active option by `delta` among visible options, wrapping. */
   #moveActive(delta) {
     const visible = this.#visibleOptions;
     const active = this.#activeOption;
@@ -1002,41 +1291,27 @@ var MultiSelectController = class extends Controller {
     const next = (candidate + visible.length) % visible.length;
     this.#setActive(visible[next] ?? null);
   }
-  /** Selects/deselects `option`, honoring `max`, and syncs chip + announcement. */
-  #toggleSelection(option) {
+  #toggleSelection(option, reason = "user") {
     const selected = option.getAttribute("aria-selected") === "true";
     const limit = this.#selectionLimit;
     if (!selected && limit > 0 && this.#selectedOptions.length >= limit) {
-      return;
+      return true;
     }
     if (selected) {
       option.setAttribute("aria-selected", "false");
       this.#removeTagFor(option);
     } else {
-      if (this.hasTagTemplateTarget && !this.#appendTag(option)) return;
+      if (this.hasTagTemplateTarget && !this.#appendTag(option)) return true;
       option.setAttribute("aria-selected", "true");
     }
     this.#refreshRoving();
-    this.#syncFields(true);
-    const values = this.#values;
-    this.#selectionValues = values;
-    this.#announceTransition(
+    return this.#publishSelection(
       !selected,
       this.#optionLabel(option),
       this.#optionValue(option),
-      values.length
+      reason
     );
-    this.dispatch("change", { detail: { values } });
-  }
-  /**
-   * Re-reads each chip's label from its option, in place.
-   *
-   * The value order alone does not say the chips are still correct: a server can
-   * re-render the same candidate with a new label ("Apple" → "Green Apple"), and
-   * the chip text and its `Remove {label}` name are both derived from the option.
-   * Updating them here keeps the rebuild — which would drop focus — for the case
-   * that actually needs it, a changed selection.
-   */
+  }
   #refreshTagLabels(selected) {
     const options = new Map(selected.map((option) => [this.#optionValue(option), option]));
     for (const tag of this.tagTargets) {
@@ -1050,7 +1325,6 @@ var MultiSelectController = class extends Controller {
       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.#rows.report('a "tags" target to append the chip to');
@@ -1061,14 +1335,6 @@ var MultiSelectController = class extends Controller {
     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 — 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 text = this.#optionLabel(option);
     const value = this.#optionValue(option);
@@ -1079,19 +1345,16 @@ var MultiSelectController = class extends Controller {
     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${this.#rows.selector("remove")}`)?.getAttribute("aria-label")?.trim();
     return template ? fillTemplate(template, { label, value }) : null;
   }
-  /** Removes the chip mirroring `option`, if present. */
   #removeTagFor(option) {
     const value = this.#optionValue(option);
     const tag = this.tagTargets.find((candidate) => candidate.dataset.value === value);
     tag?.remove();
   }
-  /** Removes chip `index` and deselects its option, re-homing focus. */
   #removeTagAt(index, focus = "neighbor") {
     const tag = this.tagTargets[index];
     if (!tag) return;
@@ -1100,31 +1363,13 @@ var MultiSelectController = class extends Controller {
     if (option) option.setAttribute("aria-selected", "false");
     tag.remove();
     this.#refreshRoving();
-    this.#syncFields(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 (!this.#publishSelection(false, option ? this.#optionLabel(option) : value, value)) return;
     if (focus === "input") {
       this.#focusInput();
       return;
     }
     if (!this.#chipRow.focusAfterRemoval(index)) this.#focusAfterLastTag();
   }
-  /**
-   * Marks `option` active via `data-active` and the input's
-   * `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 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;
     this.#activeOptionId = activeId;
@@ -1132,14 +1377,8 @@ var MultiSelectController = class extends Controller {
       candidate.toggleAttribute("data-active", candidate === option);
     }
     if (option && this.hasListTarget) scrollOptionIntoView(this.listTarget, option);
-    if (!this.hasInputTarget) return;
-    if (activeId !== null) {
-      this.inputTarget.setAttribute("aria-activedescendant", activeId);
-    } else {
-      this.inputTarget.removeAttribute("aria-activedescendant");
-    }
+    if (this.hasInputTarget) this.#activeDescendant.write(this.inputTarget, activeId);
   }
-  /** Repairs only active identity before a key; the fallback waits for the target callback. */
   #reconcileActiveForInteraction() {
     const activeId = this.#activeOptionId;
     if (activeId === null) return;
@@ -1151,88 +1390,84 @@ var MultiSelectController = class extends Controller {
       this.#setActive(active);
     }
   }
-  /**
-   * 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() {
     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`
-   * target so the selection submits with a normal form (parity with tags-input).
-   * No-ops without a `fields` target. When the
-   * `form` value is set, each input gets a matching `form` attribute so the picker
-   * can submit with a `<form>` it lives outside of.
-   */
-  #syncFields(notify = false) {
-    if (!this.hasFieldsTarget) return;
+  #syncFields() {
+    if (!this.hasFieldsTarget) return false;
     const options = { name: this.nameValue, form: this.formValue };
-    if (writeFields(this.fieldsTarget, this.#values, options) && notify) {
-      commitField(this.fieldsTarget);
-    }
+    return writeFields(this.fieldsTarget, this.#values, options);
+  }
+  #publishSelection(selected, label, value, reason = "user") {
+    const values = this.#values;
+    const changed = !this.#sameSelection(this.#selectionValues, values);
+    const fieldChanged = this.#syncFields();
+    this.#selectionValues = values;
+    if (!changed) return true;
+    const token = this.#moves.record();
+    if (fieldChanged) commitField(this.fieldsTarget);
+    if (!this.#moves.isLatest(token)) return false;
+    this.#announceTransition(selected, label, value, values.length);
+    if (!this.#moves.isLatest(token)) return false;
+    this.dispatch("change", { detail: { values, reason } });
+    return this.#moves.isLatest(token);
   }
-  /** 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.
-   *
-   * @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 }));
   }
-  /** 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) => {
     if (!this.#isClosed && !this.element.contains(event.target)) this.close();
   };
-  /** Trimmed visible label of an option. */
   #optionLabel(option) {
     return (option.textContent ?? "").trim();
   }
-  /** An option's stable value: its `data-value`, else its display label. */
   #optionValue(option) {
     return option.dataset.value ?? this.#optionLabel(option);
   }
-  /** Options not hidden by the current filter. */
   get #visibleOptions() {
     return this.optionTargets.filter((option) => !option.hidden);
   }
-  /** Current active target resolved by stable id, never a detached node reference. */
   get #activeOption() {
     return this.optionTargets.find((option) => option.id === this.#activeOptionId) ?? null;
   }
-  /** Options currently selected. */
   get #selectedOptions() {
     return this.optionTargets.filter((option) => option.getAttribute("aria-selected") === "true");
   }
-  /** Selected values in option order. */
   get #values() {
     return this.#selectedOptions.map((option) => this.#optionValue(option));
   }
-  /** Normalized cardinality cap: zero and below are unlimited; a positive value floors, never below 1. */
   get #selectionLimit() {
-    if (!Number.isFinite(this.maxValue) || this.maxValue <= 0) return 0;
-    return Math.max(1, Math.floor(this.maxValue));
+    if (this.#safeMax <= 0) return 0;
+    return Math.max(1, Math.floor(this.#safeMax));
+  }
+  #showList(list, open) {
+    this.#listHidden.write(list, open ? null : "");
   }
-  /** Whether the list is currently hidden. */
   get #isClosed() {
     return !this.hasListTarget || this.listTarget.hidden !== false;
   }
+  get #safeMax() {
+    return this.#numbers.read(
+      this,
+      "max",
+      this.maxValue,
+      _MultiSelectController.values.max.default,
+      _MultiSelectController.valueConstraints.max
+    );
+  }
 };
 
 export { MultiSelectController };
-//# sourceMappingURL=multi_select_controller.js.map
 //# sourceMappingURL=multi_select_controller.js.map