@86d-app/reviews 0.0.3

package/src/store/components/product-reviews.tsx

@@ -0,0 +1,172 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { useReviewsApi } from "./_hooks";
+import { DistributionBars } from "./distribution-bars";
+import ProductReviewsTemplate from "./product-reviews.mdx";
+import { ReviewCard } from "./review-card";
+import { ReviewForm } from "./review-form";
+import { StarDisplay } from "./star-display";
+
+interface Review {
+	id: string;
+	authorName: string;
+	rating: number;
+	title?: string | undefined;
+	body: string;
+	isVerifiedPurchase: boolean;
+	helpfulCount: number;
+	merchantResponse?: string | undefined;
+	merchantResponseAt?: string | undefined;
+	createdAt: string;
+}
+
+interface RatingSummary {
+	average: number;
+	count: number;
+	distribution: Record<string, number>;
+}
+
+interface ReviewsResponse {
+	reviews: Review[];
+	summary: RatingSummary;
+	total: number;
+}
+
+const PAGE_SIZE = 10;
+
+export function ProductReviews({
+	productId,
+	title = "Customer Reviews",
+}: {
+	productId: string;
+	title?: string | undefined;
+}) {
+	const api = useReviewsApi();
+
+	// Initial page via useQuery — eliminates the fetch-on-mount useEffect
+	const { data: initialData, isLoading: loading } =
+		api.listProductReviews.useQuery({
+			params: { productId },
+			take: String(PAGE_SIZE),
+			skip: "0",
+		}) as { data: ReviewsResponse | undefined; isLoading: boolean };
+
+	// Extra reviews loaded via "Load more"
+	const [extraReviews, setExtraReviews] = useState<Review[]>([]);
+	const [loadingMore, setLoadingMore] = useState(false);
+	const [skip, setSkip] = useState(0);
+	const [loadedAll, setLoadedAll] = useState(false);
+	const [showForm, setShowForm] = useState(false);
+
+	const allReviews = [...(initialData?.reviews ?? []), ...extraReviews];
+	const hasMore =
+		!loadedAll &&
+		initialData !== undefined &&
+		(initialData.reviews.length === PAGE_SIZE || extraReviews.length > 0);
+
+	const handleLoadMore = useCallback(async () => {
+		const nextSkip = skip === 0 ? PAGE_SIZE : skip + PAGE_SIZE;
+		setLoadingMore(true);
+		try {
+			const fresh = (await api.listProductReviews.fetch({
+				params: { productId },
+				take: String(PAGE_SIZE),
+				skip: String(nextSkip),
+			})) as ReviewsResponse;
+			setExtraReviews((prev) => [...prev, ...fresh.reviews]);
+			setSkip(nextSkip);
+			if (fresh.reviews.length < PAGE_SIZE) setLoadedAll(true);
+		} catch {
+			// silently ignore
+		} finally {
+			setLoadingMore(false);
+		}
+	}, [api.listProductReviews, productId, skip]);
+
+	const handleMarkHelpful = useCallback(
+		async (id: string) => {
+			await api.markHelpful.mutate({ params: { id } });
+		},
+		[api.markHelpful],
+	);
+
+	const handleReviewSubmitted = useCallback(() => {
+		setShowForm(false);
+		// Invalidate the query to refetch from scratch
+		void api.listProductReviews.invalidate();
+		setExtraReviews([]);
+		setSkip(0);
+		setLoadedAll(false);
+	}, [api.listProductReviews]);
+
+	if (loading) {
+		return (
+			<section className="py-8">
+				<div className="mb-6 h-7 w-40 animate-pulse rounded-lg bg-muted" />
+				<div className="space-y-4">
+					{[1, 2, 3].map((n) => (
+						<div key={n} className="space-y-2 border-border border-b pb-4">
+							<div className="h-4 w-24 animate-pulse rounded bg-muted" />
+							<div className="h-4 w-full animate-pulse rounded bg-muted" />
+							<div className="h-4 w-3/4 animate-pulse rounded bg-muted" />
+						</div>
+					))}
+				</div>
+			</section>
+		);
+	}
+
+	const summary = initialData?.summary;
+	const noReviews = !summary || summary.count === 0;
+
+	const reviewListContent =
+		allReviews.length === 0 ? (
+			<p className="text-muted-foreground text-sm">No approved reviews yet.</p>
+		) : (
+			<div>
+				{allReviews.map((review) => (
+					<ReviewCard
+						key={review.id}
+						review={review}
+						onMarkHelpful={handleMarkHelpful}
+					/>
+				))}
+				{hasMore && (
+					<button
+						type="button"
+						onClick={() => void handleLoadMore()}
+						disabled={loadingMore}
+						className="mt-4 text-primary text-sm underline-offset-4 hover:underline disabled:opacity-60"
+					>
+						{loadingMore ? "Loading…" : "Load more reviews"}
+					</button>
+				)}
+			</div>
+		);
+
+	return (
+		<ProductReviewsTemplate
+			title={title}
+			summary={summary ?? undefined}
+			noReviews={noReviews}
+			showForm={showForm}
+			onToggleForm={() => setShowForm((v) => !v)}
+			formContent={
+				<ReviewForm productId={productId} onSuccess={handleReviewSubmitted} />
+			}
+			distributionBars={
+				summary ? (
+					<DistributionBars
+						distribution={summary.distribution}
+						total={summary.count}
+					/>
+				) : null
+			}
+			reviewListContent={reviewListContent}
+			starDisplay={
+				summary ? <StarDisplay rating={summary.average} size="lg" /> : null
+			}
+		/>
+	);
+}

package/src/store/components/review-card.mdx

@@ -0,0 +1,32 @@
+<article className="border-border border-b py-5 last:border-0">
+  <div className="mb-2 flex items-start justify-between gap-3">
+    <div>
+      <div className="flex items-center gap-2">
+        {props.starDisplay}
+        {props.review.isVerifiedPurchase && (
+          <span className="rounded-full bg-emerald-50 px-2 py-0.5 text-emerald-700 text-xs dark:bg-emerald-950 dark:text-emerald-300">
+            Verified
+          </span>
+        )}
+      </div>
+      {props.review.title && (
+        <p className="mt-1 font-medium text-foreground text-sm">
+          {props.review.title}
+        </p>
+      )}
+    </div>
+    <span className="shrink-0 text-muted-foreground text-xs">
+      {props.formatDate(props.review.createdAt)}
+    </span>
+  </div>
+  <p className="text-muted-foreground text-sm leading-relaxed">
+    {props.review.body}
+  </p>
+  <div className="mt-2 flex items-center justify-between">
+    <p className="text-muted-foreground/60 text-xs">
+      — {props.review.authorName}
+    </p>
+    {props.helpfulButton}
+  </div>
+  {props.merchantResponseBlock}
+</article>

package/src/store/components/review-card.tsx

@@ -0,0 +1,87 @@
+"use client";
+
+import { useState } from "react";
+import { formatDate } from "./_utils";
+import ReviewCardTemplate from "./review-card.mdx";
+import { StarDisplay } from "./star-display";
+
+interface Review {
+	id: string;
+	authorName: string;
+	rating: number;
+	title?: string | undefined;
+	body: string;
+	isVerifiedPurchase: boolean;
+	helpfulCount: number;
+	merchantResponse?: string | undefined;
+	merchantResponseAt?: string | undefined;
+	createdAt: string;
+}
+
+export function ReviewCard({
+	review,
+	onMarkHelpful,
+}: {
+	review: Review;
+	onMarkHelpful?: ((id: string) => Promise<void>) | undefined;
+}) {
+	const [voted, setVoted] = useState(false);
+	const [localCount, setLocalCount] = useState(review.helpfulCount);
+	const [loading, setLoading] = useState(false);
+
+	const handleHelpful = async () => {
+		if (voted || loading || !onMarkHelpful) return;
+		setLoading(true);
+		try {
+			await onMarkHelpful(review.id);
+			setVoted(true);
+			setLocalCount((c) => c + 1);
+		} catch {
+			// silently ignore
+		} finally {
+			setLoading(false);
+		}
+	};
+
+	const helpfulButton = onMarkHelpful ? (
+		<button
+			type="button"
+			disabled={voted || loading}
+			onClick={() => void handleHelpful()}
+			className={`mt-2 inline-flex items-center gap-1.5 rounded-md border px-2.5 py-1 text-xs transition-colors ${
+				voted
+					? "border-emerald-200 bg-emerald-50 text-emerald-700 dark:border-emerald-800 dark:bg-emerald-950 dark:text-emerald-300"
+					: "border-border text-muted-foreground hover:border-foreground hover:text-foreground"
+			} disabled:opacity-60`}
+		>
+			<span>{voted ? "✓" : "👍"}</span>
+			<span>Helpful{localCount > 0 ? ` (${localCount})` : ""}</span>
+		</button>
+	) : null;
+
+	const merchantResponseBlock = review.merchantResponse ? (
+		<div className="mt-3 rounded-lg border-primary/30 border-l-2 bg-muted/30 py-2 pr-3 pl-3">
+			<p className="mb-0.5 font-medium text-foreground text-xs">
+				Store Response
+			</p>
+			<p className="text-muted-foreground text-sm leading-relaxed">
+				{review.merchantResponse}
+			</p>
+			{review.merchantResponseAt && (
+				<p className="mt-1 text-muted-foreground/60 text-xs">
+					{formatDate(review.merchantResponseAt)}
+				</p>
+			)}
+		</div>
+	) : null;
+
+	return (
+		<ReviewCardTemplate
+			review={review}
+			formatDate={formatDate}
+			starDisplay={<StarDisplay rating={review.rating} size="sm" />}
+			helpfulButton={helpfulButton}
+			merchantResponseBlock={merchantResponseBlock}
+		/>
+	);
+}

package/src/store/components/review-form.mdx

@@ -0,0 +1,111 @@
+{props.success ? (
+  <div className="rounded-xl border border-emerald-200 bg-emerald-50 p-5 text-center dark:border-emerald-800 dark:bg-emerald-950/30">
+    <p className="font-semibold text-emerald-800 dark:text-emerald-200">
+      Thank you for your review!
+    </p>
+    <p className="mt-1 text-emerald-700 text-sm dark:text-emerald-300">
+      Your review will appear once approved.
+    </p>
+  </div>
+) : (
+  <form
+    onSubmit={props.onSubmit}
+    className="space-y-4 rounded-xl border border-border bg-muted/30 p-5"
+  >
+    <div>
+      <p className="mb-1.5 font-medium text-foreground text-sm">
+        Your rating <span className="text-destructive">*</span>
+      </p>
+      {props.starPicker}
+    </div>
+
+    <div className="grid gap-4 sm:grid-cols-2">
+      <div>
+        <label
+          htmlFor="review-name"
+          className="mb-1 block font-medium text-foreground text-sm"
+        >
+          Name <span className="text-destructive">*</span>
+        </label>
+        <input
+          id="review-name"
+          type="text"
+          required
+          maxLength={200}
+          value={props.name}
+          onChange={(e) => props.onNameChange(e.target.value)}
+          placeholder="Your name"
+          className="w-full rounded-lg border border-input bg-background px-3 py-2 text-sm outline-none ring-offset-background focus:ring-2 focus:ring-ring focus:ring-offset-1"
+        />
+      </div>
+      <div>
+        <label
+          htmlFor="review-email"
+          className="mb-1 block font-medium text-foreground text-sm"
+        >
+          Email <span className="text-destructive">*</span>
+        </label>
+        <input
+          id="review-email"
+          type="email"
+          required
+          value={props.email}
+          onChange={(e) => props.onEmailChange(e.target.value)}
+          placeholder="you@example.com"
+          className="w-full rounded-lg border border-input bg-background px-3 py-2 text-sm outline-none ring-offset-background focus:ring-2 focus:ring-ring focus:ring-offset-1"
+        />
+      </div>
+    </div>
+
+    <div>
+      <label
+        htmlFor="review-title"
+        className="mb-1 block font-medium text-foreground text-sm"
+      >
+        Title
+      </label>
+      <input
+        id="review-title"
+        type="text"
+        maxLength={500}
+        value={props.title}
+        onChange={(e) => props.onTitleChange(e.target.value)}
+        placeholder="Summary of your experience"
+        className="w-full rounded-lg border border-input bg-background px-3 py-2 text-sm outline-none ring-offset-background focus:ring-2 focus:ring-ring focus:ring-offset-1"
+      />
+    </div>
+
+    <div>
+      <label
+        htmlFor="review-body"
+        className="mb-1 block font-medium text-foreground text-sm"
+      >
+        Review <span className="text-destructive">*</span>
+      </label>
+      <textarea
+        id="review-body"
+        required
+        maxLength={10000}
+        rows={4}
+        value={props.body}
+        onChange={(e) => props.onBodyChange(e.target.value)}
+        placeholder="Share your experience with this product"
+        className="w-full resize-y rounded-lg border border-input bg-background px-3 py-2 text-sm outline-none ring-offset-background focus:ring-2 focus:ring-ring focus:ring-offset-1"
+      />
+    </div>
+
+    {props.error && (
+      <p className="text-destructive text-sm" role="alert">
+        {props.error}
+      </p>
+    )}
+
+    <button
+      type="submit"
+      disabled={props.isLoading}
+      className="rounded-lg bg-primary px-5 py-2 font-medium text-primary-foreground text-sm transition-opacity disabled:opacity-60"
+    >
+      {props.isLoading ? "Submitting…" : "Submit Review"}
+    </button>
+  </form>
+)}

package/src/store/components/review-form.tsx

@@ -0,0 +1,68 @@
+"use client";
+
+import { useState } from "react";
+import { useReviewsApi } from "./_hooks";
+import { extractError } from "./_utils";
+import ReviewFormTemplate from "./review-form.mdx";
+import { StarPicker } from "./star-picker";
+
+export function ReviewForm({
+	productId,
+	onSuccess,
+}: {
+	productId: string;
+	onSuccess: () => void;
+}) {
+	const api = useReviewsApi();
+	const [rating, setRating] = useState(0);
+	const [name, setName] = useState("");
+	const [email, setEmail] = useState("");
+	const [title, setTitle] = useState("");
+	const [body, setBody] = useState("");
+	const [ratingError, setRatingError] = useState("");
+
+	const submitMutation = api.submitReview.useMutation({
+		onSuccess: () => onSuccess(),
+	});
+
+	const handleSubmit = (e: React.FormEvent) => {
+		e.preventDefault();
+		if (rating === 0) {
+			setRatingError("Please select a rating.");
+			return;
+		}
+		setRatingError("");
+		submitMutation.mutate({
+			productId,
+			authorName: name,
+			authorEmail: email,
+			rating,
+			title: title.trim() || undefined,
+			body,
+		});
+	};
+
+	const error =
+		ratingError ||
+		(submitMutation.isError
+			? extractError(submitMutation.error, "Failed to submit review.")
+			: "");
+
+	return (
+		<ReviewFormTemplate
+			success={submitMutation.isSuccess}
+			name={name}
+			onNameChange={setName}
+			email={email}
+			onEmailChange={setEmail}
+			title={title}
+			onTitleChange={setTitle}
+			body={body}
+			onBodyChange={setBody}
+			onSubmit={handleSubmit}
+			error={error}
+			isLoading={submitMutation.isPending}
+			starPicker={<StarPicker value={rating} onChange={setRating} />}
+		/>
+	);
+}

package/src/store/components/reviews-summary.mdx

@@ -0,0 +1,6 @@
+<div className="flex items-center gap-1.5">
+  {props.starDisplay}
+  <span className="text-muted-foreground text-sm">
+    {props.averageFormatted} · {props.countLabel}
+  </span>
+</div>

package/src/store/components/reviews-summary.tsx

@@ -0,0 +1,30 @@
+"use client";
+
+import { useReviewsApi } from "./_hooks";
+import ReviewsSummaryTemplate from "./reviews-summary.mdx";
+import { StarDisplay } from "./star-display";
+
+interface ReviewsResponse {
+	reviews: unknown[];
+	summary: { average: number; count: number };
+	total: number;
+}
+
+export function ReviewsSummary({ productId }: { productId: string }) {
+	const api = useReviewsApi();
+	const { data } = api.listProductReviews.useQuery({
+		params: { productId },
+		take: "1",
+	}) as { data: ReviewsResponse | undefined };
+
+	const summary = data?.summary;
+	if (!summary || summary.count === 0) return null;
+
+	return (
+		<ReviewsSummaryTemplate
+			starDisplay={<StarDisplay rating={summary.average} size="sm" />}
+			averageFormatted={summary.average.toFixed(1)}
+			countLabel={summary.count === 1 ? "1 review" : `${summary.count} reviews`}
+		/>
+	);
+}

package/src/store/components/star-display.mdx

@@ -0,0 +1,18 @@
+<span
+  role="img"
+  className={props.sizeClass}
+  aria-label={props.ariaLabel}
+>
+  {[1, 2, 3, 4, 5].map((n) => (
+    <span
+      key={n}
+      className={
+        n <= props.filledCount
+          ? "text-amber-400"
+          : "text-gray-200 dark:text-gray-700"
+      }
+    >
+      ★
+    </span>
+  ))}
+</span>

package/src/store/components/star-display.tsx

@@ -0,0 +1,28 @@
+"use client";
+
+import StarDisplayTemplate from "./star-display.mdx";
+
+export function StarDisplay({
+	rating,
+	size = "md",
+}: {
+	rating: number;
+	size?: "sm" | "md" | "lg";
+}) {
+	const sizeClass =
+		size === "sm"
+			? "text-sm select-none leading-none"
+			: size === "lg"
+				? "text-xl select-none leading-none"
+				: "text-base select-none leading-none";
+	const filledCount = Math.round(rating);
+	const ariaLabel = `${rating} out of 5 stars`;
+
+	return (
+		<StarDisplayTemplate
+			sizeClass={sizeClass}
+			ariaLabel={ariaLabel}
+			filledCount={filledCount}
+		/>
+	);
+}

package/src/store/components/star-picker.mdx

@@ -0,0 +1,21 @@
+<fieldset className="flex gap-0.5 border-0 p-0">
+  <legend className="sr-only">Select rating</legend>
+  {[1, 2, 3, 4, 5].map((n) => (
+    <button
+      key={n}
+      type="button"
+      aria-label={n === 1 ? "1 star" : `${n} stars`}
+      aria-pressed={props.value === n}
+      className={`text-2xl leading-none transition-colors ${
+        n <= (props.hover || props.value)
+          ? "text-amber-400"
+          : "text-gray-200 hover:text-amber-200 dark:text-gray-700"
+      }`}
+      onClick={() => props.onChange(n)}
+      onMouseEnter={() => props.onHover(n)}
+      onMouseLeave={() => props.onHover(0)}
+    >
+      ★
+    </button>
+  ))}
+</fieldset>

package/src/store/components/star-picker.tsx

@@ -0,0 +1,23 @@
+"use client";
+
+import { useState } from "react";
+import StarPickerTemplate from "./star-picker.mdx";
+
+export function StarPicker({
+	value,
+	onChange,
+}: {
+	value: number;
+	onChange: (n: number) => void;
+}) {
+	const [hover, setHover] = useState(0);
+
+	return (
+		<StarPickerTemplate
+			value={value}
+			hover={hover}
+			onChange={onChange}
+			onHover={setHover}
+		/>
+	);
+}

package/src/store/endpoints/index.ts

@@ -0,0 +1,11 @@
+import { listMyReviews } from "./list-my-reviews";
+import { listProductReviews } from "./list-product-reviews";
+import { markHelpful } from "./mark-helpful";
+import { submitReview } from "./submit-review";
+
+export const storeEndpoints = {
+	"/reviews": submitReview,
+	"/reviews/me": listMyReviews,
+	"/reviews/products/:productId": listProductReviews,
+	"/reviews/:id/helpful": markHelpful,
+};

package/src/store/endpoints/list-my-reviews.ts

@@ -0,0 +1,38 @@
+import { createStoreEndpoint, z } from "@86d-app/core";
+import type { ReviewController, ReviewStatus } from "../../service";
+
+export const listMyReviews = createStoreEndpoint(
+	"/reviews/me",
+	{
+		method: "GET",
+		query: z.object({
+			page: z.coerce.number().int().positive().optional().default(1),
+			limit: z.coerce.number().int().positive().max(50).optional().default(10),
+			status: z.enum(["pending", "approved", "rejected"]).optional(),
+		}),
+	},
+	async (ctx) => {
+		const userId = ctx.context.session?.user.id;
+		if (!userId) {
+			return { error: "Unauthorized", status: 401 };
+		}
+
+		const { page, limit, status } = ctx.query;
+		const skip = (page - 1) * limit;
+
+		const controller = ctx.context.controllers.review as ReviewController;
+		const { reviews, total } = await controller.listReviewsByCustomer(userId, {
+			status: status as ReviewStatus | undefined,
+			take: limit,
+			skip,
+		});
+
+		return {
+			reviews,
+			total,
+			page,
+			limit,
+			pages: Math.ceil(total / limit),
+		};
+	},
+);

package/src/store/endpoints/list-product-reviews.ts

@@ -0,0 +1,26 @@
+import { createStoreEndpoint, z } from "@86d-app/core";
+import type { ReviewController } from "../../service";
+
+export const listProductReviews = createStoreEndpoint(
+	"/reviews/products/:productId",
+	{
+		method: "GET",
+		params: z.object({ productId: z.string() }),
+		query: z.object({
+			take: z.coerce.number().int().min(1).max(100).optional(),
+			skip: z.coerce.number().int().min(0).optional(),
+		}),
+	},
+	async (ctx) => {
+		const controller = ctx.context.controllers.reviews as ReviewController;
+		const [reviews, summary] = await Promise.all([
+			controller.listReviewsByProduct(ctx.params.productId, {
+				approvedOnly: true,
+				take: ctx.query.take ?? 20,
+				skip: ctx.query.skip ?? 0,
+			}),
+			controller.getProductRatingSummary(ctx.params.productId),
+		]);
+		return { reviews, summary, total: reviews.length };
+	},
+);