stimeo-ui 0.14.0 → 0.16.0

data/dist/cable/index.js

@@ -164,6 +164,18 @@ var SafeInterval = class extends TimerRegistry {
     window.clearInterval(id);
   }
 };
+
+// src/utils/transient_hooks.ts
+var TransientHooks = class {
+  #attributes;
+  constructor(options) {
+    this.#attributes = options.attributes;
+  }
+  /** Drops the declared hooks from `element`; what it carries besides stays. */
+  reset(element) {
+    for (const attribute of this.#attributes) element.removeAttribute(attribute);
+  }
+};
 function parseSubscriptionParams(raw) {
   try {
     const parsed = JSON.parse(raw);
@@ -270,6 +282,7 @@ function openSharedSubscription(consumer, channel) {
 }
 
 // src/cable/live_counter_controller.ts
+var TRANSIENT = new TransientHooks({ attributes: ["data-live-counter-rejected"] });
 var DISABLED_MARKER = "data-live-counter-disabled";
 var LiveCounterController = class _LiveCounterController extends Controller {
   static targets = ["value", "trigger"];
@@ -323,9 +336,12 @@ var LiveCounterController = class _LiveCounterController extends Controller {
    * The rejected hook is transient server state: a Turbo cache snapshot must not
    * resurrect it — the fresh subscription re-decides it. An outstanding guess
    * belongs to the identifier that is going away, so it is dropped with it.
+   *
+   * @stimeoRuntimeOnly `channel` decides whether this call opens a subscription at all; the
+   *   rejected hook it clears does not depend on it.
    */
   #subscribe() {
-    this.element.removeAttribute("data-live-counter-rejected");
+    TRANSIENT.reset(this.element);
     this.#outstanding.length = 0;
     if (this.channelValue) {
       this.#subscription = this.#open();
@@ -340,6 +356,9 @@ var LiveCounterController = class _LiveCounterController extends Controller {
    * half-wired: no gate reflected, and a trigger that looks live. The gate reads
    * the declaration, so a null subscription keeps it shut and the display never
    * moves past what the server can receive.
+   *
+   * @stimeoRuntimeOnly `channel` and its params choose the one subscription this call opens; `id`
+   *   is read by the handlers it wires.
    */
   #open() {
     try {
@@ -388,7 +407,7 @@ var LiveCounterController = class _LiveCounterController extends Controller {
     this.#focusedTriggers.releaseAll();
     this.#subscription?.unsubscribe();
     this.#subscription = null;
-    this.element.removeAttribute("data-live-counter-rejected");
+    TRANSIENT.reset(this.element);
     for (const trigger of this.triggerTargets) this.#release(trigger);
   }
   /** Late-added triggers (e.g. via a Turbo Stream) pick up the current gate. */
@@ -467,6 +486,8 @@ var LiveCounterController = class _LiveCounterController extends Controller {
    * authored-disabled trigger ("disabled until valid", say) is never
    * re-enabled by the gate. A marked disabled restored from a Turbo cache
    * snapshot is recognized as ours and lifted once the gate opens.
+   *
+   * @stimeoRenderRoot
    */
   #syncTrigger(trigger) {
     if (this.#ready) {
@@ -510,6 +531,9 @@ var LiveCounterController = class _LiveCounterController extends Controller {
    * Settles the display on a count the server stated, announcing what it settled
    * on. Announcing the optimistic bump instead would read a guess out and then
    * correct it, so the announcement rides this path only.
+   *
+   * @stimeoRuntimeOnly The count shown is the value received; `announceText` words the one
+   *   announcement of this change.
    */
   #reconcile(count) {
     if (this.#write(count)) this.#announce(count);
@@ -530,6 +554,60 @@ var LiveCounterController = class _LiveCounterController extends Controller {
     }, _LiveCounterController.#announceDelay);
   }
 };
+
+// src/utils/keyed_timers.ts
+var KeyedTimers = class {
+  #timers = new SafeTimeout();
+  /** The pending timer of each key; an entry lives exactly as long as its timer. */
+  #pending = /* @__PURE__ */ new Map();
+  /**
+   * Arms `callback` after `delay` ms for `key`, cancelling the timer `key` had
+   * pending. The entry is dropped before the callback runs, so the callback sees
+   * the key unarmed and may arm it again for the next round.
+   */
+  set(key, callback, delay) {
+    this.clear(key);
+    const id = this.#timers.set(() => {
+      this.#pending.delete(key);
+      callback();
+    }, delay);
+    this.#pending.set(key, id);
+  }
+  /**
+   * Cancels `key`'s pending timer, if it has one.
+   *
+   * A timer id is a positive integer, so `-1` stands for "nothing pending" and
+   * the registry ignores an id it does not own — the unarmed case needs no
+   * branch of its own, and no other key's timer can be reached from here.
+   */
+  clear(key) {
+    this.#timers.clear(this.#pending.get(key) ?? -1);
+    this.#pending.delete(key);
+  }
+  /**
+   * Cancels every pending timer and forgets every key. Call this from a
+   * controller's `disconnect()` so no timer, and no entry, outlives the element.
+   */
+  clearAll() {
+    this.#timers.clearAll();
+    this.#pending.clear();
+  }
+  /** Whether `key` has a timer pending. */
+  has(key) {
+    return this.#pending.has(key);
+  }
+};
+
+// src/utils/template_row.ts
+function cloneTemplateRoot(template) {
+  const root = template.content.firstElementChild;
+  return root instanceof HTMLElement ? root.cloneNode(true) : null;
+}
+
+// src/cable/presence_controller.ts
+var TRANSIENT2 = new TransientHooks({
+  attributes: ["data-present", "data-present-count", "data-presence-rejected"]
+});
 var BEACON_THROTTLE_MS = 2e3;
 var DEFAULT_HEARTBEAT_MS = 15e3;
 var DEFAULT_TIMEOUT_MS = 4e4;
@@ -554,6 +632,8 @@ var PresenceController = class _PresenceController extends Controller {
   #subscription = null;
   /** Present peers keyed by id (insertion order = join order). */
   #peers = /* @__PURE__ */ new Map();
+  /** Each peer's auto-expiry timer, restarted by every beacon from that peer. */
+  #expiry = new KeyedTimers();
   #timers = new SafeTimeout();
   #intervals = new SafeInterval();
   /** Epoch ms of the last outgoing beacon, for the convergence throttle. */
@@ -622,7 +702,6 @@ var PresenceController = class _PresenceController extends Controller {
   }
   connect() {
     this.#reset();
-    this.element.removeAttribute("data-presence-rejected");
     if (this.hasCountTarget) this.countTarget.textContent = this.#countMessage(0);
     if (!this.channelValue) return;
     this.#claimSpeaker();
@@ -648,7 +727,6 @@ var PresenceController = class _PresenceController extends Controller {
     this.#subscription = null;
     this.#intervals.clearAll();
     this.#reset();
-    this.element.removeAttribute("data-presence-rejected");
   }
   /**
    * Registers this element as one of the voices for its peer, so a sibling on the
@@ -728,6 +806,9 @@ ${this.idValue}`;
    * Tracks a broadcast beacon: upserts the peer (restarting its expiry timer),
    * removes it on a `leaving` notice, and re-announces this client when the
    * peer was unknown (roster convergence — see the class doc).
+   *
+   * @stimeoRuntimeOnly `id` filters this client's own echo, `timeout` arms one peer's expiry,
+   *   `name` answers one beacon and the texts word one announcement.
    */
   #onReceived(data) {
     const beacon = data;
@@ -739,9 +820,8 @@ ${this.idValue}`;
     }
     const name = typeof beacon?.name === "string" ? beacon.name : "";
     const existing = this.#peers.get(id);
-    if (existing !== void 0) this.#timers.clear(existing.timer);
-    const timer = this.#timers.set(() => this.#drop(id), this.#timeout);
-    this.#peers.set(id, { name, timer });
+    this.#expiry.set(id, () => this.#drop(id), this.#timeout);
+    this.#peers.set(id, { name });
     if (existing === void 0) {
       this.#appendClone(id, name);
       this.#render();
@@ -753,18 +833,24 @@ ${this.idValue}`;
       this.#render();
     }
   }
-  /** Removes a peer (expiry or graceful leave) and reflects the change. */
+  /**
+   * Removes a peer (expiry or graceful leave) and reflects the change.
+   *
+   * @stimeoRuntimeOnly `announceLeaveText` words the one announcement this departure makes.
+   */
   #drop(id) {
     const peer = this.#peers.get(id);
     if (peer === void 0) return;
-    this.#timers.clear(peer.timer);
+    this.#expiry.clear(id);
     this.#peers.delete(id);
     this.#removeClone(id);
     this.#render();
     this.#announce(this.announceLeaveTextValue, peer.name);
     this.dispatch("leave", { detail: { id } });
   }
-  /** Reflects the roster onto the hooks + count target and emits `change`. */
+  /**
+   * Reflects the roster onto the hooks + count target and emits `change`.
+   */
   #render() {
     const users = [...this.#peers.entries()].map(([id, peer]) => ({ id, name: peer.name }));
     this.element.setAttribute("data-present", users.length > 0 ? "true" : "false");
@@ -803,8 +889,8 @@ ${this.idValue}`;
   /** Appends one template clone for a newly present peer (list + template only). */
   #appendClone(id, name) {
     if (!this.hasListTarget || !this.hasTemplateTarget) return;
-    const root = this.templateTarget.content.firstElementChild?.cloneNode(true);
-    if (!(root instanceof Element)) return;
+    const root = cloneTemplateRoot(this.templateTarget);
+    if (!root) return;
     root.setAttribute("data-presence-id", id);
     this.#fillName(root, name);
     this.listTarget.appendChild(root);
@@ -834,12 +920,12 @@ ${this.idValue}`;
   /** Clears the transient roster state (connect reset + disconnect teardown). */
   #reset() {
     this.#timers.clearAll();
+    this.#expiry.clearAll();
     this.#pendingBeacon = null;
     this.#announceId = null;
     this.#peers.clear();
     this.#lastBeaconAt = 0;
-    this.element.removeAttribute("data-present");
-    this.element.removeAttribute("data-present-count");
+    TRANSIENT2.reset(this.element);
     if (this.hasCountTarget) this.countTarget.textContent = "";
     if (this.hasListTarget) {
       for (const child of this.listTarget.querySelectorAll("[data-presence-id]")) {
@@ -848,6 +934,9 @@ ${this.idValue}`;
     }
   }
 };
+var TRANSIENT3 = new TransientHooks({
+  attributes: ["data-typing", "data-typing-indicator-rejected"]
+});
 var DEFAULT_TIMEOUT = 3e3;
 var DEFAULT_THROTTLE = 2e3;
 var fillTokens = (template, values) => template.replace(/%\{(name|names|count)\}/g, (match, token) => values[token] ?? match);
@@ -871,8 +960,10 @@ var TypingIndicatorController = class _TypingIndicatorController extends Control
   /** Identifier parameters parsed once from their declaration, never in the hot path. */
   #params = {};
   #subscription = null;
-  /** Names currently typing (other clients), each with its auto-clear timer id. */
-  #typers = /* @__PURE__ */ new Map();
+  /** Names currently typing (other clients), in the order their first signal arrived. */
+  #typers = /* @__PURE__ */ new Set();
+  /** Each typer's auto-clear timer, restarted by every further signal from that name. */
+  #expiry = new KeyedTimers();
   #timers = new SafeTimeout();
   /** Epoch ms of the last broadcast, for leading-edge throttling. */
   #lastSentAt = 0;
@@ -899,8 +990,7 @@ var TypingIndicatorController = class _TypingIndicatorController extends Control
     if (this.#typers.size > 0) this.#paint();
   }
   connect() {
-    this.element.removeAttribute("data-typing");
-    this.element.removeAttribute("data-typing-indicator-rejected");
+    TRANSIENT3.reset(this.element);
     if (this.hasStatusTarget) this.statusTarget.textContent = "";
     this.element.addEventListener("input", this.#onInput);
     if (this.channelValue) {
@@ -922,10 +1012,10 @@ var TypingIndicatorController = class _TypingIndicatorController extends Control
     this.#subscription?.unsubscribe();
     this.#subscription = null;
     this.#timers.clearAll();
+    this.#expiry.clearAll();
     this.#announceId = null;
     this.#typers.clear();
-    this.element.removeAttribute("data-typing");
-    this.element.removeAttribute("data-typing-indicator-rejected");
+    TRANSIENT3.reset(this.element);
     if (this.hasStatusTarget) this.statusTarget.textContent = "";
     this.#lastSentAt = 0;
   }
@@ -941,17 +1031,16 @@ var TypingIndicatorController = class _TypingIndicatorController extends Control
    * Tracks a broadcast typer. The own echo is dropped (same `name`); every
    * further signal from a name restarts its auto-clear timer, so the indicator
    * survives continuous typing and clears `timeout` ms after the last signal.
+   *
+   * @stimeoRuntimeOnly `name` filters this client's own echo and `timeout` arms one typer's expiry;
+   *   the typers shown come from what is received.
    */
   #onReceived(data) {
     const name = data?.name;
     if (typeof name !== "string" || name === "" || name === this.nameValue) return;
-    const existing = this.#typers.get(name);
-    if (existing !== void 0) this.#timers.clear(existing);
-    const added = existing === void 0;
-    this.#typers.set(
-      name,
-      this.#timers.set(() => this.#untrack(name), this.#timeout)
-    );
+    const added = !this.#typers.has(name);
+    this.#typers.add(name);
+    this.#expiry.set(name, () => this.#untrack(name), this.#timeout);
     if (added) this.#render();
   }
   /**
@@ -981,7 +1070,9 @@ var TypingIndicatorController = class _TypingIndicatorController extends Control
     this.#typers.delete(name);
     this.#render();
   }
-  /** Reflects the typer set onto the display, announces it, and emits `change`. */
+  /**
+   * Reflects the typer set onto the display, announces it, and emits `change`.
+   */
   #render() {
     const names = this.#paint();
     this.#announce(names);
@@ -995,6 +1086,9 @@ var TypingIndicatorController = class _TypingIndicatorController extends Control
    * a reader for, and the visible copy already clears. Wording comes from the
    * consumer, and {@link announce} drops an empty message, so an undeclared template
    * announces nothing at all.
+   *
+   * @stimeoRuntimeOnly The wording Values are read to compose one announcement; the
+   * visible typer list is rendered from the set, not from them.
    */
   #announce(names) {
     if (this.#announceId !== null) this.#timers.clear(this.#announceId);
@@ -1011,7 +1105,7 @@ var TypingIndicatorController = class _TypingIndicatorController extends Control
   }
   /** Writes the current typer set onto the hook and the status slot. */
   #paint() {
-    const names = [...this.#typers.keys()];
+    const names = [...this.#typers];
     this.element.setAttribute("data-typing", names.length > 0 ? "true" : "false");
     if (this.hasStatusTarget) {
       this.statusTarget.textContent = this.#message(names);

data/dist/controllers/accordion_controller.js

@@ -8,36 +8,125 @@ 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/state_reason.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";
+}
+
+// src/utils/state_regions.ts
+var StateRegions = class {
+  #whenTrue;
+  #whenFalse;
+  #taken = /* @__PURE__ */ new WeakSet();
+  constructor(options) {
+    this.#whenTrue = options.whenTrue;
+    this.#whenFalse = options.whenFalse ?? null;
+  }
+  /** Shows the regions inside `host` that belong to `isTrue` and hides the others. */
+  reflect(host, isTrue) {
+    const shown = this.#inside(host, this.#whenTrue());
+    if (!this.#whenFalse) {
+      for (const region of shown) this.#write(region, !isTrue);
+      return;
+    }
+    const hiddenSide = this.#inside(host, this.#whenFalse());
+    if (shown.length === 0 || hiddenSide.length === 0) {
+      for (const region of shown) this.#give(region);
+      for (const region of hiddenSide) this.#give(region);
+      return;
+    }
+    for (const region of shown) this.#write(region, !isTrue);
+    for (const region of hiddenSide) this.#write(region, isTrue);
+  }
+  /** Writes `hidden` where it moves, noting which regions it takes out of view. */
+  #write(region, hidden) {
+    if (hidden) this.#taken.add(region);
+    else this.#taken.delete(region);
+    if (region.hidden !== hidden) region.hidden = hidden;
+  }
+  /** Returns a region this instance hid; one it never hid keeps what it carries. */
+  #give(region) {
+    if (this.#taken.delete(region)) region.hidden = false;
+  }
+  /** The declared regions that sit within `host`, which may be the host itself. */
+  #inside(host, regions) {
+    return regions.filter((region) => host.contains(region));
+  }
+};
+
 // src/controllers/accordion_controller.ts
 var AccordionController = class extends Controller {
-  static targets = ["trigger", "panel"];
+  static targets = ["trigger", "panel", "expandedLabel", "collapsedLabel"];
   static actions = ["collapseAll", "expandAll", "onKeydown", "toggle"];
+  static events = ["close", "open"];
+  /** Owns `hidden` on the label pair a header declares, narrowed to that header. */
+  #labels = new StateRegions({
+    whenTrue: () => this.expandedLabelTargets,
+    whenFalse: () => this.collapsedLabelTargets
+  });
+  /** Settles the label pair of a header as it joins the group. */
+  triggerTargetConnected(trigger) {
+    this.#reflectLabels(trigger);
+  }
+  /** Settles the pair of the header an arriving expanded half belongs to. */
+  expandedLabelTargetConnected(label) {
+    this.#settleLabelHost(label);
+  }
+  /** Settles the pair of the header an arriving collapsed half belongs to. */
+  collapsedLabelTargetConnected(label) {
+    this.#settleLabelHost(label);
+  }
+  /** Reflects the pair of the header a label half sits in, where a header holds it. */
+  #settleLabelHost(label) {
+    const trigger = this.triggerTargets.find((candidate) => candidate.contains(label));
+    if (trigger) this.#reflectLabels(trigger);
+  }
   /** Toggles the panel controlled by the activated header. */
   toggle(event) {
     const trigger = event.currentTarget;
     const panel = this.#panelFor(trigger);
     if (!panel) return;
-    this.#setExpanded(trigger, panel, trigger.getAttribute("aria-expanded") !== "true");
+    this.#setExpanded(
+      trigger,
+      panel,
+      trigger.getAttribute("aria-expanded") !== "true",
+      stateReasonFor(event)
+    );
   }
   /** Opens every panel. Bound via `data-action` on an "expand all" control. */
-  expandAll() {
-    this.#setAll(true);
+  expandAll(event) {
+    this.#setAll(true, stateReasonFor(event));
   }
   /** Closes every panel. Bound via `data-action` on a "collapse all" control. */
-  collapseAll() {
-    this.#setAll(false);
+  collapseAll(event) {
+    this.#setAll(false, stateReasonFor(event));
   }
   /** Drives every header/panel pair to the same expanded state. */
-  #setAll(open) {
+  #setAll(open, reason) {
     for (const trigger of this.triggerTargets) {
       const panel = this.#panelFor(trigger);
-      if (panel) this.#setExpanded(trigger, panel, open);
+      if (panel) this.#setExpanded(trigger, panel, open, reason);
     }
   }
   /** Reflects one header/panel pair's state through `aria-expanded` + `hidden`. */
-  #setExpanded(trigger, panel, open) {
+  #setExpanded(trigger, panel, open, reason) {
+    const was = trigger.getAttribute("aria-expanded") === "true";
     trigger.setAttribute("aria-expanded", open ? "true" : "false");
     panel.hidden = !open;
+    this.#labels.reflect(trigger, open);
+    if (was === open) return;
+    const detail = { reason, index: this.triggerTargets.indexOf(trigger), trigger, panel };
+    if (open) this.dispatch("open", { detail, cancelable: false });
+    else this.dispatch("close", { detail, cancelable: false });
+  }
+  /** Shows the half of a header's label pair that belongs to its `aria-expanded`. */
+  #reflectLabels(trigger) {
+    this.#labels.reflect(trigger, trigger.getAttribute("aria-expanded") === "true");
   }
   /**
    * Moves focus between headers per the APG keyboard model, skipping any header