PresenceBar.tsx

PresenceBar.tsxapps/web/src/components/collaboration/PresenceBar.tsxraw ← collaboration6,550 B← Back to the app
1"use client";
2 
3/**
4 * PresenceBar (TASK-0093, spec R3) — the page/database header avatar bar:
5 * who's here, colored, with name tooltips, a "+n" overflow (click → a
6 * popover listing every peer + their state), and the accessible name
7 * `"{n} people are viewing this page"`.
8 *
9 *  - Shows **others only** (the local user's peer is excluded by the server
10 *    — it never echoes the sender — and defensively by `selfUserId` here).
11 *  - **Empty state: the bar is absent** (0 others — an empty bar is noise;
12 *    the "N people" label only when ≥ 1 other).
13 *  - The bar is a **plain list, NOT a live region** (it churns too fast for
14 *    screen readers — the announcements live in the separate polite live
15 *    region, spec R5).
16 *  - The color is never the sole identifier: each avatar carries the peer's
17 *    name as its accessible name + tooltip (the a11y rule, ux-req §12).
18 *  - Mobile: the `maxVisible` prop compresses the bar (default 5; a mobile
19 *    layout can pass 3).
20 *
21 * The 50-peer avatars-only cap needs no special-casing here: peers with
22 * `cursor: null` (the stripped mode) still render their avatar — only the
23 * "editing" descriptor degrades to "viewing".
24 */
25import { useEffect, useRef, useState } from "react";
26import { initials } from "@factory/ui";
27import { cn } from "@/lib/utils";
28import { presenceColors } from "@/lib/presence-color";
29import type { Presence } from "@/lib/types";
30 
31export interface PresenceBarProps {
32  /** The page's OTHER peers (self excluded). */
33  peers: readonly Presence[];
34  /** The local user's id (defensively excluded if present in `peers`). */
35  selfUserId?: string | null;
36  /** Resolve a cursor's block to a type label for the popover ("editing
37   *  Heading 1"). Omit → the popover says "editing" without a type. */
38  blockTypeFor?: (blockId: string) => string | null;
39  /** Max avatars before the "+n" overflow (default 5; pass 3 on mobile). */
40  maxVisible?: number;
41  className?: string;
42}
43 
44/** A peer's popover descriptor: what they're doing right now. */
45function describe(peer: Presence, blockTypeFor?: (blockId: string) => string | null): string {
46  if (peer.viewing === false) return "viewing";
47  if (peer.cursor) {
48    const type = blockTypeFor?.(peer.cursor.blockId);
49    return type ? `editing ${type}` : "editing";
50  }
51  return "viewing";
52}
53 
54function AvatarDot({ peer }: { peer: Presence }) {
55  const colors = presenceColors(peer.color);
56  return (
57    <span
58      role="img"
59      aria-label={`${peer.name} is viewing this page`}
60      title={`${peer.name} — ${describe(peer)}`}
61      className="relative inline-flex h-6 w-6 shrink-0 select-none items-center justify-center rounded-full text-[10px] font-semibold ring-1"
62      style={{
63        backgroundColor: colors.softBg,
64        color: colors.solid,
65        boxShadow: `0 0 0 1px ${colors.solid}55`,
66      }}
67    >
68      {initials(peer.name) || "?"}
69    </span>
70  );
71}
72 
73export function PresenceBar({
74  peers,
75  selfUserId,
76  blockTypeFor,
77  maxVisible = 5,
78  className,
79}: PresenceBarProps) {
80  // Others only (the server already excludes self; this is the safety net).
81  const others = selfUserId ? peers.filter((p) => p.userId !== selfUserId) : peers;
82  const [overflowOpen, setOverflowOpen] = useState(false);
83  const overflowRef = useRef<HTMLDivElement>(null);
84 
85  // Close the overflow popover on outside click / Escape.
86  useEffect(() => {
87    if (!overflowOpen) return;
88    const onDown = (e: MouseEvent): void => {
89      if (overflowRef.current && !overflowRef.current.contains(e.target as Node))
90        setOverflowOpen(false);
91    };
92    const onKey = (e: KeyboardEvent): void => {
93      if (e.key === "Escape") setOverflowOpen(false);
94    };
95    document.addEventListener("mousedown", onDown);
96    document.addEventListener("keydown", onKey);
97    return () => {
98      document.removeEventListener("mousedown", onDown);
99      document.removeEventListener("keydown", onKey);
100    };
101  }, [overflowOpen]);
102 
103  // Empty state: the bar is absent (0 others).
104  if (others.length === 0) return null;
105 
106  const visible = others.slice(0, maxVisible);
107  const overflow = others.slice(maxVisible);
108  const count = others.length;
109  const label = `${count} ${count === 1 ? "person" : "people"} ${count === 1 ? "is" : "are"} viewing this page`;
110 
111  return (
112    <div className={cn("relative inline-flex items-center", className)} aria-label={label}>
113      {/* A PLAIN list (not a live region — spec R3: the bar churns too fast
114          for SR; the announcements live in the separate polite live region).
115          Each avatar keeps its accessible name (color is never the sole
116          identifier). */}
117      <ul className="flex items-center -space-x-1.5">
118        {visible.map((p) => (
119          <li key={p.userId}>
120            <AvatarDot peer={p} />
121          </li>
122        ))}
123      </ul>
124 
125      {overflow.length > 0 ? (
126        <div className="relative" ref={overflowRef}>
127          <button
128            type="button"
129            onClick={() => setOverflowOpen((v) => !v)}
130            aria-haspopup="true"
131            aria-expanded={overflowOpen}
132            aria-label={`${overflow.length} more people are viewing this page`}
133            className="-ml-1.5 inline-flex h-6 min-w-6 items-center justify-center rounded-full border border-border bg-muted px-1 text-[10px] font-semibold text-muted-foreground hover:bg-accent"
134          >
135            +{overflow.length}
136          </button>
137 
138          {overflowOpen ? (
139            <div
140              role="menu"
141              aria-label="People viewing this page"
142              className="absolute right-0 top-7 z-50 w-56 rounded-lg border border-border bg-popover p-1 text-sm shadow-md"
143            >
144              <p className="px-2 py-1 text-xs font-medium text-muted-foreground">{count} viewing</p>
145              <ul>
146                {others.map((p) => (
147                  <li
148                    key={p.userId}
149                    className="flex items-center gap-2 rounded-md px-2 py-1.5 hover:bg-accent/60"
150                  >
151                    <AvatarDot peer={p} />
152                    <span className="min-w-0 flex-1">
153                      <span className="block truncate font-medium">{p.name}</span>
154                      <span className="block text-xs text-muted-foreground">
155                        {describe(p, blockTypeFor)}
156                      </span>
157                    </span>
158                  </li>
159                ))}
160              </ul>
161            </div>
162          ) : null}
163        </div>
164      ) : null}
165    </div>
166  );
167}
168