feat: Add helpful vote functionality to reviews

Author: ykaydogdu

apps/jobboard-frontend/public/locales/ar/common.json

@@ -1016,6 +1016,13 @@
     "loadMore": "تحميل المزيد",
     "loading": "جارٍ التحميل...",
     "helpful": "مفيد",
+    "toggleHelpful": "وضع علامة مفيد",
+    "helpfulMarked": "تم وضع علامة مفيد",
+    "helpfulMarkedDescription": "تساعد ملاحظاتك الآخرين في العثور على تقييمات مفيدة",
+    "helpfulRemoved": "تمت إزالة علامة مفيد",
+    "helpfulRemovedDescription": "لقد أزلت تصويتك المفيد",
+    "helpfulError": "فشل تحديث التصويت المفيد",
+    "helpfulErrorDescription": "يرجى المحاولة مرة أخرى لاحقًا",
     "report": "إبلاغ",
     "today": "اليوم",
     "yesterday": "أمس",

apps/jobboard-frontend/public/locales/en/common.json

@@ -1522,6 +1522,13 @@
     "loadMore": "Load More Reviews",
     "loading": "Loading...",
     "helpful": "Helpful",
+    "toggleHelpful": "Mark as helpful",
+    "helpfulMarked": "Marked as helpful",
+    "helpfulMarkedDescription": "Your feedback helps others find useful reviews",
+    "helpfulRemoved": "Removed helpful mark",
+    "helpfulRemovedDescription": "You removed your helpful vote",
+    "helpfulError": "Failed to update helpful vote",
+    "helpfulErrorDescription": "Please try again later",
     "report": "Report",
     "today": "today",
     "yesterday": "yesterday",

apps/jobboard-frontend/public/locales/tr/common.json

@@ -1202,6 +1202,13 @@
     "loadMore": "Daha Fazla Yükle",
     "loading": "Yükleniyor...",
     "helpful": "Yararlı",
+    "toggleHelpful": "Yararlı olarak işaretle",
+    "helpfulMarked": "Yararlı olarak işaretlendi",
+    "helpfulMarkedDescription": "Geri bildiriminiz, başkalarının yararlı değerlendirmeler bulmasına yardımcı olur",
+    "helpfulRemoved": "Yararlı işareti kaldırıldı",
+    "helpfulRemovedDescription": "Yararlı oyunuzu kaldırdınız",
+    "helpfulError": "Yararlı oyu güncellenemedi",
+    "helpfulErrorDescription": "Lütfen daha sonra tekrar deneyin",
     "report": "Bildir",
     "today": "bugün",
     "yesterday": "dün",
@@ -1270,4 +1277,4 @@
     "selectConversation": "Bir sohbet seçin",
     "selectConversationDesc": "Sohbet başlatmak için listeden bir konuşma seçin"
   }
-}
+}

apps/jobboard-frontend/src/components/reviews/ReviewCard.tsx

@@ -11,19 +11,50 @@ import { useState } from 'react';
 import { formatDistanceToNow } from 'date-fns';
 import { useReportModal } from '@/hooks/useReportModal';
 import { reportWorkplaceReview } from '@/services/workplace-report.service';
+import { useReviewHelpful } from '@/hooks/useReviewHelpful';
 
 interface ReviewCardProps {
   workplaceId: number;
   review: ReviewResponse;
   canReply?: boolean;
   onUpdate?: () => void;
+  onHelpfulUpdate?: (reviewId: number, newHelpfulCount: number, helpfulByUser?: boolean) => void;
 }
 
-export function ReviewCard({ workplaceId, review, canReply, onUpdate }: ReviewCardProps) {
+export function ReviewCard({
+  workplaceId,
+  review,
+  canReply,
+  onUpdate,
+  onHelpfulUpdate,
+}: ReviewCardProps) {
   const { t } = useTranslation('common');
   const [isReplyDialogOpen, setIsReplyDialogOpen] = useState(false);
   const { openReport, ReportModalElement } = useReportModal();
 
+  // Initialize helpful vote hook
+  const {
+    helpfulCount,
+    userVoted,
+    isLoading: isHelpfulLoading,
+    toggleHelpful,
+    canVote,
+  } = useReviewHelpful({
+    workplaceId,
+    reviewId: review.id,
+    initialHelpfulCount: review.helpfulCount,
+    initialUserVoted: review.helpfulByUser ?? false, // sync initial state from API
+  });
+
+  // Handle helpful count updates
+  const handleHelpfulClick = async () => {
+    const updatedReview = await toggleHelpful();
+    // Notify parent component of helpful count change
+    if (updatedReview) {
+      onHelpfulUpdate?.(review.id, updatedReview.helpfulCount, updatedReview.helpfulByUser);
+    }
+  };
+
   const handleReport = () => {
     openReport({
       title: t('reviews.report'),
@@ -96,9 +127,7 @@ export function ReviewCard({ workplaceId, review, canReply, onUpdate }: ReviewCa
             </div>
 
             {/* Title */}
-            {review.title && (
-              <h5 className="font-medium text-foreground mb-2">{review.title}</h5>
-            )}
+            {review.title && <h5 className="font-medium text-foreground mb-2">{review.title}</h5>}
 
             {/* Content */}
             {review.content && (
@@ -123,12 +152,23 @@ export function ReviewCard({ workplaceId, review, canReply, onUpdate }: ReviewCa
 
             {/* Actions */}
             <div className="flex items-center gap-4 pt-3 border-t">
-              <div className="flex items-center gap-1.5 text-sm text-muted-foreground">
-                <ThumbsUp className="h-4 w-4" />
+              <Button
+                variant="ghost"
+                size="sm"
+                onClick={handleHelpfulClick}
+                disabled={isHelpfulLoading || !canVote}
+                className={`flex items-center gap-1.5 text-sm ${
+                  userVoted
+                    ? 'text-primary hover:text-primary/80'
+                    : 'text-muted-foreground hover:text-foreground'
+                }`}
+                title={canVote ? t('reviews.toggleHelpful') : t('reviews.helpful')}
+              >
+                <ThumbsUp className={`h-4 w-4 ${userVoted ? 'fill-current' : ''}`} />
                 <span>
-                  {t('reviews.helpful')} ({review.helpfulCount})
+                  {t('reviews.helpful')} ({helpfulCount})
                 </span>
-              </div>
+              </Button>
               {canReply && !review.reply && (
                 <Button
                   variant="outline"

apps/jobboard-frontend/src/components/reviews/ReviewList.tsx

@@ -21,6 +21,7 @@ interface ReviewListProps {
   reviewsPerPage?: number;
   actions?: ReactNode;
   onTotalsChange?: (total: number) => void;
+  onReviewUpdate?: (reviewId: number, updates: Partial<ReviewResponse>) => void;
 }
 
 export function ReviewList({
@@ -30,6 +31,7 @@ export function ReviewList({
   reviewsPerPage = 10,
   actions,
   onTotalsChange,
+  onReviewUpdate,
 }: ReviewListProps) {
   const { t } = useTranslation('common');
   const [reviews, setReviews] = useState<ReviewResponse[]>([]);
@@ -74,6 +76,23 @@ export function ReviewList({
     loadReviews(currentPage);
   };
 
+  const handleHelpfulUpdate = (
+    reviewId: number,
+    newHelpfulCount: number,
+    helpfulByUser?: boolean,
+  ) => {
+    // Update the specific review's helpful count and user state in local state
+    setReviews((prevReviews) =>
+      prevReviews.map((review) =>
+        review.id === reviewId
+          ? { ...review, helpfulCount: newHelpfulCount, helpfulByUser }
+          : review,
+      ),
+    );
+    // Notify parent component if needed
+    onReviewUpdate?.(reviewId, { helpfulCount: newHelpfulCount, helpfulByUser });
+  };
+
   // Generate page numbers for pagination (0-indexed to 1-indexed for display)
   const getPageNumbers = () => {
     const pages: (number | 'ellipsis')[] = [];
@@ -144,6 +163,7 @@ export function ReviewList({
                 review={review}
                 canReply={canReply}
                 onUpdate={handleReviewUpdate}
+                onHelpfulUpdate={handleHelpfulUpdate}
               />
             ))}
           </div>
@@ -155,9 +175,7 @@ export function ReviewList({
                   <PaginationPrevious
                     onClick={() => currentPage > 0 && handlePageChange(currentPage - 1)}
                     className={
-                      currentPage === 0
-                        ? 'pointer-events-none opacity-50'
-                        : 'cursor-pointer'
+                      currentPage === 0 ? 'pointer-events-none opacity-50' : 'cursor-pointer'
                     }
                   />
                 </PaginationItem>

apps/jobboard-frontend/src/hooks/useReviewHelpful.ts

@@ -0,0 +1,88 @@
+/**
+ * useReviewHelpful Hook
+ * Manages helpful vote state and operations for reviews
+ */
+
+import { useState, useCallback } from 'react';
+import { markReviewHelpful } from '@/services/reviews.service';
+import type { ReviewResponse } from '@/types/workplace.types';
+import { toast } from 'react-toastify';
+import { useTranslation } from 'react-i18next';
+
+interface UseReviewHelpfulProps {
+  workplaceId: number;
+  reviewId: number;
+  initialHelpfulCount: number;
+  initialUserVoted?: boolean;
+}
+
+interface UseReviewHelpfulReturn {
+  helpfulCount: number;
+  userVoted: boolean;
+  isLoading: boolean;
+  toggleHelpful: () => Promise<ReviewResponse | undefined>;
+  canVote: boolean;
+}
+
+export function useReviewHelpful({
+  workplaceId,
+  reviewId,
+  initialHelpfulCount,
+  initialUserVoted = false,
+}: UseReviewHelpfulProps): UseReviewHelpfulReturn {
+  const [helpfulCount, setHelpfulCount] = useState(initialHelpfulCount);
+  const [userVoted, setUserVoted] = useState(initialUserVoted);
+  const [isLoading, setIsLoading] = useState(false);
+  const { t } = useTranslation('common');
+
+  const canVote = true; // will be enhanced with auth checks when available
+
+  const toggleHelpful = useCallback(async (): Promise<ReviewResponse | undefined> => {
+    if (isLoading || !canVote) return;
+
+    setIsLoading(true);
+
+    // Optimistic update
+    const previousCount = helpfulCount;
+    const previousVoted = userVoted;
+    const optimisticCount = previousVoted ? previousCount - 1 : previousCount + 1;
+
+    setUserVoted(!previousVoted);
+    setHelpfulCount(Math.max(optimisticCount, 0));
+
+    try {
+      // Backend toggles helpful status via single POST endpoint
+      const updatedReview = await markReviewHelpful(workplaceId, reviewId);
+
+      const newUserVoted = !!updatedReview.helpfulByUser;
+      setHelpfulCount(updatedReview.helpfulCount);
+      setUserVoted(newUserVoted);
+
+      toast.success(
+        newUserVoted
+          ? t('reviews.helpfulMarked') || 'Marked as helpful'
+          : t('reviews.helpfulRemoved') || 'Removed helpful mark',
+      );
+
+      return updatedReview;
+    } catch (error) {
+      // Revert optimistic update on error
+      setHelpfulCount(previousCount);
+      setUserVoted(previousVoted);
+
+      console.error('Failed to toggle helpful vote:', error);
+
+      toast.error(t('reviews.helpfulError') || 'Failed to update helpful vote');
+    } finally {
+      setIsLoading(false);
+    }
+  }, [workplaceId, reviewId, helpfulCount, isLoading, canVote, toast, t, userVoted]);
+
+  return {
+    helpfulCount,
+    userVoted,
+    isLoading,
+    toggleHelpful,
+    canVote,
+  };
+}