stimeo-ui 0.9.0 → 0.11.0

package/dist/cable/index.js

@@ -2,6 +2,15 @@ import { Controller } from '@hotwired/stimulus';
 import { createConsumer } from '@rails/actioncable';
 
 // src/cable/live_counter_controller.ts
+function parseSubscriptionParams(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {};
+    return parsed;
+  } catch {
+    return {};
+  }
+}
 var sharedConsumer = null;
 function setCableConsumer(consumer) {
   sharedConsumer = consumer;
@@ -10,41 +19,93 @@ function getCableConsumer() {
   if (!sharedConsumer) sharedConsumer = createConsumer();
   return sharedConsumer;
 }
+var sharedSubscriptions = /* @__PURE__ */ new WeakMap();
+function identifierOf(channel) {
+  return JSON.stringify(typeof channel === "string" ? { channel } : channel);
+}
 function createConfirmedSubscription(channel, mixin) {
-  let confirmed = false;
-  let rejected = false;
-  const subscription = getCableConsumer().subscriptions.create(channel, {
-    // A refusal is final: Action Cable never confirms a rejected subscription,
-    // so a late connected/disconnected (only possible from a misbehaving
-    // consumer double) must not reopen the gate `rejected` promised shut.
-    connected: () => {
-      if (rejected) return;
-      confirmed = true;
-      mixin.connected?.();
-    },
-    disconnected: () => {
-      if (rejected) return;
-      confirmed = false;
-      mixin.disconnected?.();
-    },
-    rejected: () => {
-      confirmed = false;
-      rejected = true;
-      mixin.rejected?.();
-    },
-    received: (data) => mixin.received?.(data)
-  });
+  const consumer = getCableConsumer();
+  let registry = sharedSubscriptions.get(consumer);
+  if (!registry) {
+    registry = /* @__PURE__ */ new Map();
+    sharedSubscriptions.set(consumer, registry);
+  }
+  const identifier = identifierOf(channel);
+  const member = { mixin, catchUp: false };
+  let shared = registry.get(identifier);
+  if (!shared) {
+    shared = openSharedSubscription(consumer, channel);
+    registry.set(identifier, shared);
+  } else if (shared.rejected || shared.confirmed) {
+    const owed = shared;
+    member.catchUp = true;
+    queueMicrotask(() => {
+      if (!member.catchUp) return;
+      member.catchUp = false;
+      if (owed.rejected) mixin.rejected?.();
+      else mixin.connected?.();
+    });
+  }
+  shared.members.add(member);
+  const owner = shared;
+  const registered = registry;
+  let active = true;
   return {
-    perform: (action, data) => subscription.perform(action, data),
-    unsubscribe: () => subscription.unsubscribe(),
+    perform: (action, data) => owner.subscription.perform(action, data),
+    unsubscribe: () => {
+      if (!active) return;
+      active = false;
+      member.catchUp = false;
+      owner.members.delete(member);
+      if (owner.members.size === 0) {
+        registered.delete(identifier);
+        owner.subscription.unsubscribe();
+      }
+    },
     get confirmed() {
-      return confirmed;
+      return owner.confirmed;
     },
     get rejected() {
-      return rejected;
+      return owner.rejected;
     }
   };
 }
+function openSharedSubscription(consumer, channel) {
+  const members = /* @__PURE__ */ new Set();
+  const fanOut = (deliver) => {
+    for (const member of [...members]) {
+      member.catchUp = false;
+      deliver(member.mixin);
+    }
+  };
+  const shared = {
+    members,
+    confirmed: false,
+    rejected: false,
+    subscription: consumer.subscriptions.create(channel, {
+      // A refusal is final: Action Cable never confirms a rejected subscription,
+      // so a late connected/disconnected (only possible from a misbehaving
+      // consumer double) must not reopen the gate `rejected` promised shut.
+      connected: () => {
+        if (shared.rejected) return;
+        shared.confirmed = true;
+        fanOut((mixin) => mixin.connected?.());
+      },
+      disconnected: () => {
+        if (shared.rejected) return;
+        shared.confirmed = false;
+        fanOut((mixin) => mixin.disconnected?.());
+      },
+      rejected: () => {
+        shared.confirmed = false;
+        shared.rejected = true;
+        fanOut((mixin) => mixin.rejected?.());
+      },
+      received: (data) => fanOut((mixin) => mixin.received?.(data))
+    })
+  };
+  return shared;
+}
 
 // src/cable/live_counter_controller.ts
 var DISABLED_MARKER = "data-live-counter-disabled";
@@ -52,17 +113,28 @@ var LiveCounterController = class extends Controller {
   static targets = ["value", "trigger"];
   static values = {
     channel: { type: String, default: "" },
-    params: { type: Object, default: {} },
+    params: { type: String, default: "" },
     id: { type: String, default: "" }
   };
   static actions = ["increment"];
   static events = ["change"];
+  /** Identifier parameters parsed once from their declaration, never in the hot path. */
+  #params = {};
   #subscription = null;
+  /**
+   * Re-parses the identifier parameters when the declaration changes.
+   *
+   * A malformed declaration falls back to no parameters, so the identifier keeps
+   * naming the channel instead of the subscription never being created at all.
+   */
+  paramsValueChanged() {
+    this.#params = parseSubscriptionParams(this.paramsValue);
+  }
   connect() {
     this.element.removeAttribute("data-live-counter-rejected");
     if (this.channelValue) {
       this.#subscription = createConfirmedSubscription(
-        { channel: this.channelValue, ...this.paramsValue },
+        { channel: this.channelValue, ...this.#params },
         {
           connected: () => this.#syncTriggers(),
           // A drop closes the send window (the shared subscription tracks it)
@@ -240,13 +312,15 @@ var PresenceController = class extends Controller {
   static targets = ["count", "list", "template"];
   static values = {
     channel: { type: String, default: "" },
-    params: { type: Object, default: {} },
+    params: { type: String, default: "" },
     id: { type: String, default: "" },
     name: { type: String, default: "" },
     heartbeat: { type: Number, default: 15e3 },
     timeout: { type: Number, default: 4e4 }
   };
   static events = ["join", "leave", "change"];
+  /** Identifier parameters parsed once from their declaration, never in the hot path. */
+  #params = {};
   #subscription = null;
   /** Present peers keyed by id (insertion order = join order). */
   #peers = /* @__PURE__ */ new Map();
@@ -256,13 +330,22 @@ var PresenceController = class extends Controller {
   #lastBeaconAt = 0;
   /** Pending trailing-edge convergence beacon (at most one queued). */
   #pendingBeacon = null;
+  /**
+   * Re-parses the identifier parameters when the declaration changes.
+   *
+   * A malformed declaration falls back to no parameters, so the identifier keeps
+   * naming the channel instead of the subscription never being created at all.
+   */
+  paramsValueChanged() {
+    this.#params = parseSubscriptionParams(this.paramsValue);
+  }
   connect() {
     this.#reset();
     this.element.removeAttribute("data-presence-rejected");
     if (this.hasCountTarget) this.countTarget.textContent = this.#countMessage(0);
     if (!this.channelValue) return;
     this.#subscription = createConfirmedSubscription(
-      { channel: this.channelValue, ...this.paramsValue },
+      { channel: this.channelValue, ...this.#params },
       {
         // The first beacon must wait for the confirmed subscription — a
         // perform() before that is silently dropped by Action Cable. Fires
@@ -441,25 +524,75 @@ var PresenceController = class extends Controller {
     }
   }
 };
-var TypingIndicatorController = class extends Controller {
+
+// 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/cable/typing_indicator_controller.ts
+var DEFAULT_TIMEOUT = 3e3;
+var DEFAULT_THROTTLE = 2e3;
+var fillTokens = (template, values) => template.replace(/%\{(name|names|count)\}/g, (match, token) => values[token] ?? match);
+var TypingIndicatorController = class _TypingIndicatorController extends Controller {
   static targets = ["input", "status"];
   static values = {
     channel: { type: String, default: "" },
-    params: { type: Object, default: {} },
+    params: { type: String, default: "" },
     name: { type: String, default: "" },
-    timeout: { type: Number, default: 3e3 },
+    timeout: { type: Number, default: DEFAULT_TIMEOUT },
     // Must stay below `timeout`: the throttle is leading-edge only (no trailing
     // send), so a receiver's display survives continuous typing only while a
     // fresh signal lands within its timeout window.
-    throttle: { type: Number, default: 2e3 }
+    throttle: { type: Number, default: DEFAULT_THROTTLE },
+    announceOneText: { type: String, default: "" },
+    announceManyText: { type: String, default: "" }
   };
   static events = ["change"];
+  /** Delay (ms) before one settled typer set is sent to the shared announcer. */
+  static #announceDelay = 200;
+  /** 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();
   #timers = new SafeTimeout();
   /** Epoch ms of the last broadcast, for leading-edge throttling. */
   #lastSentAt = 0;
+  /** The one outstanding announcement, so a newer set supersedes it. */
+  #announceId = null;
+  /**
+   * Re-parses the identifier parameters when the declaration changes.
+   *
+   * A malformed declaration falls back to no parameters, so the identifier keeps
+   * naming the channel instead of the subscription never being created at all.
+   */
+  paramsValueChanged() {
+    this.#params = parseSubscriptionParams(this.paramsValue);
+  }
+  /**
+   * Paints the current copy into a `status` target that arrived at runtime.
+   *
+   * No event: the set of typers did not change, only the element that displays it.
+   * Without this a region swapped in mid-conversation stays empty while `data-typing`
+   * still says someone is typing, leaving the state in the visual hook alone. An empty
+   * set needs no paint — a fresh region already shows it.
+   */
+  statusTargetConnected() {
+    if (this.#typers.size > 0) this.#paint();
+  }
   connect() {
     this.element.removeAttribute("data-typing");
     this.element.removeAttribute("data-typing-indicator-rejected");
@@ -467,7 +600,7 @@ var TypingIndicatorController = class extends Controller {
     this.element.addEventListener("input", this.#onInput);
     if (this.channelValue) {
       this.#subscription = createConfirmedSubscription(
-        { channel: this.channelValue, ...this.paramsValue },
+        { channel: this.channelValue, ...this.#params },
         {
           // The server refused the subscription: the send gate stays shut for
           // good, and the hook lets the consumer's CSS reflect the dead stream.
@@ -484,6 +617,7 @@ var TypingIndicatorController = class extends Controller {
     this.#subscription?.unsubscribe();
     this.#subscription = null;
     this.#timers.clearAll();
+    this.#announceId = null;
     this.#typers.clear();
     this.element.removeAttribute("data-typing");
     this.element.removeAttribute("data-typing-indicator-rejected");
@@ -494,7 +628,7 @@ var TypingIndicatorController = class extends Controller {
   #onInput = () => {
     if (!this.#subscription?.confirmed) return;
     const now = Date.now();
-    if (now - this.#lastSentAt < this.throttleValue) return;
+    if (now - this.#lastSentAt < this.#throttle) return;
     this.#lastSentAt = now;
     this.#subscription.perform("typing", { name: this.nameValue });
   };
@@ -511,25 +645,74 @@ var TypingIndicatorController = class extends Controller {
     const added = existing === void 0;
     this.#typers.set(
       name,
-      this.#timers.set(() => this.#untrack(name), this.timeoutValue)
+      this.#timers.set(() => this.#untrack(name), this.#timeout)
     );
     if (added) this.#render();
   }
+  /**
+   * The silence after which a typer is dropped, in ms: a finite, non-negative number.
+   * Anything else names no delay — `setTimeout` reads `NaN`, a negative value and
+   * `Infinity` alike as "now", so the typer would vanish in the same task it appeared
+   * and the indicator could never be seen. Such a declaration falls back to the default.
+   */
+  get #timeout() {
+    const declared = this.timeoutValue;
+    return Number.isFinite(declared) && declared >= 0 ? declared : DEFAULT_TIMEOUT;
+  }
+  /**
+   * The minimum gap between outgoing signals, in ms: a finite, non-negative number.
+   * Anything else names no interval, and the gate then settles the same way at every
+   * keystroke — `NaN` and a negative gap leave it open, so every keystroke broadcasts,
+   * while `Infinity` is never exceeded, so nothing is ever sent. Such a declaration
+   * falls back to the default.
+   */
+  get #throttle() {
+    const declared = this.throttleValue;
+    return Number.isFinite(declared) && declared >= 0 ? declared : DEFAULT_THROTTLE;
+  }
   #untrack(name) {
     this.#typers.delete(name);
     this.#render();
   }
-  /** Reflects the typer set onto the hook + live region and emits `change`. */
+  /** Reflects the typer set onto the display, announces it, and emits `change`. */
   #render() {
+    const names = this.#paint();
+    this.#announce(names);
+    this.dispatch("change", { detail: { names } });
+  }
+  /**
+   * Hands the settled typer set to the page's shared announcer.
+   *
+   * Debounced: a burst of arrivals is one announcement, not one per name. Only a
+   * non-empty set is announced — that typing stopped is not news worth interrupting
+   * 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.
+   */
+  #announce(names) {
+    if (this.#announceId !== null) this.#timers.clear(this.#announceId);
+    this.#announceId = null;
+    if (names.length === 0) return;
+    const message = names.length === 1 ? fillTemplate(this.announceOneTextValue, { name: names[0] ?? "" }) : fillTemplate(this.announceManyTextValue, {
+      names: names.join(", "),
+      count: names.length
+    });
+    this.#announceId = this.#timers.set(() => {
+      announce(message);
+      this.#announceId = null;
+    }, _TypingIndicatorController.#announceDelay);
+  }
+  /** Writes the current typer set onto the hook and the status slot. */
+  #paint() {
     const names = [...this.#typers.keys()];
     this.element.setAttribute("data-typing", names.length > 0 ? "true" : "false");
     if (this.hasStatusTarget) {
       this.statusTarget.textContent = this.#message(names);
     }
-    this.dispatch("change", { detail: { names } });
+    return names;
   }
   /**
-   * Builds the live-region copy. Localizable through `data-one` / `data-many`
+   * Builds the status copy. Localizable through `data-one` / `data-many`
    * templates on the status target (`%{name}` / `%{names}` / `%{count}`); terse
    * English is the fallback.
    */
@@ -539,10 +722,10 @@ var TypingIndicatorController = class extends Controller {
     if (names.length === 1) {
       const template2 = this.statusTarget.dataset.one;
       const name = names[0] ?? "";
-      return template2 ? template2.replace("%{name}", name) : `${name} is typing\u2026`;
+      return template2 ? fillTokens(template2, { name }) : `${name} is typing\u2026`;
     }
     const template = this.statusTarget.dataset.many;
-    return template ? template.replace("%{names}", joined).replace("%{count}", String(names.length)) : `${joined} are typing\u2026`;
+    return template ? fillTokens(template, { names: joined, count: String(names.length) }) : `${joined} are typing\u2026`;
   }
 };