Live Presence Stack

1"use client";
2 
3import * as React from "react";
4import { motion, AnimatePresence, type Transition } from "motion/react";
5 
6import { cn } from "@/lib/utils";
7import { useReducedMotion, useVisibilityPause } from "@/lib/motiq";
8 
9/* --------------------------------------------------------------------------
10 * LivePresenceStack — a live avatar stack for collaborative workspaces.
11 *
12 * Shows who is present, animates joins/leaves without reflowing the row
13 * (layout animation + a reserved slot for the "+N" overflow), reflects a
14 * per-user status (active / idle / editing / viewing) with a shape + label
15 * (never color alone), and opens a keyboard-accessible detail popover that
16 * lists every participant with their status in words.
17 *
18 * Presence is fully controlled: pass `users` and the stack renders it. It
19 * holds no presence state of its own, so it composes with any realtime source.
20 * Clean-room original.
21 * ----------------------------------------------------------------------- */
22 
23export type PresenceStatus = "active" | "idle" | "editing" | "viewing";
24 
25export interface PresenceUser {
26  /** Stable identity — drives join/leave animation and React keys. */
27  id: string;
28  /** Human name; also the accessible name of the avatar. */
29  name: string;
30  status: PresenceStatus;
31  /** Optional explicit avatar color (any CSS color). Defaults to a hue derived from the name. */
32  color?: string;
33}
34 
35export interface LivePresenceStackProps {
36  /** Controlled presence data (source of truth). */
37  users: PresenceUser[];
38  /** Maximum avatars shown before collapsing into a "+N" chip. */
39  max?: number;
40  /** Called when a participant row is chosen in the detail popover. */
41  onSelect?: (userId: string) => void;
42  /** Accessible group label. Defaults to "N people here". */
43  label?: string;
44  className?: string;
45}
46 
47const STATUS_META: Record<PresenceStatus, { label: string; dot: string; live: boolean }> = {
48  active: { label: "Active", dot: "var(--color-success)", live: true },
49  editing: { label: "Editing", dot: "var(--color-accent)", live: true },
50  viewing: { label: "Viewing", dot: "var(--color-fg)", live: false },
51  idle: { label: "Idle", dot: "var(--color-muted)", live: false },
52};
53 
54const EASE: Transition["ease"] = [0.2, 0, 0, 1];
55 
56/** Deterministic hue from a name so colors are stable across renders/sessions. */
57function hueFromName(name: string): number {
58  let h = 0;
59  for (let i = 0; i < name.length; i++) h = (h * 31 + name.charCodeAt(i)) >>> 0;
60  return h % 360;
61}
62 
63// … truncated