use-presence-announcer.ts

use-presence-announcer.tsapps/web/src/hooks/use-presence-announcer.tsraw ← hooks2,332 B← Back to the app
1"use client";
2 
3/**
4 * usePresenceAnnouncer (TASK-0093, spec R5) — the polite live region for a
5 * page's presence: "Ana is editing this page" / "Ana left" / "Ana joined",
6 * rate-limited to ≤ 1 announcement per second, STATE CHANGES ONLY (a peer
7 * typing fires cursor frames at ~8/s — those never announce).
8 *
9 * The pure state machine (the rate limiter + the join/edit/leave state
10 * detection) is {@link PresenceAnnouncer} (lib/presence-announcer) — this
11 * hook only owns the DOM: the `role=status` live-region text, fed from the
12 * store's roster (others only), flushed on an idle tick so a change that
13 * lands inside the 1 s window is still delivered (not lost).
14 *
15 * Returns the current announcement text (the component renders it in the
16 * live region).
17 */
18import { useEffect, useRef, useState } from "react";
19import { PresenceAnnouncer } from "@/lib/presence-announcer";
20import { useBlockPatchStore } from "@/stores/block-patch-store";
21import type { Presence } from "@/lib/types";
22 
23const EMPTY_PRESENCE: Record<string, Presence> = {};
24const FLUSH_INTERVAL_MS = 1000;
25 
26export function usePresenceAnnouncer(pageId: string | null, selfUserId?: string | null): string {
27  const [text, setText] = useState("");
28  const announcerRef = useRef<PresenceAnnouncer | null>(null);
29 
30  useEffect(() => {
31    if (pageId === null) return;
32    const announcer = new PresenceAnnouncer();
33    announcerRef.current = announcer;
34 
35    const emit = (a: { text: string } | null): void => {
36      if (a !== null) setText(a.text);
37    };
38 
39    const feed = (state: { presence: Record<string, Record<string, Presence>> }): void => {
40      const roster = Object.values(state.presence[pageId] ?? EMPTY_PRESENCE);
41      emit(announcer.update(selfUserId ? roster.filter((p) => p.userId !== selfUserId) : roster));
42    };
43    feed(useBlockPatchStore.getState());
44    const off = useBlockPatchStore.subscribe(feed);
45 
46    // Flush a change that was queued inside the 1 s window (so it is
47    // delivered, not lost) — the announcer emits at most once per window.
48    const id = window.setInterval(() => emit(announcer.flush()), FLUSH_INTERVAL_MS);
49    return () => {
50      off();
51      window.clearInterval(id);
52      announcerRef.current = null;
53      announcer.reset();
54      setText("");
55    };
56  }, [pageId, selfUserId]);
57 
58  return text;
59}
60