@cartbase/storefront 0.19.0 → 0.20.1

package/src/reviews-ui/review-list.tsx

@@ -1,191 +1,193 @@
-"use client"
-
-import { useState } from "react"
-import { ShieldCheck } from "lucide-react"
-import type { PublicReview } from "../api/reviews"
-import { useLocaleArea } from "../locales/context"
-import { defaultReviewsUiLabels, type ReviewsUiLabels } from "./labels"
-import { formatReviewDate, reviewDisplayName } from "./helpers"
-import { lightboxMedia, type LightboxPosition } from "./lightbox-state"
-import { ReviewLightbox } from "./review-lightbox"
-import { StarRow } from "./star-badge"
-
-/**
- * Review cards (masonry) + the review lightbox. Ported from the Alenika PDP
- * reviews section (src/components/product/reviews-list.tsx, the card
- * grid), presentational half: the fetch/sort/paging orchestration lives in
- * `ReviewWidget`. Data: `api/reviews` `PublicReview[]` (hidden media is
- * filtered out server-side, the client just renders what it gets).
- *
- * A click anywhere on a card opens that review in `ReviewLightbox`; a click
- * on one of its photos opens it on that photo.
- *
- * Verified-purchaser badge is unconditional — every Cartbase review comes
- * from a tokenized post-purchase email, so the badge is a tautology of
- * the system, not an opt-in flag.
- *
- * Masonry: CSS multi-column so photo reviews (tall) and text-only reviews
- * (short) pack together without empty gaps; `break-inside-avoid` keeps
- * each card whole. Images-first ordering comes from the API's default
- * sort, so photo cards lead the flow. `layout="list"` (the store's
- * widget_layout setting) renders a single column instead.
- */
-export interface ReviewListProps {
-  reviews: PublicReview[]
-  /** Store display option (`getWidget().options.layout`). Default masonry. */
-  layout?: "masonry" | "list"
-  labels?: Partial<ReviewsUiLabels>
-  className?: string
-}
-
-export function ReviewList({
-  reviews,
-  layout = "masonry",
-  labels,
-  className,
-}: ReviewListProps) {
-  const l = { ...useLocaleArea("reviews", defaultReviewsUiLabels), ...labels }
-  const [open, setOpen] = useState<LightboxPosition | null>(null)
-
-  return (
-    <>
-      <ul
-        className={
-          className ??
-          (layout === "list"
-            ? "columns-1 [column-gap:1rem]"
-            : "columns-1 sm:columns-2 lg:columns-3 xl:columns-4 [column-gap:1rem]")
-        }
-      >
-        {reviews.map((r, index) => {
-          const media = lightboxMedia(r)
-          const hero = media[0]
-          const rest = media.slice(1)
-          return (
-            <li
-              key={r.id}
-              className="relative break-inside-avoid mb-4 rounded-[2px] border border-border bg-background overflow-hidden"
-            >
-              {/* The whole card is the button; the photos sit above it. */}
-              <button
-                type="button"
-                onClick={() => setOpen({ review: index, media: 0 })}
-                aria-label={`${l.openReview}: ${reviewDisplayName(r.customer_name)}`}
-                className="absolute inset-0 z-0 cursor-pointer"
-              />
-
-              {/* Hero media on top */}
-              {hero && (
-                <button
-                  type="button"
-                  onClick={() => setOpen({ review: index, media: 0 })}
-                  aria-label={hero.type === "image" ? l.showPhoto : l.playVideo}
-                  className="relative z-10 block w-full group"
-                >
-                  {hero.type === "image" ? (
-                    <img
-                      src={hero.thumb || hero.url}
-                      alt=""
-                      loading="lazy"
-                      className="block w-full h-auto object-cover transition-transform group-hover:scale-[1.02]"
-                    />
-                  ) : (
-                    <>
-                      {/* `#t=0.001`: iOS Safari paints no first frame from
-                          `preload="metadata"` alone; the seek makes it. */}
-                      <video
-                        src={`${hero.url}#t=0.001`}
-                        muted
-                        playsInline
-                        preload="metadata"
-                        className="block w-full h-auto object-cover bg-black"
-                      />
-                      <span className="absolute inset-0 flex items-center justify-center">
-                        <span className="w-11 h-11 rounded-full bg-background/80 flex items-center justify-center">
-                          <span
-                            aria-hidden
-                            className="w-0 h-0 border-y-[7px] border-y-transparent border-l-[12px] border-l-foreground ml-0.5"
-                          />
-                        </span>
-                      </span>
-                    </>
-                  )}
-                </button>
-              )}
-
-              <div className="p-4 sm:p-5">
-                <StarRow rating={r.rating} />
-
-                <div className="flex items-center flex-wrap gap-x-2 gap-y-0.5 mt-2">
-                  <span className="text-sm font-medium text-foreground">
-                    {reviewDisplayName(r.customer_name)}
-                  </span>
-                  <span
-                    className="inline-flex items-center gap-1 text-xs text-muted-foreground"
-                    title={l.verifiedTitle}
-                  >
-                    <ShieldCheck className="w-3.5 h-3.5" />
-                    {l.verified}
-                  </span>
-                  <span className="text-xs text-muted-foreground ml-auto">
-                    {formatReviewDate(r.created_at, l)}
-                  </span>
-                </div>
-
-                {r.title && (
-                  <h3 className="text-base font-semibold text-foreground leading-snug mt-3">
-                    {r.title}
-                  </h3>
-                )}
-                {r.body && (
-                  <p className="text-sm text-foreground/90 whitespace-pre-wrap leading-relaxed mt-1.5">
-                    {r.body}
-                  </p>
-                )}
-
-                {/* Extra media beyond the hero */}
-                {rest.length > 0 && (
-                  <div className="relative z-10 grid grid-cols-4 gap-2 mt-3">
-                    {rest.map((m, i) => (
-                      <button
-                        key={i}
-                        type="button"
-                        onClick={() => setOpen({ review: index, media: i + 1 })}
-                        aria-label={m.type === "image" ? l.showPhoto : l.playVideo}
-                        className="relative aspect-square rounded-[2px] overflow-hidden bg-muted"
-                      >
-                        {m.type === "image" ? (
-                          <img
-                            src={m.thumb || m.url}
-                            alt=""
-                            loading="lazy"
-                            className="absolute inset-0 w-full h-full object-cover"
-                          />
-                        ) : (
-                          <video
-                            src={`${m.url}#t=0.001`}
-                            muted
-                            playsInline
-                            preload="metadata"
-                            className="absolute inset-0 w-full h-full object-cover bg-black"
-                          />
-                        )}
-                      </button>
-                    ))}
-                  </div>
-                )}
-              </div>
-            </li>
-          )
-        })}
-      </ul>
-
-      <ReviewLightbox
-        reviews={reviews}
-        position={open}
-        onPositionChange={setOpen}
-        labels={labels}
-      />
-    </>
-  )
-}
+"use client"
+
+import { useState } from "react"
+import { CircleCheck } from "lucide-react"
+import type { PublicReview } from "../api/reviews"
+import { useLocaleArea } from "../locales/context"
+import { defaultReviewsUiLabels, type ReviewsUiLabels } from "./labels"
+import { formatReviewDate, reviewDisplayName } from "./helpers"
+import { lightboxMedia, type LightboxPosition } from "./lightbox-state"
+import { ReviewLightbox } from "./review-lightbox"
+import { StarRow } from "./star-badge"
+
+/**
+ * Review cards (masonry) + the review lightbox. Ported from the Alenika PDP
+ * reviews section (src/components/product/reviews-list.tsx, the card
+ * grid), presentational half: the fetch/sort/paging orchestration lives in
+ * `ReviewWidget`. Data: `api/reviews` `PublicReview[]` (hidden media is
+ * filtered out server-side, the client just renders what it gets).
+ *
+ * A card (Loox's, as evoo.bg runs it): the first photo on top at its own
+ * height, then the reviewer with the verified badge, the date, the stars and
+ * the text. A click anywhere on a card opens that review in
+ * `ReviewLightbox`; a click on one of its photos opens it on that photo.
+ *
+ * Verified-purchaser badge is unconditional — every Cartbase review comes
+ * from a tokenized post-purchase email, so the badge is a tautology of
+ * the system, not an opt-in flag.
+ *
+ * Masonry: CSS multi-column so photo reviews (tall) and text-only reviews
+ * (short) pack together without empty gaps; `break-inside-avoid` keeps
+ * each card whole. Images-first ordering comes from the API's default
+ * sort, so photo cards lead the flow. `layout="list"` (the store's
+ * widget_layout setting) renders a single column instead.
+ */
+export interface ReviewListProps {
+  reviews: PublicReview[]
+  /** Store display option (`getWidget().options.layout`). Default masonry. */
+  layout?: "masonry" | "list"
+  /** The date on each card (`getWidget().options.show_date`). Default on. */
+  showDate?: boolean
+  labels?: Partial<ReviewsUiLabels>
+  className?: string
+}
+
+export function ReviewList({
+  reviews,
+  layout = "masonry",
+  showDate = true,
+  labels,
+  className,
+}: ReviewListProps) {
+  const l = { ...useLocaleArea("reviews", defaultReviewsUiLabels), ...labels }
+  const [open, setOpen] = useState<LightboxPosition | null>(null)
+
+  return (
+    <>
+      <ul
+        className={
+          className ??
+          (layout === "list"
+            ? "columns-1 [column-gap:1rem]"
+            : "columns-2 sm:columns-[14rem] [column-gap:1rem]")
+        }
+      >
+        {reviews.map((r, index) => {
+          const media = lightboxMedia(r)
+          const hero = media[0]
+          const rest = media.slice(1)
+          return (
+            <li
+              key={r.id}
+              className="relative mb-4 break-inside-avoid overflow-hidden rounded-lg bg-card shadow-card"
+            >
+              {/* The whole card is the button; the photos sit above it. */}
+              <button
+                type="button"
+                onClick={() => setOpen({ review: index, media: 0 })}
+                aria-label={`${l.openReview}: ${reviewDisplayName(r.customer_name)}`}
+                className="absolute inset-0 z-0 cursor-pointer"
+              />
+
+              {/* Hero media on top */}
+              {hero && (
+                <button
+                  type="button"
+                  onClick={() => setOpen({ review: index, media: 0 })}
+                  aria-label={hero.type === "image" ? l.showPhoto : l.playVideo}
+                  className="relative z-10 block w-full group"
+                >
+                  {hero.type === "image" ? (
+                    <img
+                      src={hero.thumb || hero.url}
+                      alt=""
+                      loading="lazy"
+                      className="block w-full h-auto object-cover transition-transform group-hover:scale-[1.02]"
+                    />
+                  ) : (
+                    <>
+                      {/* `#t=0.001`: iOS Safari paints no first frame from
+                          `preload="metadata"` alone; the seek makes it. */}
+                      <video
+                        src={`${hero.url}#t=0.001`}
+                        muted
+                        playsInline
+                        preload="metadata"
+                        className="block w-full h-auto object-cover bg-black"
+                      />
+                      <span className="absolute inset-0 flex items-center justify-center">
+                        <span className="w-11 h-11 rounded-full bg-background/80 flex items-center justify-center">
+                          <span
+                            aria-hidden
+                            className="w-0 h-0 border-y-[7px] border-y-transparent border-l-[12px] border-l-foreground ml-0.5"
+                          />
+                        </span>
+                      </span>
+                    </>
+                  )}
+                </button>
+              )}
+
+              <div className="p-4">
+                <div className="flex flex-wrap items-center gap-x-2 gap-y-0.5">
+                  <span className="text-body font-semibold text-foreground">
+                    {reviewDisplayName(r.customer_name)}
+                  </span>
+                  <span
+                    className="inline-flex items-center gap-1 text-caption text-foreground"
+                    title={l.verifiedTitle}
+                  >
+                    <CircleCheck aria-hidden className="size-4 fill-foreground text-background" />
+                    {l.verified}
+                  </span>
+                </div>
+                {showDate ? (
+                  <p className="mt-0.5 text-caption text-muted-foreground">
+                    {formatReviewDate(r.created_at, l)}
+                  </p>
+                ) : null}
+                <StarRow rating={r.rating} size="md" className="mt-2" />
+
+                {r.title && (
+                  <h3 className="mt-2 text-h6 text-foreground">{r.title}</h3>
+                )}
+                {r.body && (
+                  <p className="mt-2 whitespace-pre-wrap text-body text-foreground">{r.body}</p>
+                )}
+
+                {/* Extra media beyond the hero */}
+                {rest.length > 0 && (
+                  <div className="relative z-10 mt-3 grid grid-cols-4 gap-2">
+                    {rest.map((m, i) => (
+                      <button
+                        key={i}
+                        type="button"
+                        onClick={() => setOpen({ review: index, media: i + 1 })}
+                        aria-label={m.type === "image" ? l.showPhoto : l.playVideo}
+                        className="relative aspect-square overflow-hidden rounded-md bg-muted"
+                      >
+                        {m.type === "image" ? (
+                          <img
+                            src={m.thumb || m.url}
+                            alt=""
+                            loading="lazy"
+                            className="absolute inset-0 w-full h-full object-cover"
+                          />
+                        ) : (
+                          <video
+                            src={`${m.url}#t=0.001`}
+                            muted
+                            playsInline
+                            preload="metadata"
+                            className="absolute inset-0 w-full h-full object-cover bg-black"
+                          />
+                        )}
+                      </button>
+                    ))}
+                  </div>
+                )}
+              </div>
+            </li>
+          )
+        })}
+      </ul>
+
+      <ReviewLightbox
+        reviews={reviews}
+        position={open}
+        onPositionChange={setOpen}
+        labels={labels}
+      />
+    </>
+  )
+}

package/src/reviews-ui/review-widget.tsx

@@ -1,6 +1,6 @@
 "use client"
 
-import { useCallback, useEffect, useState } from "react"
+import { useCallback, useEffect, useRef, useState } from "react"
 import type { StorefrontClient } from "../api/http"
 import {
   getWidget,
@@ -12,32 +12,35 @@ import { cn } from "../lib/utils"
 import { useLocaleArea } from "../locales/context"
 import { defaultReviewsUiLabels, type ReviewsUiLabels } from "./labels"
 import { sortParamsFor, type ReviewSortKey } from "./helpers"
-import { RatingDistribution, StarBadge } from "./star-badge"
+import { ReviewSummaryHeader } from "./review-header"
 import { ReviewList } from "./review-list"
+import { reviewWidgetOptions } from "./widget-options"
 
 /**
- * PDP reviews widget: aggregate header (score + distribution + sort) +
- * masonry card list + load-more. Ported from the Alenika PDP section
+ * The product reviews widget, the reviews app's grid for the bottom of a
+ * product page (Loox's Reviews Widget): a header, the review cards, photo
+ * reviews first, and "Show more reviews" under them; a card opens its
+ * review in the lightbox. Ported from the Alenika PDP section
  * (src/components/product/reviews-list.tsx) with the Cartbase data seam:
  *
  *  - Bootstrap is ONE call — `api/reviews.getWidget(client, productId)`
- *    (aggregate + first page sized/sorted per the store's Settings →
- *    Reviews display options; edge-cached 60s). Server-fetch it and pass
- *    `initialData` (recommended — no client waterfall, mirrors the
- *    production server-fetched first page); when omitted the widget
- *    fetches it on mount.
- *  - Sort changes and load-more re-fetch client-side via `listReviews`
- *    (the API enforces ordering; the client just passes params — the
- *    default sort is with-media-first then newest).
+ *    (aggregate + first page + the store's widget settings; edge-cached).
+ *    Server-fetch it and pass `initialData` (recommended — no client
+ *    waterfall); when omitted the widget fetches it on mount.
+ *  - The store's settings (admin, Reviews, Widgets) arrive in
+ *    `options` and shape it: the header (`minimal`, `compact`,
+ *    `expanded`, and what the minimal one shows), the rating breakdown,
+ *    the sort menu, the date on the cards, masonry or list, and the page
+ *    size. A field an older platform does not send takes Loox's default
+ *    (`reviewWidgetOptions`).
+ *  - Sort changes and "Show more reviews" re-fetch client-side via
+ *    `listReviews` (the API orders; the default sort is photo reviews
+ *    first, then newest).
  *  - Aggregate fallback preserved (production fix): if the aggregate is
  *    missing but reviews loaded, derive avg + distribution from the
  *    loaded page rather than showing a misleading "0.0" next to a filled
  *    star. The whole section renders null only when there are genuinely
  *    zero reviews.
- *
- * Settings that shape it (admin → Settings → Reviews): `widget_layout`
- * (masonry|list), `widget_page_size`, `widget_photo_first` — all arrive
- * via `getWidget().options`; moderation decides what is visible at all.
  */
 export interface ReviewWidgetProps {
   client: StorefrontClient
@@ -58,18 +61,19 @@ export function ReviewWidget({
   // The mounted language, then the store's overrides (2026-09-14): a store
   // that mounts StorefrontLocaleProvider passes nothing here.
   const l = { ...useLocaleArea("reviews", defaultReviewsUiLabels), ...labels }
-  const [data, setData] = useState<ReviewWidgetPayload | null>(
-    initialData ?? null
-  )
-  const [sort, setSort] = useState<ReviewSortKey>("default")
-  const [reviews, setReviews] = useState<PublicReview[]>(
-    initialData?.reviews ?? []
+  const [data, setData] = useState<ReviewWidgetPayload | null>(initialData ?? null)
+  // The first page is photo reviews first unless the store turned that off.
+  const [sort, setSort] = useState<ReviewSortKey>(
+    initialData?.options.photo_first === false ? "date" : "default"
   )
+  const [reviews, setReviews] = useState<PublicReview[]>(initialData?.reviews ?? [])
   const [count, setCount] = useState<number>(initialData?.count ?? 0)
   const [hasMore, setHasMore] = useState<boolean>(initialData?.has_more ?? false)
   const [loading, setLoading] = useState(false)
+  const sortChanged = useRef(false)
 
-  const pageSize = data?.options.page_size ?? 10
+  const options = reviewWidgetOptions(data?.options)
+  const pageSize = options.pageSize
 
   // No server-provided bootstrap → fetch it on mount.
   useEffect(() => {
@@ -83,6 +87,7 @@ export function ReviewWidget({
         setReviews(payload.reviews)
         setCount(payload.count)
         setHasMore(payload.has_more)
+        if (payload.options.photo_first === false) setSort("date")
       } catch {
         /* widget is decorative — a failed bootstrap renders nothing */
       }
@@ -93,18 +98,17 @@ export function ReviewWidget({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [client, productId])
 
-  // Re-fetch the first page whenever the sort changes (post-mount only —
-  // the bootstrap page covers sort='default', so no extra round-trip).
+  // Re-fetch the first page when the shopper picks a sort (the bootstrap
+  // page already is the first sort, so the first run is skipped).
   useEffect(() => {
-    if (sort === "default") return
+    if (!sortChanged.current) return
     let cancelled = false
     setLoading(true)
     ;(async () => {
       try {
-        const params = sortParamsFor(sort)
         const res = await listReviews(client, {
           product_id: productId,
-          ...params,
+          ...sortParamsFor(sort),
           limit: pageSize,
           offset: 0,
         })
@@ -122,13 +126,17 @@ export function ReviewWidget({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [sort, productId, pageSize])
 
+  const chooseSort = (next: ReviewSortKey) => {
+    sortChanged.current = true
+    setSort(next)
+  }
+
   const loadMore = useCallback(async () => {
     setLoading(true)
     try {
-      const params = sortParamsFor(sort)
       const res = await listReviews(client, {
         product_id: productId,
-        ...params,
+        ...sortParamsFor(sort),
         limit: pageSize,
         offset: reviews.length,
       })
@@ -146,9 +154,7 @@ export function ReviewWidget({
   const total = aggregate?.count ?? count
   const avg =
     aggregate?.avg_rating ??
-    (reviews.length
-      ? reviews.reduce((s, r) => s + r.rating, 0) / reviews.length
-      : 0)
+    (reviews.length ? reviews.reduce((s, r) => s + r.rating, 0) / reviews.length : 0)
   const distribution =
     aggregate?.distribution ??
     reviews.reduce(
@@ -157,10 +163,7 @@ export function ReviewWidget({
         if (key in d) d[key]++
         return d
       },
-      { "1": 0, "2": 0, "3": 0, "4": 0, "5": 0 } as Record<
-        "1" | "2" | "3" | "4" | "5",
-        number
-      >
+      { "1": 0, "2": 0, "3": 0, "4": 0, "5": 0 } as Record<"1" | "2" | "3" | "4" | "5", number>
     )
 
   if (total === 0) {
@@ -170,41 +173,33 @@ export function ReviewWidget({
   return (
     <section
       id="reviews"
-      className={
-        className ?? "max-w-[1440px] mx-auto px-4 sm:px-6 lg:px-10 my-16 sm:my-24"
-      }
+      className={className ?? "max-w-[1440px] mx-auto px-4 sm:px-6 lg:px-10 my-16 sm:my-24"}
     >
-      <header className="mb-10">
-        <h2 className="text-2xl sm:text-3xl font-semibold text-foreground mb-6">
-          {l.sectionTitle}
-        </h2>
-
-        <div className="flex flex-col md:flex-row md:items-center gap-6 md:gap-12">
-          <StarBadge
-            aggregate={{ count: total, avg_rating: avg }}
-            labels={l}
-          />
-
-          <RatingDistribution distribution={distribution} total={total} />
-
-          <select
-            value={sort}
-            onChange={(e) => setSort(e.target.value as ReviewSortKey)}
-            aria-label={l.sortAria}
-            className="md:ml-auto md:self-start px-3 py-2 rounded-[2px] border border-border bg-background text-sm focus:outline-none focus:ring-2 focus:ring-primary/30"
-          >
-            <option value="default">{l.sortDefault}</option>
-            <option value="date">{l.sortNewest}</option>
-            <option value="rating-desc">{l.sortRatingDesc}</option>
-            <option value="rating-asc">{l.sortRatingAsc}</option>
-          </select>
-        </div>
-      </header>
+      <ReviewSummaryHeader
+        layout={options.header}
+        content={options.headerContent}
+        total={total}
+        average={avg}
+        distribution={distribution}
+        showDistribution={options.showDistribution}
+        showSort={options.showSort}
+        sort={sort}
+        onSortChange={chooseSort}
+        labels={l}
+      />
 
       <ReviewList
         reviews={reviews}
-        layout={data?.options.layout ?? "masonry"}
+        layout={options.layout}
+        showDate={options.showDate}
         labels={l}
+        className={cn(
+          options.layout === "list"
+            ? "columns-1 [column-gap:1rem]"
+            : // Two on a phone, then as many ~14rem columns as the page is wide.
+              "columns-2 sm:columns-[14rem] [column-gap:1rem]",
+          loading && "opacity-60 transition-opacity"
+        )}
       />
 
       {hasMore && (
@@ -213,10 +208,7 @@ export function ReviewWidget({
             type="button"
             onClick={loadMore}
             disabled={loading}
-            className={cn(
-              "inline-flex items-center justify-center px-6 py-2.5 rounded-[2px] border border-border text-sm font-medium transition-colors",
-              loading ? "opacity-50 cursor-not-allowed" : "hover:bg-muted"
-            )}
+            className="inline-flex items-center justify-center rounded-md border border-border bg-background px-4 py-2 text-body-small text-foreground transition-colors hover:bg-muted disabled:cursor-not-allowed disabled:opacity-50"
           >
             {loading ? l.loading : l.loadMore}
           </button>