@cartbase/storefront 0.19.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cartbase/storefront",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Storefront SDK + UI component library for Cartbase stores: typed API client, checkout orchestration, cart drawer, product/catalog components, tracking. Source-shipped TypeScript — add it to transpilePackages.",
   "license": "MIT",
   "repository": {

package/src/api/reviews.ts

@@ -95,6 +95,16 @@ export async function getAggregate(
   return client.get("/api/store/reviews/aggregate", { query: { product_id: productId } })
 }
 
+/**
+ * The widget's header, Loox's three: `minimal` is the stars and one fact
+ * with the breakdown under a chevron, `compact` the average, the stars and
+ * the count on one line, `expanded` the big score with the breakdown open.
+ */
+export type ReviewWidgetHeader = "minimal" | "compact" | "expanded"
+
+/** What the minimal header shows beside its stars. */
+export type ReviewWidgetHeaderContent = "count" | "average" | "stars"
+
 /** Widget payload — aggregate + first page + display options, one call. */
 export interface ReviewWidgetPayload {
   product_id: string
@@ -106,6 +116,15 @@ export interface ReviewWidgetPayload {
     layout: "masonry" | "list"
     page_size: number
     photo_first: boolean
+    /** The fields below arrive from platforms of 2026-09-17 on; the widget defaults each. */
+    header?: ReviewWidgetHeader
+    header_content?: ReviewWidgetHeaderContent
+    /** The 5 to 1 star breakdown. */
+    show_distribution?: boolean
+    /** The shopper's sort menu. */
+    show_sort?: boolean
+    /** The date on each card. */
+    show_date?: boolean
   }
 }
 
@@ -116,7 +135,9 @@ export interface ReviewWidgetPayload {
  *
  * Auth: anon (x-client-id).
  * Errors: 400 validation_failed (missing product_id).
- * Settings: widget_layout / widget_page_size / widget_photo_first.
+ * Settings (admin, Reviews, Widgets): widget_header / widget_header_content /
+ * widget_layout / widget_page_size / widget_photo_first /
+ * widget_show_distribution / widget_show_sort / widget_show_date.
  */
 export async function getWidget(
   client: StorefrontClient,

package/src/locales/bg.ts

@@ -374,14 +374,14 @@ export const bg: StorefrontLocale = {
     sectionTitle: "Отзиви",
     reviewSingular: "отзив",
     reviewPlural: "отзива",
-    sortAria: "Сортирай",
+    sortAria: "Сортирай по",
     sortDefault: "Препоръчани",
     sortNewest: "Най-нови",
     sortRatingDesc: "Най-високи оценки",
     sortRatingAsc: "Най-ниски оценки",
     verified: "Потвърден",
     verifiedTitle: "Истински купувач, потвърден чрез линк от поръчка",
-    loadMore: "Покажи още",
+    loadMore: "Покажи още отзиви",
     loading: "Зарежда...",
     dateToday: "днес",
     dateYesterday: "вчера",
@@ -389,6 +389,7 @@ export const bg: StorefrontLocale = {
     showPhoto: "Покажи снимка",
     playVideo: "Пусни видео",
     close: "Затвори",
+    ratingBreakdown: "Разбивка по оценки",
     openReview: "Отвори отзива",
     verifiedInfo: "Какво значи потвърден",
     storeReply: "Отговор от магазина",

package/src/locales/es.ts

@@ -384,14 +384,14 @@ export const es: StorefrontLocale = {
     sectionTitle: "Valoraciones",
     reviewSingular: "valoración",
     reviewPlural: "valoraciones",
-    sortAria: "Ordenar",
+    sortAria: "Ordenar por",
     sortDefault: "Recomendadas",
     sortNewest: "Más recientes",
     sortRatingDesc: "Mejor valoradas",
     sortRatingAsc: "Peor valoradas",
     verified: "Compra verificada",
     verifiedTitle: "Comprador real, verificado mediante un enlace de pedido",
-    loadMore: "Mostrar más",
+    loadMore: "Mostrar más valoraciones",
     loading: "Cargando...",
     dateToday: "hoy",
     dateYesterday: "ayer",
@@ -399,6 +399,7 @@ export const es: StorefrontLocale = {
     showPhoto: "Ver foto",
     playVideo: "Reproducir vídeo",
     close: "Cerrar",
+    ratingBreakdown: "Desglose de valoraciones",
     openReview: "Abrir la valoración",
     verifiedInfo: "Qué significa compra verificada",
     storeReply: "Respuesta de la tienda",

package/src/reviews-ui/index.ts

@@ -62,6 +62,18 @@ export {
 
 export { ReviewWidget, type ReviewWidgetProps } from "./review-widget"
 
+export {
+  ReviewSummaryHeader,
+  ReviewSortMenu,
+  type ReviewSummaryHeaderProps,
+} from "./review-header"
+
+export {
+  reviewWidgetOptions,
+  DEFAULT_REVIEW_WIDGET_OPTIONS,
+  type ReviewWidgetOptions,
+} from "./widget-options"
+
 export {
   ReviewWizard,
   ReviewWizardForm,

package/src/reviews-ui/labels.ts

@@ -31,6 +31,8 @@ export type ReviewsUiLabels = {
   showPhoto: string
   playVideo: string
   close: string
+  /** The header's chevron that opens the 5 to 1 star breakdown. */
+  ratingBreakdown: string
   // — lightbox —
   /** A review card's own button: the whole card opens the lightbox. */
   openReview: string
@@ -130,14 +132,14 @@ export const defaultReviewsUiLabels: ReviewsUiLabels = {
   sectionTitle: "Reviews",
   reviewSingular: "review",
   reviewPlural: "reviews",
-  sortAria: "Sort",
+  sortAria: "Sort by",
   sortDefault: "Recommended",
   sortNewest: "Newest",
   sortRatingDesc: "Highest rated",
   sortRatingAsc: "Lowest rated",
   verified: "Verified",
   verifiedTitle: "Real buyer, verified via an order link",
-  loadMore: "Show more",
+  loadMore: "Show more reviews",
   loading: "Loading...",
   dateToday: "today",
   dateYesterday: "yesterday",
@@ -145,6 +147,7 @@ export const defaultReviewsUiLabels: ReviewsUiLabels = {
   showPhoto: "View photo",
   playVideo: "Play video",
   close: "Close",
+  ratingBreakdown: "Rating breakdown",
   openReview: "Open the review",
   verifiedInfo: "What verified means",
   storeReply: "Reply from the store",

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

@@ -0,0 +1,166 @@
+"use client"
+
+import { useState } from "react"
+import { Check, ChevronDown, SlidersHorizontal, Star } from "lucide-react"
+import type { ReviewAggregate, ReviewWidgetHeader, ReviewWidgetHeaderContent } from "../api/reviews"
+import { Popover, PopoverContent, PopoverTrigger } from "../primitives/ui/popover"
+import { reviewCountLabel, type ReviewSortKey } from "./helpers"
+import type { ReviewsUiLabels } from "./labels"
+import { RatingDistribution, StarBadge, StarRow } from "./star-badge"
+
+/**
+ * The reviews widget's header, Loox's three layouts:
+ *
+ *  - `minimal`: the stars and one fact beside them (the review count, the
+ *    average, or nothing), the breakdown under a chevron;
+ *  - `compact`: the average, the stars and the count on one line, the
+ *    breakdown under a chevron;
+ *  - `expanded`: the section title, the big score and the breakdown open
+ *    beside it (the Alenika header).
+ *
+ * The sort menu sits on the right in all three. `showDistribution` and
+ * `showSort` switch those parts off.
+ */
+export interface ReviewSummaryHeaderProps {
+  layout: ReviewWidgetHeader
+  content: ReviewWidgetHeaderContent
+  total: number
+  average: number
+  distribution: ReviewAggregate["distribution"]
+  showDistribution: boolean
+  showSort: boolean
+  sort: ReviewSortKey
+  onSortChange: (sort: ReviewSortKey) => void
+  labels: ReviewsUiLabels
+}
+
+export function ReviewSummaryHeader({
+  layout,
+  content,
+  total,
+  average,
+  distribution,
+  showDistribution,
+  showSort,
+  sort,
+  onSortChange,
+  labels: l,
+}: ReviewSummaryHeaderProps) {
+  const count = reviewCountLabel(total, l)
+  const sortMenu = showSort ? <ReviewSortMenu value={sort} onChange={onSortChange} labels={l} /> : null
+
+  if (layout === "expanded") {
+    return (
+      <header className="mb-10">
+        <h2 className="mb-6 text-h4 text-foreground">{l.sectionTitle}</h2>
+        <div className="flex flex-col gap-6 md:flex-row md:items-center md:gap-12">
+          <StarBadge aggregate={{ count: total, avg_rating: average }} labels={l} />
+          {showDistribution ? <RatingDistribution distribution={distribution} total={total} /> : null}
+          {sortMenu ? <div className="md:ml-auto md:self-start">{sortMenu}</div> : null}
+        </div>
+      </header>
+    )
+  }
+
+  const summary =
+    layout === "compact" ? (
+      <>
+        <span className="text-h6 text-foreground tabular-nums">{average.toFixed(1)}</span>
+        <StarRow rating={average} size="lg" />
+        <span className="text-body-small text-foreground">{count}</span>
+      </>
+    ) : (
+      <>
+        <StarRow rating={average} size="lg" />
+        {content === "count" ? <span className="text-body-small text-foreground">{count}</span> : null}
+        {content === "average" ? (
+          <span className="text-body-small font-semibold text-foreground tabular-nums">
+            {average.toFixed(1)}
+          </span>
+        ) : null}
+      </>
+    )
+
+  return (
+    <header className="mb-6 flex items-center justify-between gap-4">
+      {showDistribution ? (
+        <Popover>
+          <PopoverTrigger
+            aria-label={`${l.ratingBreakdown}: ${count}`}
+            className="group flex items-center gap-2 rounded-md text-left"
+          >
+            {summary}
+            <ChevronDown
+              aria-hidden
+              className="size-4 text-foreground transition-transform group-data-[state=open]:rotate-180"
+            />
+          </PopoverTrigger>
+          <PopoverContent align="start" className="w-[min(26rem,calc(100vw-2rem))] p-6">
+            <div className="mb-4 flex items-center justify-center gap-2">
+              <Star aria-hidden className="size-7 fill-rating text-rating" strokeWidth={0} />
+              <span className="text-h3 text-foreground tabular-nums">{average.toFixed(1)}</span>
+            </div>
+            <RatingDistribution distribution={distribution} total={total} className="md:max-w-none" />
+          </PopoverContent>
+        </Popover>
+      ) : (
+        <div className="flex items-center gap-2">{summary}</div>
+      )}
+      {sortMenu}
+    </header>
+  )
+}
+
+const SORT_OPTIONS: Array<{ key: ReviewSortKey; label: keyof ReviewsUiLabels }> = [
+  { key: "default", label: "sortDefault" },
+  { key: "date", label: "sortNewest" },
+  { key: "rating-desc", label: "sortRatingDesc" },
+  { key: "rating-asc", label: "sortRatingAsc" },
+]
+
+/**
+ * The sort menu: an icon button, and under it "Sort by" with the four
+ * orders, the chosen one ticked. Choosing one closes it.
+ */
+export function ReviewSortMenu({
+  value,
+  onChange,
+  labels: l,
+}: {
+  value: ReviewSortKey
+  onChange: (sort: ReviewSortKey) => void
+  labels: ReviewsUiLabels
+}) {
+  const [open, setOpen] = useState(false)
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger
+        aria-label={l.sortAria}
+        className="flex size-9 shrink-0 items-center justify-center rounded-md border border-border bg-background text-foreground transition-colors hover:bg-muted data-[state=open]:bg-muted"
+      >
+        <SlidersHorizontal aria-hidden className="size-4.5" />
+      </PopoverTrigger>
+      <PopoverContent align="end" className="w-64 p-2">
+        <p className="px-3 pb-2 pt-2 text-h6 text-foreground">{l.sortAria}</p>
+        <ul>
+          {SORT_OPTIONS.map((option) => (
+            <li key={option.key}>
+              <button
+                type="button"
+                aria-pressed={value === option.key}
+                onClick={() => {
+                  setOpen(false)
+                  if (option.key !== value) onChange(option.key)
+                }}
+                className="flex w-full items-center justify-between rounded-md px-3 py-2 text-left text-body-small text-foreground transition-colors hover:bg-muted"
+              >
+                {l[option.label]}
+                {value === option.key ? <Check aria-hidden className="size-4" /> : null}
+              </button>
+            </li>
+          ))}
+        </ul>
+      </PopoverContent>
+    </Popover>
+  )
+}

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

@@ -1,7 +1,7 @@
 "use client"
 
 import { useState } from "react"
-import { ShieldCheck } from "lucide-react"
+import { CircleCheck } from "lucide-react"
 import type { PublicReview } from "../api/reviews"
 import { useLocaleArea } from "../locales/context"
 import { defaultReviewsUiLabels, type ReviewsUiLabels } from "./labels"
@@ -17,8 +17,10 @@ import { StarRow } from "./star-badge"
  * `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.
+ * 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
@@ -34,6 +36,8 @@ 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
 }
@@ -41,6 +45,7 @@ export interface ReviewListProps {
 export function ReviewList({
   reviews,
   layout = "masonry",
+  showDate = true,
   labels,
   className,
 }: ReviewListProps) {
@@ -64,7 +69,7 @@ export function ReviewList({
           return (
             <li
               key={r.id}
-              className="relative break-inside-avoid mb-4 rounded-[2px] border border-border bg-background overflow-hidden"
+              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
@@ -113,46 +118,43 @@ export function ReviewList({
                 </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">
+              <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-xs text-muted-foreground"
+                    className="inline-flex items-center gap-1 text-caption text-foreground"
                     title={l.verifiedTitle}
                   >
-                    <ShieldCheck className="w-3.5 h-3.5" />
+                    <CircleCheck aria-hidden className="size-4 fill-foreground text-background" />
                     {l.verified}
                   </span>
-                  <span className="text-xs text-muted-foreground ml-auto">
-                    {formatReviewDate(r.created_at, l)}
-                  </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="text-base font-semibold text-foreground leading-snug mt-3">
-                    {r.title}
-                  </h3>
+                  <h3 className="mt-2 text-h6 text-foreground">{r.title}</h3>
                 )}
                 {r.body && (
-                  <p className="text-sm text-foreground/90 whitespace-pre-wrap leading-relaxed mt-1.5">
-                    {r.body}
-                  </p>
+                  <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 grid grid-cols-4 gap-2 mt-3">
+                  <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 rounded-[2px] overflow-hidden bg-muted"
+                        className="relative aspect-square overflow-hidden rounded-md bg-muted"
                       >
                         {m.type === "image" ? (
                           <img

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,9 +11,11 @@ import { reviewCountLabel } from "./helpers"
  * arrives via props (`api/reviews.getAggregate` / `getWidget().aggregate`).
  */
 
+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. `lg` is the lightbox's row.
+ * colour. `md` is a review card's row, `lg` the lightbox's and the header's.
  */
 export function StarRow({
   rating,
@@ -21,21 +23,21 @@ export function StarRow({
   className,
 }: {
   rating: number
-  size?: "sm" | "lg"
+  size?: keyof typeof STAR_SIZE
   className?: string
 }) {
   return (
     <span
       role="img"
       aria-label={`${Math.round(rating)} / 5`}
-      className={cn("inline-flex items-center", size === "lg" ? "gap-px" : "gap-0.5", className)}
+      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(
-            size === "lg" ? "size-5" : "size-3.5",
+            STAR_SIZE[size],
             i < Math.round(rating)
               ? "fill-rating text-rating"
               : "fill-muted text-muted-foreground"

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,
+  }
+}