sailfork / t3code-github / apps/ web/ src/ components/ chat/ useAssistantCitationTarget.ts

import { useEffect, useRef, useState } from "react";
import type { AssistantCitationRequest, AssistantCitationTarget } from "./AssistantCitationSource";
import type { CitationPhase } from "./citationProcedure";

const CITATION_SCROLL_KEYS = new Set([
  "ArrowUp",
  "ArrowDown",
  "PageUp",
  "PageDown",
  "Home",
  "End",
  " ",
]);

/** One activation of a citation; virtual row remounts and listeners share it. */
interface CitationNavigation {
  readonly target: AssistantCitationTarget;
  /** Takes over from the live follow for this activation. */
  readonly activate: () => void;
  /** Stops this activation for good once another one (or none) replaces it. */
  readonly retire: () => void;
  /** Listens for user navigation that stops this activation's pending scroll. */
  readonly attachDismissal: (viewport: HTMLElement | null) => () => void;
}

interface CitationSettlement {
  /** Per activation, not per key: Back/Forward can restore an earlier key. */
  readonly target: AssistantCitationTarget;
  /** Dismissed citations also drop their highlight; completed ones keep it. */
  readonly dismissed: boolean;
}

export function useAssistantCitationTarget({
  request,
  phase,
  viewport,
  onManualNavigation,
}: {
  request: AssistantCitationRequest | null;
  phase: CitationPhase | null;
  viewport: HTMLElement | null;
  onManualNavigation: () => void;
}) {
  const [settlement, setSettlement] = useState<CitationSettlement | null>(null);
  const [listLoaded, setListLoaded] = useState(false);
  const onListLoad = () => setListLoaded(true);

  // Rows and listeners mutate the activation, so it lives as long as its
  // request; a target belongs to one request, so returning to an earlier key
  // never reuses it.
  const [navigation, setNavigation] = useState<CitationNavigation | null>(null);
  let current = navigation;
  if ((request?.key ?? null) !== (navigation?.target.key ?? null)) {
    current = request ? createCitationNavigation(request) : null;
    setNavigation(current);
  }
  function createCitationNavigation(next: AssistantCitationRequest): CitationNavigation {
    let done = false;
    const activationRef: AssistantCitationTarget["activationRef"] = {
      current: { scrolled: false, dismissed: false },
    };
    const target: AssistantCitationTarget = {
      ...next,
      activationRef,
      onComplete: () => {
        done = true;
        // The thread-open follow can run after the scroll started.
        onManualNavigation();
        setSettlement({ target, dismissed: false });
      },
    };
    const activate = () => {
      // The follow must yield before the citation row starts scrolling.
      if (!done) onManualNavigation();
    };
    const retire = () => {
      activationRef.current.dismissed = true;
      activationRef.current.cancelScroll?.();
    };
    const attachDismissal = (citationViewport: HTMLElement | null) => {
      // User navigation stops a pending citation scroll; Escape dismisses it outright.
      const dismiss = (onlyPending: boolean) => {
        const activation = activationRef.current;
        if (activation.dismissed || (onlyPending && (activation.scrolled || done))) return;
        activation.dismissed = true;
        activation.cancelScroll?.();
        if (!activation.scrolled && !done) onManualNavigation();
        done = true;
        setSettlement({ target, dismissed: true });
      };
      const onKeyDown = (event: KeyboardEvent) => {
        if (event.key === "Escape") {
          dismiss(false);
        } else if (
          CITATION_SCROLL_KEYS.has(event.key) &&
          event.target instanceof Node &&
          citationViewport?.contains(event.target)
        ) {
          dismiss(true);
        }
      };
      const onWheel = (event: WheelEvent) => {
        if (event.deltaY !== 0) dismiss(true);
      };
      const onNavigation = () => dismiss(true);
      document.addEventListener("keydown", onKeyDown);
      document.addEventListener("pointerdown", onNavigation, true);
      citationViewport?.addEventListener("wheel", onWheel, { passive: true });
      citationViewport?.addEventListener("touchmove", onNavigation, { passive: true });
      return () => {
        document.removeEventListener("keydown", onKeyDown);
        document.removeEventListener("pointerdown", onNavigation, true);
        citationViewport?.removeEventListener("wheel", onWheel);
        citationViewport?.removeEventListener("touchmove", onNavigation);
      };
    };
    return { target, activate, retire, attachDismissal };
  }

  // Retiring is one-way, so it runs when the activation is replaced rather than
  // in a cleanup: StrictMode and <Activity> replay cleanups on a live activation.
  // Unmounting needs no retire; the rows observing it unmount with the list.
  const activatedRef = useRef<CitationNavigation | null>(null);
  // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- retires the replaced citation scroll and activates the new one, releasing the timeline follow
  useEffect(() => {
    if (activatedRef.current === current) return;
    activatedRef.current?.retire();
    activatedRef.current = current;
    current?.activate();
  }, [current]);
  // Escape and pointerdown dismiss before the viewport mounts; the viewport
  // listeners join once it exists.
  // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- subscribes document and viewport listeners that dismiss the pending citation scroll
  useEffect(() => current?.attachDismissal(viewport), [current, viewport]);

  const settled = current !== null && settlement?.target === current.target ? settlement : null;
  const target =
    current !== null && phase?._tag === "ready" && listLoaded && settled?.dismissed !== true
      ? current.target
      : null;
  const positioning = current !== null && phase?._tag !== "failed" && settled === null;

  return {
    target,
    positioning,
    onListLoad,
    alwaysRender:
      target && positioning && phase?._tag === "ready" ? { keys: [phase.rowId] } : undefined,
  };
}