blomios/IdeA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(frontend): restaure le suivi automatique du scroll des fils de messages — hook partagé useThreadScrollController — #356 (QA verte)

Browse Source 
Cause: la logique de suivi du bas de fil était dupliquée et ad-hoc dans chaque surface (scrollRef, followsLatestRef, showLatestButton dans CustomAgentChatView), et dérivait dans certains cas — le fil ne suivait plus les nouveaux messages.

Fix: nouveau hook partagé shared/lib/useThreadScrollController (resté collé au bas quand l'utilisateur est déjà en bas, position préservée pendant la consultation de l'historique, notice latest sinon) câblé dans CustomAgentChatView, ConversationViewer et TicketAssistantPanel.

QA verte: npm run typecheck exit 0; tests ciblés useThreadScrollController, CustomAgentChatView, ConversationViewer/useConversationThread et tickets verts; npm test 1400/1400 verts (137 fichiers); git diff --check.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Blomios
2026-09-14 11:15:10 +02:00
parent 7eb501e013
commit ec941d1af6
7 changed files with 512 additions and 144 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
frontend/src/features/agents/CustomAgentChatView.test.tsx
View File

@ -6169,11 +6169,12 @@ describe("CustomAgentChatView", () => {
const scrollTo = vi.fn();
Object.defineProperty(scroll, "scrollTo", { value: scrollTo, configurable: true });
fireEvent.scroll(scroll);
fireEvent.click(screen.getByRole("button", { name: "Aller au dernier message" }));
expect(scrollTo).toHaveBeenCalledWith({ top: 1000, behavior: "smooth" });
expect(screen.queryByRole("button", { name: "Aller au dernier message" })).toBeNull();
fireEvent.click(screen.getByRole("button", { name: "Aller au Final précédent" }));
expect(scrollTo).toHaveBeenLastCalledWith({ top: 0, behavior: "smooth" });
expect(scrollTo).toHaveBeenCalledWith({ top: 0, behavior: "smooth" });
fireEvent.click(screen.getByRole("button", { name: "Aller au dernier message" }));
expect(scrollTo).toHaveBeenLastCalledWith({ top: 1000, behavior: "smooth" });
});
it("surfaces non-NOT_FOUND reattach errors instead of launching a new session", async () => {

77
frontend/src/features/agents/CustomAgentChatView.tsx
View File

@ -43,7 +43,14 @@ import {
markProjectCliInteractionStarted,
markProjectCliInteractionStopped,
} from "@/features/projects/projectCliInteractionActivity";
import { Button, EntryTimestamp, Spinner, cn, normalizeTimestamp } from "@/shared";
import {
Button,
EntryTimestamp,
Spinner,
cn,
normalizeTimestamp,
useThreadScrollController,
} from "@/shared";
import { onProjectIconChanged, ProjectIcon } from "@/features/projects/projectIcons";
import type {
ChatAttachmentInput,
@ -1054,7 +1061,6 @@ export function CustomAgentChatView({
} | null>(null);
const [queueAnnouncement, setQueueAnnouncement] = useState("");
const [queueDrainReady, setQueueDrainReady] = useState(false);
const [showLatestButton, setShowLatestButton] = useState(false);
const [slashCommands, setSlashCommands] = useState<SlashCommand[]>([]);
const [slashMenuOpen, setSlashMenuOpen] = useState(false);
const [slashActiveIndex, setSlashActiveIndex] = useState(0);
@ -1071,7 +1077,6 @@ export function CustomAgentChatView({
const [stopTerminalOverride, setStopTerminalOverride] = useState(false);
const [error, setError] = useState<ChatErrorState | null>(null);
const [projectIcon, setProjectIcon] = useState<ProjectIconRef | null>(null);
const scrollRef = useRef<HTMLDivElement | null>(null);
const composerRef = useRef<HTMLTextAreaElement | null>(null);
const chatRootRef = useRef<HTMLDivElement | null>(null);
const turnsRef = useRef(turns);
@ -1111,7 +1116,6 @@ export function CustomAgentChatView({
const queuedMessagesRef = useRef(queuedMessages);
queuedMessagesRef.current = queuedMessages;
const messageQueueKeyRef = useRef(initialMessageQueueKey);
const followsLatestRef = useRef(true);
const imageTokenSeqRef = useRef(0);
const mountedRef = useRef(false);
const openOrAttachCountRef = useRef(0);
@ -1252,6 +1256,19 @@ export function CustomAgentChatView({
const [composerHistoryIndex, setComposerHistoryIndex] =
useState<number | null>(null);
const displayTurns = turns;
const threadScroll = useThreadScrollController({
itemCount: displayTurns.length,
completedItemCount: displayTurns.filter(
(turn) => turn.role === "final" || turn.role === "error",
).length,
contentVersion: displayTurns
.map((turn) => {
if ("text" in turn) return `${turn.role}:${turn.text.length}`;
if (turn.role === "tool") return `${turn.role}:${turn.label.length}`;
return `${turn.role}:${JSON.stringify(turn.progress).length}:${Boolean(turn.settled)}`;
})
.join("|"),
});
const hasPreviousFinal = displayTurns.some((turn) => turn.role === "final");
const sessionLabel = structuredSessionLabel(profile.structuredAdapter);
const [requesterDelegation, setRequesterDelegation] =
@ -1976,32 +1993,11 @@ export function CustomAgentChatView({
);
const scrollToLatest = useCallback(() => {
const element = scrollRef.current;
if (!element) return;
const top = element.scrollHeight;
if (element.scrollTo) {
element.scrollTo({
top,
behavior: prefersReducedMotion() ? "auto" : "smooth",
});
} else {
element.scrollTop = top;
}
followsLatestRef.current = true;
setShowLatestButton(false);
}, [prefersReducedMotion]);
const updateLatestVisibility = useCallback(() => {
const element = scrollRef.current;
if (!element) return;
const atBottom =
element.scrollHeight - element.scrollTop - element.clientHeight <= 24;
followsLatestRef.current = atBottom;
setShowLatestButton(!atBottom);
}, []);
threadScroll.scrollToBottom(prefersReducedMotion() ? "auto" : "smooth");
}, [prefersReducedMotion, threadScroll]);
const scrollToPreviousFinal = useCallback(() => {
const element = scrollRef.current;
const element = threadScroll.scrollRef.current;
if (!element) return;
const finals = Array.from(
element.querySelectorAll<HTMLElement>("[data-chat-final]"),
@ -2020,16 +2016,8 @@ export function CustomAgentChatView({
} else {
element.scrollTop = top;
}
followsLatestRef.current = false;
setShowLatestButton(true);
}, [prefersReducedMotion]);
useEffect(() => {
const element = scrollRef.current;
if (!element || !followsLatestRef.current) return;
element.scrollTop = element.scrollHeight;
setShowLatestButton(false);
}, [displayTurns]);
threadScroll.readHistory();
}, [prefersReducedMotion, threadScroll]);
useEffect(() => {
if (selfEmittedSessionIdRef.current === sessionId) {
@ -2523,6 +2511,7 @@ export function CustomAgentChatView({
markProjectCliInteractionFinished(projectId, interactionId);
activeInteractionIdRef.current = null;
};
threadScroll.followLatest();
setBusy(true);
setError(null);
updateChatViewState((prev) => ({
@ -2959,10 +2948,10 @@ export function CustomAgentChatView({
/>
</div>
<div
ref={scrollRef}
ref={threadScroll.scrollRef}
data-testid="custom-agent-chat-scroll"
className="relative z-10 flex min-h-0 flex-1 basis-0 flex-col gap-2 overflow-x-hidden overflow-y-auto px-3 py-3"
onScroll={updateLatestVisibility}
onScroll={threadScroll.onScroll}
>
<div className="shrink-0">
<AnnouncementsPreview
@ -3038,14 +3027,16 @@ export function CustomAgentChatView({
mobile && "pb-[max(0.5rem,env(safe-area-inset-bottom))]",
)}
>
{showLatestButton && (
{threadScroll.notice && (
<button
type="button"
aria-label={tr("Aller au dernier message", "Go to latest message")}
className="absolute -top-12 left-1/2 z-20 flex h-11 w-11 -translate-x-1/2 items-center justify-center rounded-full border border-border bg-raised/95 text-lg text-content shadow-md hover:border-border-strong"
className="absolute -top-10 left-1/2 z-20 -translate-x-1/2 rounded-full border border-border bg-raised/95 px-3 py-1 text-xs text-content shadow-md hover:border-border-strong"
onClick={scrollToLatest}
>
↓
{threadScroll.notice === "new"
? tr("Nouveaux messages ↓", "New messages ↓")
: tr("Revenir en bas ↓", "Back to bottom ↓")}
</button>
)}
<div className="sr-only" aria-live="polite" aria-atomic="true">

155
frontend/src/features/conversations/ConversationViewer.tsx
View File

@ -18,7 +18,13 @@ import type {
TurnSource,
TurnView,
} from "@/domain";
import { Button, EntryTimestamp, Spinner, cn } from "@/shared";
import {
Button,
EntryTimestamp,
Spinner,
cn,
useThreadScrollController,
} from "@/shared";
import { useProjectWorkState } from "@/features/workstate";
import { useConversationThread } from "./useConversationThread";
import { useI18n } from "@/i18n";
@ -205,6 +211,13 @@ export function ConversationViewer({
}: ConversationViewerProps) {
const { tr } = useI18n();
const vm = useConversationThread(projectId, conversationId);
const threadScroll = useThreadScrollController({
itemCount: vm.turns.length,
completedItemCount: vm.turns.length,
contentVersion: vm.turns
.map((turn) => `${turn.id}:${turn.textLen}:${turn.text.length}`)
.join("|"),
});
// Reuse the already-loaded work-state inventory to resolve agent names.
const work = useProjectWorkState(projectId);
@ -300,76 +313,96 @@ export function ConversationViewer({
)}
{/* ── Thread ── */}
<div className="flex flex-1 flex-col gap-2 overflow-auto px-4 py-3">
{vm.hasMore && (
<div className="flex justify-center">
<Button
size="sm"
variant="ghost"
onClick={() => void vm.loadOlder()}
loading={vm.busy}
>
{tr("Charger les tours précédents", "Load previous turns")}
</Button>
</div>
)}
{vm.busy && vm.turns.length === 0 ? (
<div className="flex items-center gap-2 text-sm text-muted">
<Spinner size={14} />
<span>{tr("Chargement du fil…", "Loading thread…")}</span>
</div>
) : vm.turns.length === 0 ? (
<div className="max-w-xl text-sm text-muted">
<p>{emptyState.message}</p>
{emptyState.detail && (
<p className="mt-1 text-xs text-faint">{emptyState.detail}</p>
)}
{emptyState.action && onOpenConversation && (
<div className="relative flex min-h-0 flex-1">
<div
ref={threadScroll.scrollRef}
data-testid="conversation-viewer-scroll"
className="flex min-h-0 flex-1 flex-col gap-2 overflow-auto px-4 py-3"
onScroll={threadScroll.onScroll}
>
{vm.hasMore && (
<div className="flex justify-center">
<Button
size="sm"
variant="ghost"
className="mt-2"
onClick={() =>
onOpenConversation(emptyState.action!.conversationId)
void threadScroll.preserveAnchor(() => vm.loadOlder())
}
loading={vm.busy}
>
{emptyState.action.label}
{tr("Charger les tours précédents", "Load previous turns")}
</Button>
)}
</div>
) : (
vm.turns.map((turn) => {
const side = sideOf(turn.source);
const sideClass = side === "right" ? "items-end" : "items-start";
if (turn.role === "toolActivity") {
return (
<ToolTurn key={turn.id} turn={turn} sideClass={sideClass} />
);
}
const party = parties.meta.get(partyKey(turn.source));
return (
<div key={turn.id} className={cn("flex flex-col", sideClass)}>
<div
className={cn(
"max-w-[80%] rounded-lg border px-3 py-2 text-sm",
side === "right"
? "border-primary/20 bg-primary/10 text-content"
: "border-border bg-raised text-content",
)}
</div>
)}
{vm.busy && vm.turns.length === 0 ? (
<div className="flex items-center gap-2 text-sm text-muted">
<Spinner size={14} />
<span>{tr("Chargement du fil…", "Loading thread…")}</span>
</div>
) : vm.turns.length === 0 ? (
<div className="max-w-xl text-sm text-muted">
<p>{emptyState.message}</p>
{emptyState.detail && (
<p className="mt-1 text-xs text-faint">{emptyState.detail}</p>
)}
{emptyState.action && onOpenConversation && (
<Button
size="sm"
variant="ghost"
className="mt-2"
onClick={() =>
onOpenConversation(emptyState.action!.conversationId)
}
>
<div className="mb-1 flex items-baseline gap-2 text-xs text-muted">
<span className="font-medium text-content">
{party?.label ?? "?"}
</span>
<span>· {roleLabel(turn.role, tr)}</span>
<EntryTimestamp atMs={turn.atMs} />
{emptyState.action.label}
</Button>
)}
</div>
) : (
vm.turns.map((turn) => {
const side = sideOf(turn.source);
const sideClass = side === "right" ? "items-end" : "items-start";
if (turn.role === "toolActivity") {
return (
<ToolTurn key={turn.id} turn={turn} sideClass={sideClass} />
);
}
const party = parties.meta.get(partyKey(turn.source));
return (
<div key={turn.id} className={cn("flex flex-col", sideClass)}>
<div
className={cn(
"max-w-[80%] rounded-lg border px-3 py-2 text-sm",
side === "right"
? "border-primary/20 bg-primary/10 text-content"
: "border-border bg-raised text-content",
)}
>
<div className="mb-1 flex items-baseline gap-2 text-xs text-muted">
<span className="font-medium text-content">
{party?.label ?? "?"}
</span>
<span>· {roleLabel(turn.role, tr)}</span>
<EntryTimestamp atMs={turn.atMs} />
</div>
<p className="whitespace-pre-wrap break-words">{turn.text}</p>
</div>
<p className="whitespace-pre-wrap break-words">{turn.text}</p>
</div>
</div>
);
})
);
})
)}
</div>
{threadScroll.notice && (
<button
type="button"
className="absolute bottom-3 left-1/2 -translate-x-1/2 rounded-full border border-border bg-raised/95 px-3 py-1 text-xs text-content shadow-md hover:border-border-strong"
onClick={() => threadScroll.scrollToBottom()}
>
{threadScroll.notice === "new"
? tr("Nouveaux messages ↓", "New messages ↓")
: tr("Revenir en bas ↓", "Back to bottom ↓")}
</button>
)}
</div>
</div>

93
frontend/src/features/tickets/TicketAssistantPanel.tsx
View File

@ -8,9 +8,9 @@
* all session/streaming logic lives in the hook.
*/
import { useEffect, useRef, useState } from "react";
import { useState } from "react";
import { Button, Spinner, cn } from "@/shared";
import { Button, Spinner, cn, useThreadScrollController } from "@/shared";
import { useI18n } from "@/i18n";
import { TicketViewportSelect } from "./TicketViewportSelect";
import { useTicketAssistant } from "./useTicketAssistant";
@ -29,18 +29,22 @@ export function TicketAssistantPanel({
const [profileId, setProfileId] = useState("");
const [draft, setDraft] = useState("");
// Auto-scroll the transcript to the newest content as it streams in.
const scrollRef = useRef<HTMLDivElement>(null);
useEffect(() => {
const el = scrollRef.current;
if (el) el.scrollTop = el.scrollHeight;
}, [vm.turns]);
const threadScroll = useThreadScrollController({
itemCount: vm.turns.length,
completedItemCount: vm.turns.filter(
(turn) => turn.role === "assistant" && !turn.pending,
).length,
contentVersion: vm.turns
.map((turn) => `${turn.role}:${turn.text.length}:${Boolean(turn.pending)}`)
.join("|"),
});
const open = vm.sessionId !== null;
function submit() {
const text = draft.trim();
if (!text || vm.busy) return;
threadScroll.followLatest();
void vm.send(text);
setDraft("");
}
@ -95,40 +99,55 @@ export function TicketAssistantPanel({
</Button>
</div>
<div
ref={scrollRef}
className="flex max-h-96 min-h-32 flex-col gap-2 overflow-auto rounded-md border border-border bg-raised/40 p-3"
>
{vm.turns.length === 0 ? (
<p className="m-auto text-xs text-muted">
{tr("Démarrez la conversation en décrivant ce que l'assistant doit faire sur ce ticket.", "Start the conversation by describing what the assistant should do with this ticket.")}
</p>
) : (
vm.turns.map((turn, i) => (
<div
key={i}
className={cn(
"flex",
turn.role === "user" ? "justify-end" : "justify-start",
)}
>
<div className="relative">
<div
ref={threadScroll.scrollRef}
data-testid="ticket-assistant-scroll"
className="flex max-h-96 min-h-32 flex-col gap-2 overflow-auto rounded-md border border-border bg-raised/40 p-3"
onScroll={threadScroll.onScroll}
>
{vm.turns.length === 0 ? (
<p className="m-auto text-xs text-muted">
{tr("Démarrez la conversation en décrivant ce que l'assistant doit faire sur ce ticket.", "Start the conversation by describing what the assistant should do with this ticket.")}
</p>
) : (
vm.turns.map((turn, i) => (
<div
key={i}
className={cn(
"max-w-[85%] whitespace-pre-wrap break-words rounded-lg px-3 py-2 text-sm",
turn.role === "user"
? "bg-primary/15 text-content"
: "bg-surface text-content",
"flex",
turn.role === "user" ? "justify-end" : "justify-start",
)}
>
{turn.text}
{turn.pending && (
<span className="ml-1 inline-flex items-center align-middle text-muted">
<Spinner size={12} />
</span>
)}
<div
className={cn(
"max-w-[85%] whitespace-pre-wrap break-words rounded-lg px-3 py-2 text-sm",
turn.role === "user"
? "bg-primary/15 text-content"
: "bg-surface text-content",
)}
>
{turn.text}
{turn.pending && (
<span className="ml-1 inline-flex items-center align-middle text-muted">
<Spinner size={12} />
</span>
)}
</div>
</div>
</div>
))
))
)}
</div>
{threadScroll.notice && (
<button
type="button"
className="absolute bottom-2 left-1/2 -translate-x-1/2 rounded-full border border-border bg-raised/95 px-3 py-1 text-xs text-content shadow-md hover:border-border-strong"
onClick={() => threadScroll.scrollToBottom()}
>
{threadScroll.notice === "new"
? tr("Nouveaux messages ↓", "New messages ↓")
: tr("Revenir en bas ↓", "Back to bottom ↓")}
</button>
)}
</div>

5
frontend/src/shared/index.ts
View File

@ -7,6 +7,11 @@
export { cn } from "./lib/cn";
export type { ClassValue } from "./lib/cn";
export { useThreadScrollController } from "./lib/useThreadScrollController";
export type {
ThreadScrollController,
ThreadScrollNotice,
} from "./lib/useThreadScrollController";
export { Button } from "./ui/Button";
export type { ButtonProps, ButtonVariant, ButtonSize } from "./ui/Button";

148
frontend/src/shared/lib/useThreadScrollController.test.tsx Normal file
View File

@ -0,0 +1,148 @@
import { fireEvent, render, screen, waitFor } from "@testing-library/react";
import { useState } from "react";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { useThreadScrollController } from "./useThreadScrollController";
function setMetrics(
element: HTMLElement,
metrics: { scrollHeight: number; clientHeight: number; scrollTop: number },
) {
Object.defineProperty(element, "scrollHeight", {
configurable: true,
value: metrics.scrollHeight,
});
Object.defineProperty(element, "clientHeight", {
configurable: true,
value: metrics.clientHeight,
});
element.scrollTop = metrics.scrollTop;
}
function Harness() {
const [items, setItems] = useState(1);
const [completed, setCompleted] = useState(1);
const [version, setVersion] = useState(1);
const scroll = useThreadScrollController({
itemCount: items,
completedItemCount: completed,
contentVersion: version,
});
return (
<>
<div ref={scroll.scrollRef} data-testid="scroll" onScroll={scroll.onScroll}>
<div>content</div>
</div>
<span data-testid="notice">{scroll.notice ?? "none"}</span>
<button onClick={() => setVersion((value) => value + 1)}>stream</button>
<button
onClick={() => {
setItems((value) => value + 1);
setCompleted((value) => value + 1);
setVersion((value) => value + 1);
}}
>
complete
</button>
<button onClick={scroll.followLatest}>send</button>
<button onClick={() => scroll.scrollToBottom("auto")}>bottom</button>
<button
onClick={() =>
void scroll.preserveAnchor(() => {
const element = scroll.scrollRef.current!;
Object.defineProperty(element, "scrollHeight", {
configurable: true,
value: 1200,
});
})
}
>
prepend
</button>
</>
);
}
describe("useThreadScrollController", () => {
let resize: ResizeObserverCallback;
beforeEach(() => {
vi.stubGlobal("requestAnimationFrame", (callback: FrameRequestCallback) => {
callback(0);
return 1;
});
vi.stubGlobal(
"ResizeObserver",
class {
constructor(callback: ResizeObserverCallback) {
resize = callback;
}
observe() {}
disconnect() {}
},
);
});
afterEach(() => vi.unstubAllGlobals());
it("does not move historical reading and distinguishes growth from a completed message", () => {
render(<Harness />);
const element = screen.getByTestId("scroll");
setMetrics(element, { scrollHeight: 1000, clientHeight: 300, scrollTop: 400 });
fireEvent.scroll(element);
fireEvent.click(screen.getByText("stream"));
expect(element.scrollTop).toBe(400);
expect(screen.getByTestId("notice").textContent).toBe("growth");
fireEvent.click(screen.getByText("complete"));
expect(element.scrollTop).toBe(400);
expect(screen.getByTestId("notice").textContent).toBe("new");
});
it("reactivates follow mode on send and on a manual return to bottom", () => {
render(<Harness />);
const element = screen.getByTestId("scroll");
setMetrics(element, { scrollHeight: 1000, clientHeight: 300, scrollTop: 400 });
fireEvent.scroll(element);
fireEvent.click(screen.getByText("send"));
expect(element.scrollTop).toBe(1000);
expect(screen.getByTestId("notice").textContent).toBe("none");
element.scrollTop = 400;
fireEvent.scroll(element);
const scrollTo = vi.fn();
Object.defineProperty(element, "scrollTo", { configurable: true, value: scrollTo });
fireEvent.click(screen.getByText("bottom"));
expect(scrollTo).toHaveBeenCalledWith({ top: 1000, behavior: "auto" });
expect(screen.getByTestId("notice").textContent).toBe("none");
});
it("follows near the bottom across late resizes but leaves history fixed", () => {
render(<Harness />);
const element = screen.getByTestId("scroll");
setMetrics(element, { scrollHeight: 1000, clientHeight: 300, scrollTop: 680 });
fireEvent.scroll(element);
Object.defineProperty(element, "scrollHeight", { configurable: true, value: 1100 });
resize([], {} as ResizeObserver);
expect(element.scrollTop).toBe(1100);
element.scrollTop = 400;
fireEvent.scroll(element);
Object.defineProperty(element, "scrollHeight", { configurable: true, value: 1200 });
resize([], {} as ResizeObserver);
expect(element.scrollTop).toBe(400);
});
it("preserves the visible anchor when older content is prepended", async () => {
render(<Harness />);
const element = screen.getByTestId("scroll");
setMetrics(element, { scrollHeight: 1000, clientHeight: 300, scrollTop: 100 });
fireEvent.scroll(element);
fireEvent.click(screen.getByText("prepend"));
await waitFor(() => expect(element.scrollTop).toBe(300));
expect(screen.getByTestId("notice").textContent).toBe("none");
});
});

171
frontend/src/shared/lib/useThreadScrollController.ts Normal file
View File

@ -0,0 +1,171 @@
import {
useCallback,
useLayoutEffect,
useRef,
useState,
type RefObject,
} from "react";
export type ThreadScrollNotice = "new" | "growth" | null;
export interface ThreadScrollController {
scrollRef: RefObject<HTMLDivElement>;
notice: ThreadScrollNotice;
onScroll: () => void;
scrollToBottom: (behavior?: ScrollBehavior) => void;
followLatest: () => void;
readHistory: () => void;
preserveAnchor: (mutation: () => void | Promise<void>) => Promise<void>;
}
interface ThreadScrollOptions {
itemCount: number;
completedItemCount: number;
contentVersion: string | number;
bottomThreshold?: number;
}
function nextFrame(callback: FrameRequestCallback): number {
if (typeof requestAnimationFrame === "function") {
return requestAnimationFrame(callback);
}
return window.setTimeout(() => callback(performance.now()), 0);
}
/**
* Owns the local follow/history state of one message viewport.
*
* Content mutations and late layout changes only pin the viewport while follow
* mode is active. Prepending can be wrapped with `preserveAnchor` so the same
* visible content remains under the reader's eyes.
*/
export function useThreadScrollController({
itemCount,
completedItemCount,
contentVersion,
bottomThreshold = 32,
}: ThreadScrollOptions): ThreadScrollController {
const scrollRef = useRef<HTMLDivElement>(null);
const followsLatestRef = useRef(true);
const preservingRef = useRef(false);
const previousRef = useRef<{
itemCount: number;
completedItemCount: number;
contentVersion: string | number;
} | null>(null);
const [notice, setNotice] = useState<ThreadScrollNotice>(null);
const pinToBottom = useCallback(() => {
const element = scrollRef.current;
if (element) element.scrollTop = element.scrollHeight;
}, []);
const onScroll = useCallback(() => {
const element = scrollRef.current;
if (!element || preservingRef.current) return;
const atBottom =
element.scrollHeight - element.scrollTop - element.clientHeight <=
bottomThreshold;
followsLatestRef.current = atBottom;
if (atBottom) setNotice(null);
}, [bottomThreshold]);
const scrollToBottom = useCallback(
(behavior: ScrollBehavior = "smooth") => {
const element = scrollRef.current;
followsLatestRef.current = true;
setNotice(null);
if (!element) return;
if (element.scrollTo) {
element.scrollTo({ top: element.scrollHeight, behavior });
} else {
element.scrollTop = element.scrollHeight;
}
},
[],
);
const followLatest = useCallback(() => {
followsLatestRef.current = true;
setNotice(null);
pinToBottom();
nextFrame(pinToBottom);
}, [pinToBottom]);
const preserveAnchor = useCallback(
async (mutation: () => void | Promise<void>) => {
const element = scrollRef.current;
if (!element) {
await mutation();
return;
}
const height = element.scrollHeight;
const top = element.scrollTop;
const wasFollowing = followsLatestRef.current;
preservingRef.current = true;
try {
await mutation();
} finally {
nextFrame(() => {
nextFrame(() => {
element.scrollTop = top + (element.scrollHeight - height);
followsLatestRef.current = wasFollowing;
preservingRef.current = false;
});
});
}
},
[],
);
useLayoutEffect(() => {
const previous = previousRef.current;
previousRef.current = { itemCount, completedItemCount, contentVersion };
if (
!previous ||
(previous.itemCount === itemCount &&
previous.completedItemCount === completedItemCount &&
previous.contentVersion === contentVersion) ||
preservingRef.current
) {
return;
}
if (followsLatestRef.current) {
pinToBottom();
nextFrame(pinToBottom);
setNotice(null);
return;
}
setNotice((current) =>
completedItemCount > previous.completedItemCount || current === "new"
? "new"
: "growth",
);
}, [completedItemCount, contentVersion, itemCount, pinToBottom]);
useLayoutEffect(() => {
const element = scrollRef.current;
if (!element || typeof ResizeObserver === "undefined") return;
const observer = new ResizeObserver(() => {
if (followsLatestRef.current && !preservingRef.current) pinToBottom();
});
observer.observe(element);
for (const child of element.children) observer.observe(child);
return () => observer.disconnect();
}, [contentVersion, itemCount, pinToBottom]);
const readHistory = useCallback(() => {
followsLatestRef.current = false;
setNotice((current) => current ?? "growth");
}, []);
return {
scrollRef,
notice,
onScroll,
scrollToBottom,
followLatest,
readHistory,
preserveAnchor,
};
}