@agent-native/toolkit 0.6.0 → 0.7.0

package/src/collab-ui/PresenceBar.tsx

@@ -0,0 +1,346 @@
+import { useMemo, type CSSProperties } from "react";
+
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "../ui/tooltip.js";
+import {
+  type CollabUser,
+  dedupeCollabUsersByEmail,
+  emailToColor,
+  emailToName,
+} from "./types.js";
+
+export interface PresenceBarProps {
+  /** Active collaborators on this document. */
+  activeUsers: CollabUser[];
+  /** Whether the agent has a durable presence entry. */
+  agentPresent?: boolean;
+  /** Whether the agent is actively making edits right now. */
+  agentActive?: boolean;
+  /** Current user's email (to exclude from the list). */
+  currentUserEmail?: string;
+  /** Max visible avatars before "+N" overflow. Default: 5 */
+  maxVisible?: number;
+  /** Additional CSS classes. */
+  className?: string;
+  /**
+   * Called when an avatar is clicked. Receives the user being clicked
+   * (or null for the agent avatar). Use this to start/stop follow mode.
+   */
+  onAvatarClick?: (user: CollabUser | null) => void;
+  /**
+   * The email of the user currently being followed. Highlighted with a
+   * blue ring to indicate active follow mode.
+   */
+  followingEmail?: string | null;
+}
+
+const AVATAR_SIZE = 28;
+const OVERLAP = -8;
+const BORDER_WIDTH = 2;
+const FONT_SIZE = 12;
+const AGENT_COLOR = "#00B5FF";
+
+const baseAvatarStyle: CSSProperties = {
+  width: AVATAR_SIZE,
+  height: AVATAR_SIZE,
+  borderRadius: "50%",
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "center",
+  fontSize: FONT_SIZE,
+  fontWeight: 700,
+  color: "#fff",
+  border: `${BORDER_WIDTH}px solid #fff`,
+  flexShrink: 0,
+  position: "relative",
+  cursor: "default",
+  boxSizing: "border-box",
+};
+
+const containerStyle: React.CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  flexDirection: "row",
+};
+
+const pulseKeyframes = `
+@keyframes _anPresencePulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.6; }
+}
+`;
+
+let styleInjected = false;
+
+function injectStyles() {
+  if (styleInjected || typeof document === "undefined") return;
+  const style = document.createElement("style");
+  style.textContent = pulseKeyframes;
+  document.head.appendChild(style);
+  styleInjected = true;
+}
+
+function UserAvatar({
+  user,
+  isFirst,
+  onClick,
+  isFollowing,
+}: {
+  user: CollabUser;
+  isFirst: boolean;
+  onClick?: () => void;
+  isFollowing?: boolean;
+}) {
+  const color = user.color || emailToColor(user.email);
+  const name = user.name || emailToName(user.email);
+  const initial = name.charAt(0).toUpperCase();
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <div
+          style={{
+            ...baseAvatarStyle,
+            backgroundColor: color,
+            marginLeft: isFirst ? 0 : OVERLAP,
+            cursor: onClick ? "pointer" : "default",
+            boxShadow: isFollowing
+              ? `0 0 0 2px #3b82f6, 0 0 0 4px #fff`
+              : `0 0 0 2px #fff`,
+          }}
+          aria-label={`${name} (${user.email})${isFollowing ? " — following" : ""}`}
+          tabIndex={onClick ? 0 : undefined}
+          role={onClick ? "button" : undefined}
+          onClick={onClick}
+          onKeyDown={(e) => {
+            if (e.key === "Enter" || e.key === " ") onClick?.();
+          }}
+        >
+          {user.avatarUrl ? (
+            <img
+              src={user.avatarUrl}
+              alt=""
+              style={{
+                width: "100%",
+                height: "100%",
+                borderRadius: "50%",
+                objectFit: "cover",
+              }}
+            />
+          ) : (
+            initial
+          )}
+        </div>
+      </TooltipTrigger>
+      <TooltipContent side="bottom">
+        {isFollowing
+          ? `Following ${name} — click to stop`
+          : onClick
+            ? `${name} — click to follow`
+            : user.email}
+      </TooltipContent>
+    </Tooltip>
+  );
+}
+
+function AgentAvatar({
+  active,
+  onClick,
+  isFollowing,
+}: {
+  active: boolean;
+  onClick?: () => void;
+  isFollowing?: boolean;
+}) {
+  injectStyles();
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        alignItems: "center",
+        gap: 4,
+      }}
+    >
+      <div
+        style={{
+          ...baseAvatarStyle,
+          backgroundColor: AGENT_COLOR,
+          marginLeft: 0,
+          animation: active ? "_anPresencePulse 2s infinite" : undefined,
+          cursor: onClick ? "pointer" : "default",
+          boxShadow: isFollowing
+            ? `0 0 0 2px #3b82f6, 0 0 0 4px #fff`
+            : undefined,
+        }}
+        title={
+          isFollowing
+            ? "Following AI — click to stop"
+            : active
+              ? "AI is editing"
+              : "AI agent"
+        }
+        onClick={onClick}
+        tabIndex={onClick ? 0 : undefined}
+        onKeyDown={(e) => {
+          if (e.key === "Enter" || e.key === " ") onClick?.();
+        }}
+        role={onClick ? "button" : undefined}
+      >
+        A
+      </div>
+      {active && !isFollowing && <AgentEditingChip />}
+      {isFollowing && (
+        <span
+          style={{
+            display: "inline-flex",
+            alignItems: "center",
+            height: 20,
+            padding: "0 8px",
+            borderRadius: 9999,
+            backgroundColor: `#3b82f620`,
+            color: "#3b82f6",
+            fontSize: 11,
+            fontWeight: 600,
+            whiteSpace: "nowrap",
+          }}
+        >
+          Following AI
+        </span>
+      )}
+    </div>
+  );
+}
+
+function AgentEditingChip() {
+  return (
+    <span
+      style={{
+        display: "inline-flex",
+        alignItems: "center",
+        gap: 4,
+        height: 20,
+        padding: "0 8px",
+        borderRadius: 9999,
+        backgroundColor: `${AGENT_COLOR}20`,
+        color: AGENT_COLOR,
+        fontSize: 11,
+        fontWeight: 600,
+        whiteSpace: "nowrap",
+      }}
+    >
+      <span
+        style={{
+          width: 6,
+          height: 6,
+          borderRadius: "50%",
+          backgroundColor: AGENT_COLOR,
+          animation: "_anPresencePulse 2s infinite",
+          flexShrink: 0,
+        }}
+      />
+      AI editing
+    </span>
+  );
+}
+
+function OverflowBadge({
+  count,
+  isFirst,
+}: {
+  count: number;
+  isFirst: boolean;
+}) {
+  return (
+    <div
+      style={{
+        ...baseAvatarStyle,
+        backgroundColor: "rgba(255,255,255,0.1)",
+        color: "rgba(255,255,255,0.5)",
+        marginLeft: isFirst ? 0 : OVERLAP,
+        fontSize: 10,
+      }}
+      title={`${count} more collaborator${count === 1 ? "" : "s"}`}
+    >
+      +{count}
+    </div>
+  );
+}
+
+export function PresenceBar({
+  activeUsers,
+  agentPresent,
+  agentActive,
+  currentUserEmail,
+  maxVisible = 5,
+  className,
+  onAvatarClick,
+  followingEmail,
+}: PresenceBarProps) {
+  const { humanUsers, showAgent } = useMemo(() => {
+    const currentEmail = currentUserEmail?.trim().toLowerCase();
+    const uniqueUsers = dedupeCollabUsersByEmail(activeUsers);
+    const humans = uniqueUsers.filter((u) => {
+      const email = u.email.trim().toLowerCase();
+      return email !== currentEmail && email !== "agent@system";
+    });
+    const hasAgentUser = uniqueUsers.some(
+      (u) => u.email.trim().toLowerCase() === "agent@system",
+    );
+    return {
+      humanUsers: humans,
+      showAgent: agentPresent || agentActive || hasAgentUser,
+    };
+  }, [activeUsers, currentUserEmail, agentPresent, agentActive]);
+
+  const visibleUsers = humanUsers.slice(0, maxVisible);
+  const overflowCount = humanUsers.length - visibleUsers.length;
+
+  if (!showAgent && humanUsers.length === 0) return null;
+
+  const followingLower = followingEmail?.trim().toLowerCase() ?? null;
+  const isFollowingAgent = followingLower === "agent@system";
+
+  return (
+    <TooltipProvider delayDuration={150}>
+      <div style={containerStyle} className={className}>
+        {showAgent && (
+          <AgentAvatar
+            active={!!agentActive}
+            onClick={onAvatarClick ? () => onAvatarClick(null) : undefined}
+            isFollowing={isFollowingAgent}
+          />
+        )}
+        {visibleUsers.length > 0 && (
+          <div
+            style={{
+              display: "flex",
+              alignItems: "center",
+              marginLeft: showAgent ? 6 : 0,
+            }}
+          >
+            {visibleUsers.map((u, i) => (
+              <UserAvatar
+                key={u.email}
+                user={u}
+                isFirst={i === 0}
+                onClick={onAvatarClick ? () => onAvatarClick(u) : undefined}
+                isFollowing={
+                  followingLower != null &&
+                  u.email.trim().toLowerCase() === followingLower
+                }
+              />
+            ))}
+            {overflowCount > 0 && (
+              <OverflowBadge count={overflowCount} isFirst={false} />
+            )}
+          </div>
+        )}
+      </div>
+    </TooltipProvider>
+  );
+}

package/src/collab-ui/RecentEditHighlights.tsx

@@ -0,0 +1,225 @@
+/**
+ * RecentEditHighlights — lingering, fading highlights over regions another
+ * participant (human or agent) just edited, with their name/avatar flag.
+ *
+ * The Google-Docs/Figma feel: when a collaborator or the AI edits something,
+ * the changed region glows in their color and the flag identifies them; the
+ * highlight fades out over the last portion of its lifetime instead of
+ * vanishing.
+ *
+ * Feed it `useRecentEdits(others)` (which reads participants' `recentEdits`
+ * awareness rings) and a `resolveRect` that maps an edit descriptor to a
+ * viewport DOMRect for your surface:
+ *
+ *   const others = usePresence(awareness, ydoc?.clientID).others;
+ *   const edits = useRecentEdits(others);
+ *   <RecentEditHighlights
+ *     edits={edits}
+ *     resolveRect={(edit) =>
+ *       edit.descriptor.kind === "selector"
+ *         ? container.querySelector(edit.descriptor.selector)?.getBoundingClientRect() ?? null
+ *         : null
+ *     }
+ *     containerRef={containerRef}
+ *   />
+ */
+
+import {
+  memo,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type RefObject,
+} from "react";
+
+import { RECENT_EDIT_TTL_MS, type AttributedRecentEdit } from "./types.js";
+
+export interface RecentEditHighlightsProps {
+  /** Attributed recent edits (from `useRecentEdits`). */
+  edits: AttributedRecentEdit[];
+  /**
+   * Resolver: maps an edit to a viewport-relative DOMRect, or null when the
+   * region can't be located (the edit is skipped).
+   */
+  resolveRect: (edit: AttributedRecentEdit) => DOMRect | null;
+  /** Container the highlights are positioned within (position: relative). */
+  containerRef: RefObject<HTMLElement | null>;
+  /** Highlight lifetime; should match useRecentEdits ttlMs. Default 6000. */
+  ttlMs?: number;
+  /** Additional CSS class for the overlay div. */
+  className?: string;
+}
+
+interface Highlight {
+  key: string;
+  color: string;
+  label: string;
+  avatarUrl?: string;
+  isAgent: boolean;
+  opacity: number;
+  rect: { top: number; left: number; width: number; height: number };
+}
+
+const HighlightItem = memo(function HighlightItem({ h }: { h: Highlight }) {
+  return (
+    <div
+      aria-label={`${h.label} edited this`}
+      style={{
+        position: "absolute",
+        top: h.rect.top,
+        left: h.rect.left,
+        width: h.rect.width,
+        height: h.rect.height,
+        borderRadius: 4,
+        pointerEvents: "none",
+        zIndex: 9997,
+        opacity: h.opacity,
+        transition: "opacity 400ms ease-out",
+        outline: `2px solid ${h.color}`,
+        outlineOffset: 2,
+        backgroundColor: `${h.color}1A`,
+        boxShadow: `0 0 0 1px ${h.color}33, 0 0 12px ${h.color}40`,
+      }}
+    >
+      <div
+        style={{
+          position: "absolute",
+          top: -22,
+          left: 0,
+          display: "flex",
+          alignItems: "center",
+          gap: 4,
+          backgroundColor: h.color,
+          color: "#fff",
+          fontSize: 10,
+          fontWeight: 600,
+          padding: "2px 6px",
+          borderRadius: 3,
+          whiteSpace: "nowrap",
+          maxWidth: 180,
+          overflow: "hidden",
+          textOverflow: "ellipsis",
+        }}
+      >
+        {h.avatarUrl ? (
+          <img
+            src={h.avatarUrl}
+            alt=""
+            style={{
+              width: 12,
+              height: 12,
+              borderRadius: "50%",
+              flexShrink: 0,
+            }}
+          />
+        ) : null}
+        {h.label}
+      </div>
+    </div>
+  );
+});
+
+export function RecentEditHighlights({
+  edits,
+  resolveRect,
+  containerRef,
+  ttlMs = RECENT_EDIT_TTL_MS,
+  className,
+}: RecentEditHighlightsProps) {
+  const [highlights, setHighlights] = useState<Highlight[]>([]);
+  const editsRef = useRef(edits);
+  editsRef.current = edits;
+  const resolveRef = useRef(resolveRect);
+  resolveRef.current = resolveRect;
+
+  const recompute = () => {
+    const container = containerRef.current;
+    if (!container) {
+      setHighlights([]);
+      return;
+    }
+    const containerRect = container.getBoundingClientRect();
+    const now = Date.now();
+    const next: Highlight[] = [];
+
+    for (const edit of editsRef.current) {
+      const domRect = resolveRef.current(edit);
+      if (!domRect) continue;
+
+      const top = domRect.top - containerRect.top;
+      const left = domRect.left - containerRect.left;
+      if (
+        left + domRect.width < 0 ||
+        top + domRect.height < 0 ||
+        left > containerRect.width ||
+        top > containerRect.height
+      ) {
+        continue;
+      }
+
+      // Fade over the final 40% of the lifetime.
+      const age = now - edit.at;
+      const fadeStart = ttlMs * 0.6;
+      const opacity =
+        age <= fadeStart
+          ? 1
+          : Math.max(0, 1 - (age - fadeStart) / (ttlMs - fadeStart));
+
+      next.push({
+        key: `${edit.clientId}:${edit.at}`,
+        color: edit.user.color || "#94a3b8",
+        label: edit.isAgent
+          ? edit.label
+            ? `AI — ${edit.label}`
+            : "AI edited"
+          : edit.label
+            ? `${edit.user.name} — ${edit.label}`
+            : edit.user.name,
+        avatarUrl: (edit.user as { avatarUrl?: string }).avatarUrl,
+        isAgent: edit.isAgent,
+        opacity,
+        rect: { top, left, width: domRect.width, height: domRect.height },
+      });
+    }
+
+    setHighlights(next);
+  };
+
+  useLayoutEffect(() => {
+    recompute();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [edits, ttlMs]);
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+    const observer = new ResizeObserver(() => recompute());
+    observer.observe(container);
+    container.addEventListener("scroll", recompute, { passive: true });
+    window.addEventListener("scroll", recompute, { passive: true });
+    return () => {
+      observer.disconnect();
+      container.removeEventListener("scroll", recompute);
+      window.removeEventListener("scroll", recompute);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [containerRef]);
+
+  return (
+    <div
+      aria-hidden
+      style={{
+        position: "absolute",
+        inset: 0,
+        pointerEvents: "none",
+        overflow: "hidden",
+      }}
+      className={className}
+    >
+      {highlights.map((h) => (
+        <HighlightItem key={h.key} h={h} />
+      ))}
+    </div>
+  );
+}