@cartbase/storefront 0.18.1 → 0.20.0

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

@@ -1,227 +1,218 @@
-"use client"
-
-import { useCallback, useEffect, useState } from "react"
-import type { StorefrontClient } from "../api/http"
-import {
-  getWidget,
-  listReviews,
-  type PublicReview,
-  type ReviewWidgetPayload,
-} from "../api/reviews"
-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 { ReviewList } from "./review-list"
-
-/**
- * PDP reviews widget: aggregate header (score + distribution + sort) +
- * masonry card list + load-more. 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 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
-  productId: string
-  /** Server-fetched `getWidget` payload (recommended). */
-  initialData?: ReviewWidgetPayload | null
-  labels?: Partial<ReviewsUiLabels>
-  className?: string
-}
-
-export function ReviewWidget({
-  client,
-  productId,
-  initialData,
-  labels,
-  className,
-}: ReviewWidgetProps) {
-  // 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 [count, setCount] = useState<number>(initialData?.count ?? 0)
-  const [hasMore, setHasMore] = useState<boolean>(initialData?.has_more ?? false)
-  const [loading, setLoading] = useState(false)
-
-  const pageSize = data?.options.page_size ?? 10
-
-  // No server-provided bootstrap → fetch it on mount.
-  useEffect(() => {
-    if (initialData) return
-    let cancelled = false
-    ;(async () => {
-      try {
-        const payload = await getWidget(client, productId)
-        if (cancelled) return
-        setData(payload)
-        setReviews(payload.reviews)
-        setCount(payload.count)
-        setHasMore(payload.has_more)
-      } catch {
-        /* widget is decorative — a failed bootstrap renders nothing */
-      }
-    })()
-    return () => {
-      cancelled = true
-    }
-    // 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).
-  useEffect(() => {
-    if (sort === "default") return
-    let cancelled = false
-    setLoading(true)
-    ;(async () => {
-      try {
-        const params = sortParamsFor(sort)
-        const res = await listReviews(client, {
-          product_id: productId,
-          ...params,
-          limit: pageSize,
-          offset: 0,
-        })
-        if (cancelled) return
-        setReviews(res.reviews)
-        setCount(res.count)
-        setHasMore(res.has_more)
-      } finally {
-        if (!cancelled) setLoading(false)
-      }
-    })()
-    return () => {
-      cancelled = true
-    }
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [sort, productId, pageSize])
-
-  const loadMore = useCallback(async () => {
-    setLoading(true)
-    try {
-      const params = sortParamsFor(sort)
-      const res = await listReviews(client, {
-        product_id: productId,
-        ...params,
-        limit: pageSize,
-        offset: reviews.length,
-      })
-      setReviews((prev) => [...prev, ...res.reviews])
-      setCount(res.count)
-      setHasMore(res.has_more)
-    } finally {
-      setLoading(false)
-    }
-  }, [client, productId, sort, pageSize, reviews.length])
-
-  // Header summary uses the full aggregate when available; else derive
-  // from the loaded reviews (see the header comment).
-  const aggregate = data?.aggregate ?? null
-  const total = aggregate?.count ?? count
-  const avg =
-    aggregate?.avg_rating ??
-    (reviews.length
-      ? reviews.reduce((s, r) => s + r.rating, 0) / reviews.length
-      : 0)
-  const distribution =
-    aggregate?.distribution ??
-    reviews.reduce(
-      (d, r) => {
-        const key = String(r.rating) as "1" | "2" | "3" | "4" | "5"
-        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
-      >
-    )
-
-  if (total === 0) {
-    return null // Hide the section entirely when there are no reviews
-  }
-
-  return (
-    <section
-      id="reviews"
-      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>
-
-      <ReviewList
-        reviews={reviews}
-        layout={data?.options.layout ?? "masonry"}
-        labels={l}
-      />
-
-      {hasMore && (
-        <div className="mt-8 text-center">
-          <button
-            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"
-            )}
-          >
-            {loading ? l.loading : l.loadMore}
-          </button>
-        </div>
-      )}
-    </section>
-  )
-}
+"use client"
+
+import { useCallback, useEffect, useRef, useState } from "react"
+import type { StorefrontClient } from "../api/http"
+import {
+  getWidget,
+  listReviews,
+  type PublicReview,
+  type ReviewWidgetPayload,
+} from "../api/reviews"
+import { cn } from "../lib/utils"
+import { useLocaleArea } from "../locales/context"
+import { defaultReviewsUiLabels, type ReviewsUiLabels } from "./labels"
+import { sortParamsFor, type ReviewSortKey } from "./helpers"
+import { ReviewSummaryHeader } from "./review-header"
+import { ReviewList } from "./review-list"
+import { reviewWidgetOptions } from "./widget-options"
+
+/**
+ * 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 + 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.
+ */
+export interface ReviewWidgetProps {
+  client: StorefrontClient
+  productId: string
+  /** Server-fetched `getWidget` payload (recommended). */
+  initialData?: ReviewWidgetPayload | null
+  labels?: Partial<ReviewsUiLabels>
+  className?: string
+}
+
+export function ReviewWidget({
+  client,
+  productId,
+  initialData,
+  labels,
+  className,
+}: ReviewWidgetProps) {
+  // 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)
+  // 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 options = reviewWidgetOptions(data?.options)
+  const pageSize = options.pageSize
+
+  // No server-provided bootstrap → fetch it on mount.
+  useEffect(() => {
+    if (initialData) return
+    let cancelled = false
+    ;(async () => {
+      try {
+        const payload = await getWidget(client, productId)
+        if (cancelled) return
+        setData(payload)
+        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 */
+      }
+    })()
+    return () => {
+      cancelled = true
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [client, productId])
+
+  // 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 (!sortChanged.current) return
+    let cancelled = false
+    setLoading(true)
+    ;(async () => {
+      try {
+        const res = await listReviews(client, {
+          product_id: productId,
+          ...sortParamsFor(sort),
+          limit: pageSize,
+          offset: 0,
+        })
+        if (cancelled) return
+        setReviews(res.reviews)
+        setCount(res.count)
+        setHasMore(res.has_more)
+      } finally {
+        if (!cancelled) setLoading(false)
+      }
+    })()
+    return () => {
+      cancelled = true
+    }
+    // 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 res = await listReviews(client, {
+        product_id: productId,
+        ...sortParamsFor(sort),
+        limit: pageSize,
+        offset: reviews.length,
+      })
+      setReviews((prev) => [...prev, ...res.reviews])
+      setCount(res.count)
+      setHasMore(res.has_more)
+    } finally {
+      setLoading(false)
+    }
+  }, [client, productId, sort, pageSize, reviews.length])
+
+  // Header summary uses the full aggregate when available; else derive
+  // from the loaded reviews (see the header comment).
+  const aggregate = data?.aggregate ?? null
+  const total = aggregate?.count ?? count
+  const avg =
+    aggregate?.avg_rating ??
+    (reviews.length ? reviews.reduce((s, r) => s + r.rating, 0) / reviews.length : 0)
+  const distribution =
+    aggregate?.distribution ??
+    reviews.reduce(
+      (d, r) => {
+        const key = String(r.rating) as "1" | "2" | "3" | "4" | "5"
+        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>
+    )
+
+  if (total === 0) {
+    return null // Hide the section entirely when there are no reviews
+  }
+
+  return (
+    <section
+      id="reviews"
+      className={className ?? "max-w-[1440px] mx-auto px-4 sm:px-6 lg:px-10 my-16 sm:my-24"}
+    >
+      <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={options.layout}
+        showDate={options.showDate}
+        labels={l}
+        className={cn(
+          options.layout === "list"
+            ? "columns-1 [column-gap:1rem]"
+            : "columns-1 sm:columns-2 lg:columns-3 xl:columns-4 [column-gap:1rem]",
+          loading && "opacity-60 transition-opacity"
+        )}
+      />
+
+      {hasMore && (
+        <div className="mt-8 text-center">
+          <button
+            type="button"
+            onClick={loadMore}
+            disabled={loading}
+            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>
+        </div>
+      )}
+    </section>
+  )
+}

package/src/reviews-ui/star-badge.tsx

@@ -11,23 +11,35 @@ import { reviewCountLabel } from "./helpers"
  * arrives via props (`api/reviews.getAggregate` / `getWidget().aggregate`).
  */
 
-/** Five-star row, filled to `Math.round(rating)`. */
+const STAR_SIZE = { sm: "size-3.5", md: "size-4.5", lg: "size-5" } as const
+
+/**
+ * Five-star row, filled to `Math.round(rating)` in the theme's `rating`
+ * colour. `md` is a review card's row, `lg` the lightbox's and the header's.
+ */
 export function StarRow({
   rating,
+  size = "sm",
   className,
 }: {
   rating: number
+  size?: keyof typeof STAR_SIZE
   className?: string
 }) {
   return (
-    <span className={cn("inline-flex items-center gap-0.5", className)}>
+    <span
+      role="img"
+      aria-label={`${Math.round(rating)} / 5`}
+      className={cn("inline-flex items-center", size === "sm" ? "gap-0.5" : "gap-px", className)}
+    >
       {Array.from({ length: 5 }).map((_, i) => (
         <Star
           key={i}
+          aria-hidden
           className={cn(
-            "w-3.5 h-3.5",
+            STAR_SIZE[size],
             i < Math.round(rating)
-              ? "fill-warning text-warning"
+              ? "fill-rating text-rating"
               : "fill-muted text-muted-foreground"
           )}
           strokeWidth={0}
@@ -53,7 +65,7 @@ export function StarBadge({ aggregate, labels, className }: StarBadgeProps) {
   if (!aggregate.count) return null
   return (
     <div className={cn("flex items-center gap-3 shrink-0", className)}>
-      <Star className="w-10 h-10 fill-warning text-warning" strokeWidth={0} />
+      <Star className="w-10 h-10 fill-rating text-rating" strokeWidth={0} />
       <div>
         <div className="text-3xl font-bold text-foreground leading-none">
           {aggregate.avg_rating.toFixed(1)}

package/src/reviews-ui/widget-options.ts

@@ -0,0 +1,55 @@
+/**
+ * The reviews widget's display options with every default filled, from the
+ * payload the platform serves (`getWidget().options`) or from nothing. A
+ * platform older than a field leaves it out; the widget then shows what
+ * Loox shows by default. Pure. Unit-tested in
+ * tests/unit/storefront-review-lightbox.test.ts.
+ */
+import type {
+  ReviewWidgetHeader,
+  ReviewWidgetHeaderContent,
+  ReviewWidgetPayload,
+} from "../api/reviews"
+
+export interface ReviewWidgetOptions {
+  layout: "masonry" | "list"
+  pageSize: number
+  header: ReviewWidgetHeader
+  headerContent: ReviewWidgetHeaderContent
+  showDistribution: boolean
+  showSort: boolean
+  showDate: boolean
+}
+
+export const DEFAULT_REVIEW_WIDGET_OPTIONS: ReviewWidgetOptions = {
+  layout: "masonry",
+  pageSize: 10,
+  header: "minimal",
+  headerContent: "count",
+  showDistribution: true,
+  showSort: true,
+  showDate: true,
+}
+
+export function reviewWidgetOptions(
+  options: Partial<ReviewWidgetPayload["options"]> | null | undefined
+): ReviewWidgetOptions {
+  const d = DEFAULT_REVIEW_WIDGET_OPTIONS
+  if (!options) return { ...d }
+  return {
+    layout: options.layout === "list" ? "list" : d.layout,
+    pageSize:
+      typeof options.page_size === "number" && options.page_size > 0
+        ? Math.trunc(options.page_size)
+        : d.pageSize,
+    header:
+      options.header === "compact" || options.header === "expanded" ? options.header : d.header,
+    headerContent:
+      options.header_content === "average" || options.header_content === "stars"
+        ? options.header_content
+        : d.headerContent,
+    showDistribution: options.show_distribution ?? d.showDistribution,
+    showSort: options.show_sort ?? d.showSort,
+    showDate: options.show_date ?? d.showDate,
+  }
+}

package/src/store/pagination.tsx

@@ -6,7 +6,7 @@
  * the server templates read it back and convert to `offset`. Windowed
  * layout: ≤7 pages inline, otherwise ellipsis around the current window.
  */
-import { usePathname, useRouter, useSearchParams } from "next/navigation"
+import { usePathname, useRouter } from "next/navigation"
 import { cn } from "../lib/utils"
 
 export function Pagination({
@@ -20,13 +20,14 @@ export function Pagination({
 }) {
   const router = useRouter()
   const pathname = usePathname()
-  const searchParams = useSearchParams()
 
   const arrayRange = (start: number, stop: number) =>
     Array.from({ length: stop - start + 1 }, (_, index) => start + index)
 
   const handlePageChange = (newPage: number) => {
-    const params = new URLSearchParams(searchParams)
+    // The query as it is at the click: read while rendering, it would make
+    // every listing page request data and stop it from being prerendered.
+    const params = new URLSearchParams(window.location.search)
     params.set("page", newPage.toString())
     router.push(`${pathname}?${params.toString()}`)
   }

package/src/store/sort-select.tsx

@@ -12,7 +12,7 @@
  * from `sortOptionLabelKeys` (labels.ts, pure) so map completeness against
  * `SortOptions` is unit-tested.
  */
-import { usePathname, useRouter, useSearchParams } from "next/navigation"
+import { usePathname, useRouter } from "next/navigation"
 import { useCallback } from "react"
 import { cn } from "../lib/utils"
 import type { SortOptions } from "../lib/sort-products"
@@ -35,20 +35,18 @@ export function SortSelect({
   const l = { ...defaultStoreLabels, ...labels }
   const router = useRouter()
   const pathname = usePathname()
-  const searchParams = useSearchParams()
 
   const sortOptions = (
     Object.keys(sortOptionLabelKeys) as SortOptions[]
   ).map((value) => ({ value, label: l[sortOptionLabelKeys[value]] }))
 
-  const createQueryString = useCallback(
-    (name: string, value: string) => {
-      const params = new URLSearchParams(searchParams)
-      params.set(name, value)
-      return params.toString()
-    },
-    [searchParams]
-  )
+  // The query as it is at the click: read while rendering, it would make
+  // every listing page request data and stop it from being prerendered.
+  const createQueryString = useCallback((name: string, value: string) => {
+    const params = new URLSearchParams(window.location.search)
+    params.set(name, value)
+    return params.toString()
+  }, [])
 
   const handleChange = (value: SortOptions) => {
     const query = createQueryString("sortBy", value)

package/theme/theme.css

@@ -40,6 +40,7 @@
   --color-success-foreground: var(--success-foreground);
   --color-warning: var(--warning);
   --color-warning-foreground: var(--warning-foreground);
+  --color-rating: var(--rating);
 
   --color-border: var(--border);
   --color-input: var(--input);

package/theme/tokens.css

@@ -44,6 +44,9 @@
   --warning: oklch(0.828 0.189 84.429);
   --warning-foreground: oklch(0.279 0.077 45.635);
 
+  /* ── Ratings: the filled review star ──────────────────────────────────── */
+  --rating: oklch(0.828 0.189 84.429);
+
   /* ── Lines and focus ──────────────────────────────────────────────────── */
   --border: oklch(0.922 0 0);
   --input: oklch(0.922 0 0);
@@ -94,6 +97,8 @@
   --warning: oklch(0.828 0.189 84.429);
   --warning-foreground: oklch(0.279 0.077 45.635);
 
+  --rating: oklch(0.828 0.189 84.429);
+
   --border: oklch(1 0 0 / 12%);
   --input: oklch(1 0 0 / 18%);
   --ring: oklch(0.556 0 0);