feat: optimistic updates

Author: ncarazon

front_end/src/app/(main)/questions/[id]/components/key_factors/item_view/key_factor_strength_item.tsx

@@ -20,6 +20,7 @@ import cn from "@/utils/core/cn";
 import { KeyFactorImpactDirectionLabel } from "../item_creation/driver/impact_direction_label";
 import { convertNumericImpactToDirectionCategory } from "../utils";
 import ThumbVoteButtons, { ThumbVoteSelection } from "./thumb_vote_buttons";
+import { useOptimisticVote } from "./use_optimistic_vote";
 
 type Props = PropsWithChildren<{
   keyFactor: KeyFactor;
@@ -70,14 +71,21 @@ const KeyFactorStrengthItem: FC<Props> = ({
 
   const isCompactConsumer = mode === "consumer" && isCompact;
 
-  const userVote = aggregate?.user_vote ?? null;
-  const { upCount, downCount } = useMemo(() => {
-    const arr = aggregate?.aggregated_data ?? [];
-    return {
-      upCount: arr.find((a) => a.score === upScore)?.count ?? 0,
-      downCount: arr.find((a) => a.score === downScore)?.count ?? 0,
-    };
-  }, [aggregate, upScore, downScore]);
+  const aggregatedData = aggregate?.aggregated_data ?? [];
+  const {
+    vote: userVote,
+    upCount,
+    downCount,
+    setOptimistic,
+    clearOptimistic,
+  } = useOptimisticVote({
+    serverVote: aggregate?.user_vote ?? null,
+    serverUpCount: aggregatedData.find((a) => a.score === upScore)?.count ?? 0,
+    serverDownCount:
+      aggregatedData.find((a) => a.score === downScore)?.count ?? 0,
+    upValue: upScore,
+    downValue: downScore,
+  });
 
   const selection: ThumbVoteSelection =
     userVote === upScore ? "up" : userVote === downScore ? "down" : null;
@@ -89,6 +97,7 @@ const KeyFactorStrengthItem: FC<Props> = ({
     }
     if (user.is_bot || submitting) return;
     setSubmitting(true);
+    setOptimistic(next);
 
     try {
       const resp = await voteKeyFactor({
@@ -102,6 +111,7 @@ const KeyFactorStrengthItem: FC<Props> = ({
         setKeyFactorVote(keyFactor.id, updated);
       }
     } finally {
+      clearOptimistic();
       setSubmitting(false);
     }
   };

front_end/src/app/(main)/questions/[id]/components/key_factors/item_view/question_link/question_link_agree_voter.tsx

@@ -21,6 +21,7 @@ import { Question } from "@/types/question";
 import cn from "@/utils/core/cn";
 
 import ThumbVoteButtons, { ThumbVoteSelection } from "../thumb_vote_buttons";
+import { useOptimisticVote } from "../use_optimistic_vote";
 
 type Props = {
   aggregationId?: number;
@@ -70,11 +71,25 @@ const QuestionLinkAgreeVoter: FC<Props> = ({
     return {
       agree: votes?.aggregated_data?.find((x) => x.score === 1)?.count ?? 0,
       disagree: votes?.aggregated_data?.find((x) => x.score === -1)?.count ?? 0,
-      selected: mapUserVoteToSelection(votes?.user_vote),
+      userVote: (votes?.user_vote ?? null) as 1 | -1 | null,
     };
   }, [aggregateCoherenceLinks, aggregationId]);
 
-  const { agree, disagree, selected } = contextVotes;
+  const {
+    vote: currentVote,
+    upCount: agree,
+    downCount: disagree,
+    setOptimistic,
+    clearOptimistic,
+  } = useOptimisticVote<1 | -1 | null>({
+    serverVote: contextVotes.userVote,
+    serverUpCount: contextVotes.agree,
+    serverDownCount: contextVotes.disagree,
+    upValue: 1,
+    downValue: -1,
+  });
+
+  const selected = mapUserVoteToSelection(currentVote);
 
   const { user } = useAuth();
   const [showCopyHint, setShowCopyHint] = useState(false);
@@ -107,6 +122,7 @@ const QuestionLinkAgreeVoter: FC<Props> = ({
       next === "agree" ? 1 : next === "disagree" ? -1 : null;
 
     setSubmitting(true);
+    setOptimistic(vote);
     try {
       const res = await voteAggregateCoherenceLink(aggregationId, vote);
       if ("errors" in res) return;
@@ -121,6 +137,7 @@ const QuestionLinkAgreeVoter: FC<Props> = ({
     } catch (e) {
       console.error("Failed to vote aggregate coherence link", e);
     } finally {
+      clearOptimistic();
       setSubmitting(false);
     }
   };

front_end/src/app/(main)/questions/[id]/components/key_factors/item_view/use_optimistic_vote.ts

@@ -0,0 +1,65 @@
+import { useMemo, useState } from "react";
+
+type OptimisticVoteResult<V extends number | null> = {
+  vote: V | null;
+  upCount: number;
+  downCount: number;
+  setOptimistic: (value: V | null) => void;
+  clearOptimistic: () => void;
+};
+
+/**
+ * Manages optimistic UI updates for up/down vote interactions.
+ * While an API call is in flight, the vote selection and counts
+ * reflect the expected outcome rather than server state.
+ */
+export function useOptimisticVote<V extends number | null>({
+  serverVote,
+  serverUpCount,
+  serverDownCount,
+  upValue,
+  downValue,
+}: {
+  serverVote: V | null;
+  serverUpCount: number;
+  serverDownCount: number;
+  upValue: V;
+  downValue: V;
+}): OptimisticVoteResult<V> {
+  const [optimistic, setOptimisticRaw] = useState<V | null | undefined>(
+    undefined
+  );
+
+  const vote = optimistic !== undefined ? optimistic : serverVote;
+
+  const { upCount, downCount } = useMemo(() => {
+    let up = serverUpCount;
+    let down = serverDownCount;
+
+    if (optimistic !== undefined) {
+      const wasUp = serverVote === upValue;
+      const wasDown = serverVote === downValue;
+      const isUp = optimistic === upValue;
+      const isDown = optimistic === downValue;
+
+      if (wasUp && !isUp) up = Math.max(0, up - 1);
+      if (!wasUp && isUp) up += 1;
+      if (wasDown && !isDown) down = Math.max(0, down - 1);
+      if (!wasDown && isDown) down += 1;
+    }
+
+    return { upCount: up, downCount: down };
+  }, [
+    serverUpCount,
+    serverDownCount,
+    serverVote,
+    upValue,
+    downValue,
+    optimistic,
+  ]);
+
+  const setOptimistic = (value: V | null) => setOptimisticRaw(value);
+  const clearOptimistic = () => setOptimisticRaw(undefined);
+
+  return { vote, upCount, downCount, setOptimistic, clearOptimistic };
+}

front_end/src/app/(main)/questions/[id]/components/key_factors/item_view/vote_panel.tsx

@@ -2,7 +2,7 @@
 
 import { faXmark } from "@fortawesome/free-solid-svg-icons";
 import { FontAwesomeIcon } from "@fortawesome/react-fontawesome";
-import { FC, ReactNode, RefObject, useEffect, useState } from "react";
+import { FC, ReactNode, RefObject, useMemo } from "react";
 import { createPortal } from "react-dom";
 
 import cn from "@/utils/core/cn";
@@ -34,22 +34,18 @@ function VotePanelInner<T extends string>({
   renderLabel,
   footer,
 }: Props<T>) {
-  const [style, setStyle] = useState<React.CSSProperties>({
-    position: "fixed",
-    opacity: 0,
-  });
-
-  useEffect(() => {
-    if (!anchorRef.current) return;
+  const style = useMemo<React.CSSProperties>(() => {
+    if (!anchorRef.current) {
+      return { position: "fixed", opacity: 0 };
+    }
     const rect = anchorRef.current.getBoundingClientRect();
-    setStyle({
+    return {
       position: "fixed",
       top: rect.bottom + 4,
       left: rect.left,
       width: rect.width,
       zIndex: 50,
-      opacity: 1,
-    });
+    };
   }, [anchorRef]);
 
   const panel = (