@cartbase/storefront 0.18.1 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cartbase/storefront",
-  "version": "0.18.1",
+  "version": "0.19.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/common/cart-button-client.tsx

@@ -18,9 +18,13 @@ import { useCartDrawer } from "../cart-drawer/context"
  * NOTE: depends on the sibling `cart-drawer` family's context (ported in
  * the same batch); mount inside `<CartDrawerProvider>`.
  */
-export function CartButtonClient({ cart }: { cart: Cart | null }) {
-  const { open } = useCartDrawer()
-  const totalItems = productItemCount(cart?.items)
+export function CartButtonClient({ cart }: { cart?: Cart | null }) {
+  const drawer = useCartDrawer()
+  // Leave `cart` out and the badge counts the drawer's own cart, the one
+  // the provider read in the browser, so the header needs no server read
+  // and the page around it can be prerendered.
+  const totalItems = productItemCount((cart === undefined ? drawer.cart : cart)?.items)
+  const { open } = drawer
 
   return (
     <button

package/src/lib/cookie-names.ts

@@ -3,9 +3,10 @@
  * (platform-fingerprints card, fingerprint #4 — cookie names are a
  * primary Wappalyzer/BuiltWith detection signal).
  *
- * The app still OWNS *setting* the cart cookie — carts.md is explicit that
- * "the SDK never persists the cart" — this module is the single source of
- * the NAME so every consumer emits the same wire fingerprint instead of
+ * The app decides WHEN the cart cookie is written (it hands
+ * `writeCartCookie` to the drawer's `onCartChange`); this module is the
+ * single source of the NAME and the shape, so every consumer emits the
+ * same wire fingerprint instead of
  * inventing its own prefix (the reference app previously hardcoded
  * `_barter_cart_id` locally in `examples/storefront/src/lib/config.ts`).
  *
@@ -40,6 +41,39 @@ export function readCartCookie(
   return get(CART_COOKIE) ?? get(LEGACY_CART_COOKIE)
 }
 
+/** How long a stored cart id lives: thirty days. */
+export const CART_COOKIE_MAX_AGE = 60 * 60 * 24 * 30
+
+/**
+ * The stored cart id, read in the browser; null on the server or when none
+ * is stored. A storefront hands it to `CartDrawerProvider` as `cartId`, so
+ * no page reads the cart cookie on the server and every page can be
+ * prerendered (Cache Components).
+ */
+export function readBrowserCartId(): string | null {
+  if (typeof document === "undefined") return null
+  const cookies = new Map(
+    document.cookie
+      .split("; ")
+      .filter(Boolean)
+      .map((row) => {
+        const at = row.indexOf("=")
+        return [row.slice(0, at), decodeURIComponent(row.slice(at + 1))] as const
+      })
+  )
+  return readCartCookie((name) => cookies.get(name) || undefined) ?? null
+}
+
+/**
+ * Store the cart id in the browser, under the current name: what a
+ * storefront hands to `CartDrawerProvider`'s `onCartChange`. A no-op on the
+ * server.
+ */
+export function writeCartCookie(cartId: string): void {
+  if (typeof document === "undefined") return
+  document.cookie = `${CART_COOKIE}=${encodeURIComponent(cartId)};path=/;max-age=${CART_COOKIE_MAX_AGE};samesite=lax`
+}
+
 /**
  * Forget the stored cart in the browser, under both names: Medusa's
  * `removeCartId()`. The package's checkout calls it when the order is

package/src/locales/bg.ts

@@ -389,6 +389,13 @@ export const bg: StorefrontLocale = {
     showPhoto: "Покажи снимка",
     playVideo: "Пусни видео",
     close: "Затвори",
+    openReview: "Отвори отзива",
+    verifiedInfo: "Какво значи потвърден",
+    storeReply: "Отговор от магазина",
+    previous: "Предишен",
+    next: "Следващ",
+    mediaAlt: "Снимка {n} от {total}, {name}",
+    showMediaAt: "Покажи снимка {n}",
     expiredTitle: "Този линк за отзив е изтекъл",
     expiredBody:
       "Линкът беше валиден 60 дни от датата на покупката. Ако искаш да оставиш отзив, пиши ни на {email}.",

package/src/locales/es.ts

@@ -399,6 +399,13 @@ export const es: StorefrontLocale = {
     showPhoto: "Ver foto",
     playVideo: "Reproducir vídeo",
     close: "Cerrar",
+    openReview: "Abrir la valoración",
+    verifiedInfo: "Qué significa compra verificada",
+    storeReply: "Respuesta de la tienda",
+    previous: "Anterior",
+    next: "Siguiente",
+    mediaAlt: "Foto {n} de {total} de {name}",
+    showMediaAt: "Ver foto {n}",
     expiredTitle: "Este enlace de valoración ha caducado",
     expiredBody:
       "El enlace era válido durante 60 días desde tu compra. Si quieres dejar una valoración, escríbenos a {email}.",

package/src/products/product-actions-wrapper.tsx

@@ -23,8 +23,12 @@ type ProductActionsWrapperProps = {
   id: string
   /** Pricing context so `calculated_price` is present for the price panel. */
   pricingContext?: PricingContextQuery
-  /** The variant the address names; see the product page contract. */
-  initialVariantId?: string | null
+  /**
+   * The variant the address names; see the product page contract. A promise
+   * is read here, behind the template's boundary, so a page on Cache
+   * Components never reads its query outside one.
+   */
+  initialVariantId?: string | null | Promise<string | null | undefined>
   /** A server action; leave it out for the instant add through the mounted cart drawer. */
   addToCart?: (input: AddToCartInput) => Promise<void>
   onAddToCart?: (product: StoreProduct, variant: StoreProductVariant) => void
@@ -40,6 +44,9 @@ export async function ProductActionsWrapper({
   onAddToCart,
   openCart,
 }: ProductActionsWrapperProps) {
+  // The address first: it is request data, so the live read never runs
+  // while a build prerenders the page.
+  const variantId = await initialVariantId
   let product: StoreProduct
   try {
     const res = await retrieveProduct(client, id, pricingContext)
@@ -52,7 +59,7 @@ export async function ProductActionsWrapper({
   return (
     <ProductActions
       product={product}
-      initialVariantId={initialVariantId}
+      initialVariantId={variantId}
       addToCart={addToCart}
       onAddToCart={onAddToCart}
       openCart={openCart}

package/src/products/product-template.tsx

@@ -26,6 +26,8 @@ import { RelatedProducts } from "./related-products"
 import { ProductInfo } from "./product-info"
 import { ProductActionsWrapper } from "./product-actions-wrapper"
 
+type VariantParam = string | null | Promise<string | null | undefined>
+
 type ProductTemplateProps = {
   client: StorefrontClient
   product: StoreProduct
@@ -59,11 +61,13 @@ type ProductTemplateProps = {
   /** Anything else the store wants in the accordion, appended in order. */
   sections?: ProductSection[]
   /**
-   * The variant the address names: pass `searchParams.variant` from the
-   * page, so the server renders that variant's price, code and stock and
-   * nothing flashes (the product page contract, `use-product-actions.ts`).
+   * The variant the address names, so the server renders that variant's
+   * price, code and stock and nothing flashes (the product page contract,
+   * `use-product-actions.ts`). On Cache Components pass it as a promise
+   * (`searchParams.then((q) => q.variant)`): the live buy box reads it
+   * behind its boundary and the rest of the page stays prerendered.
    */
-  initialVariantId?: string | null
+  initialVariantId?: VariantParam
   /** The store's own card for the related strip; the library's preview without it. */
   renderProduct?: ComponentType<{ product: StoreProduct }>
 }
@@ -112,7 +116,7 @@ export function ProductTemplate({
               <ProductActions
                 disabled={true}
                 product={product}
-                initialVariantId={initialVariantId}
+                initialVariantId={typeof initialVariantId === "string" ? initialVariantId : null}
                 addToCart={addToCart}
                 onAddToCart={onAddToCart}
                 openCart={openCart}

package/src/products/use-product-actions.ts

@@ -31,7 +31,7 @@
  * to out of stock until the choice changes.
  */
 import { useCallback, useEffect, useMemo, useState } from "react"
-import { usePathname, useRouter, useSearchParams } from "next/navigation"
+import { usePathname, useRouter } from "next/navigation"
 
 import type { StoreProduct, StoreProductVariant } from "../api/products"
 import { useCartDrawer } from "../cart-drawer/context"
@@ -102,7 +102,6 @@ export function useProductActions({
   const router = useRouter()
   const drawer = useCartDrawer()
   const pathname = usePathname()
-  const searchParams = useSearchParams()
   const variants = product.variants ?? []
 
   const [chosen, setChosen] = useState<OptionChoices>(() => {
@@ -127,12 +126,16 @@ export function useProductActions({
     setQuantityState(Math.max(1, Math.floor(next) || 1))
   }, [])
 
-  // Rule 3: the address follows the choice, in the browser alone.
+  // Rule 3: the address follows the choice, in the browser alone. The query
+  // is read here, when the address is written, and never while rendering: a
+  // render that reads the query is request data, and would stop a store on
+  // Cache Components from prerendering its product pages.
   useEffect(() => {
     if (!syncAddress || variants.length < 2 || !variant) return
-    if (searchParams.get(VARIANT_PARAM) === variantParamValue(variant.id)) return
-    window.history.replaceState(null, "", variantHref(pathname, searchParams, variant.id))
-  }, [syncAddress, variants.length, variant, searchParams, pathname])
+    const search = new URLSearchParams(window.location.search)
+    if (search.get(VARIANT_PARAM) === variantParamValue(variant.id)) return
+    window.history.replaceState(null, "", variantHref(pathname, search, variant.id))
+  }, [syncAddress, variants.length, variant, pathname])
 
   const inStock = useMemo(() => {
     if (!variant) return false

package/src/reviews-ui/index.ts

@@ -50,11 +50,15 @@ export {
   type RatingDistributionProps,
 } from "./star-badge"
 
+export { ReviewList, type ReviewListProps } from "./review-list"
+
+export { ReviewLightbox, type ReviewLightboxProps } from "./review-lightbox"
+
 export {
-  ReviewList,
-  ReviewLightbox,
-  type ReviewListProps,
-} from "./review-list"
+  lightboxMedia,
+  stepLightbox,
+  type LightboxPosition,
+} from "./lightbox-state"
 
 export { ReviewWidget, type ReviewWidgetProps } from "./review-widget"
 

package/src/reviews-ui/labels.ts

@@ -31,6 +31,18 @@ export type ReviewsUiLabels = {
   showPhoto: string
   playVideo: string
   close: string
+  // — lightbox —
+  /** A review card's own button: the whole card opens the lightbox. */
+  openReview: string
+  /** The info button beside "Verified"; its popover says `verifiedTitle`. */
+  verifiedInfo: string
+  storeReply: string
+  previous: string
+  next: string
+  /** `{n}` = position, `{total}` = the review's photo count, `{name}` = reviewer. */
+  mediaAlt: string
+  /** A dot under the photo; `{n}` = position. */
+  showMediaAt: string
   // — wizard: entry states (ported from the alenika /review/[token] page) —
   expiredTitle: string
   /** `{email}` = store support email. */
@@ -133,6 +145,13 @@ export const defaultReviewsUiLabels: ReviewsUiLabels = {
   showPhoto: "View photo",
   playVideo: "Play video",
   close: "Close",
+  openReview: "Open the review",
+  verifiedInfo: "What verified means",
+  storeReply: "Reply from the store",
+  previous: "Previous",
+  next: "Next",
+  mediaAlt: "Photo {n} of {total} from {name}",
+  showMediaAt: "Show photo {n}",
   expiredTitle: "This review link has expired",
   expiredBody:
     "The link was valid for 60 days after your purchase. If you'd like to leave a review, write to us at {email}.",

package/src/reviews-ui/lightbox-state.ts

@@ -0,0 +1,46 @@
+/**
+ * Where the review lightbox stands, and how it steps. Pure, no React, so
+ * every widget that opens the lightbox (the review list, a carousel, a
+ * store's own row of reviews) walks the same sequence. Unit-tested in
+ * tests/unit/storefront-review-lightbox.test.ts.
+ */
+import type { PublicReview, ReviewMedia } from "../api/reviews"
+
+/** The open review (its index in the widget's list) and which of its photos or videos. */
+export interface LightboxPosition {
+  review: number
+  media: number
+}
+
+/**
+ * A review's photos and videos as the lightbox shows them: the SAME
+ * filtered list the cards count their indexes from, so a falsy entry can
+ * never shift which item opens (the Alenika production fix).
+ */
+export function lightboxMedia(review: Pick<PublicReview, "media"> | undefined): ReviewMedia[] {
+  return (review?.media ?? []).filter(Boolean)
+}
+
+/**
+ * One step through the reviews: through the open review's photos first,
+ * then on to the next review's first one, or back to the previous review's
+ * last. Null at either end, where the arrow is not drawn.
+ */
+export function stepLightbox(
+  reviews: ReadonlyArray<Pick<PublicReview, "media">>,
+  at: LightboxPosition,
+  direction: 1 | -1
+): LightboxPosition | null {
+  const count = lightboxMedia(reviews[at.review]).length
+  if (direction === 1) {
+    if (at.media + 1 < count) return { review: at.review, media: at.media + 1 }
+    if (at.review + 1 < reviews.length) return { review: at.review + 1, media: 0 }
+    return null
+  }
+  if (at.media > 0) return { review: at.review, media: at.media - 1 }
+  if (at.review > 0) {
+    const previous = lightboxMedia(reviews[at.review - 1]).length
+    return { review: at.review - 1, media: Math.max(previous - 1, 0) }
+  }
+  return null
+}

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

@@ -0,0 +1,271 @@
+"use client"
+
+import { useEffect, type ReactNode } from "react"
+import * as DialogPrimitive from "@radix-ui/react-dialog"
+import { ChevronLeft, ChevronRight, CircleCheck, Info, X } from "lucide-react"
+import type { PublicReview } from "../api/reviews"
+import { cn } from "../lib/utils"
+import { useLocaleArea } from "../locales/context"
+import { DialogOverlay, DialogPortal } from "../primitives/ui/dialog"
+import { Popover, PopoverContent, PopoverTrigger } from "../primitives/ui/popover"
+import { formatLabel, formatReviewDate, reviewDisplayName } from "./helpers"
+import { defaultReviewsUiLabels, type ReviewsUiLabels } from "./labels"
+import { lightboxMedia, stepLightbox, type LightboxPosition } from "./lightbox-state"
+import { StarRow } from "./star-badge"
+
+/**
+ * The review lightbox: one review, whole. The photo or video on the left
+ * over a blurred copy of itself, the review on the right: the reviewer's
+ * name, "Verified" with a button that says what it means, the stars, the
+ * date, the text and the store's reply. On a phone the photo sits on top
+ * and the review scrolls under it.
+ *
+ * Every widget that shows reviews opens this one: it takes the widget's
+ * own list and a position, so the arrows (and the arrow keys) walk through
+ * the open review's photos and then on to the next review. The dots jump
+ * between one review's photos. Built on the package's Dialog (focus trap,
+ * scroll lock, Escape and a click outside close it).
+ *
+ *   const [open, setOpen] = useState<LightboxPosition | null>(null)
+ *   <ReviewLightbox reviews={reviews} position={open} onPositionChange={setOpen} />
+ *
+ * Alenika's production fixes are kept: the media index counts from the
+ * same filtered list the cards use, and a video plays inline on iPhone
+ * with its controls as the answer to a blocked autoplay.
+ */
+export interface ReviewLightboxProps {
+  /** The reviews the opening widget shows, in its order. */
+  reviews: PublicReview[]
+  /** The open review and which of its photos; null when closed. */
+  position: LightboxPosition | null
+  /** The new position when the shopper steps, null when they close. */
+  onPositionChange: (position: LightboxPosition | null) => void
+  labels?: Partial<ReviewsUiLabels>
+}
+
+export function ReviewLightbox({ reviews, position, onPositionChange, labels }: ReviewLightboxProps) {
+  const l = { ...useLocaleArea("reviews", defaultReviewsUiLabels), ...labels }
+  const review = position ? reviews[position.review] : undefined
+  const media = lightboxMedia(review)
+  const item = position ? media[position.media] : undefined
+  const previous = position ? stepLightbox(reviews, position, -1) : null
+  const next = position ? stepLightbox(reviews, position, 1) : null
+
+  // The arrow keys step as the arrows do; a video keeps its own keys.
+  useEffect(() => {
+    if (!position) return
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key !== "ArrowLeft" && event.key !== "ArrowRight") return
+      if ((event.target as HTMLElement | null)?.closest?.("video, input, textarea, select")) return
+      const to = stepLightbox(reviews, position, event.key === "ArrowLeft" ? -1 : 1)
+      if (to) onPositionChange(to)
+    }
+    window.addEventListener("keydown", onKey)
+    return () => window.removeEventListener("keydown", onKey)
+  }, [position, reviews, onPositionChange])
+
+  const name = review ? reviewDisplayName(review.customer_name) : ""
+  const stepping = Boolean(previous || next)
+
+  return (
+    <DialogPrimitive.Root
+      open={Boolean(review)}
+      onOpenChange={(open) => {
+        if (!open) onPositionChange(null)
+      }}
+    >
+      <DialogPortal>
+        <DialogOverlay />
+        <DialogPrimitive.Content
+          aria-describedby={undefined}
+          className={cn(
+            "fixed inset-0 z-50 outline-none data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=closed]:animate-out data-[state=closed]:fade-out-0",
+            "md:inset-auto md:left-1/2 md:top-1/2 md:w-[calc(100%-10rem)] md:-translate-x-1/2 md:-translate-y-1/2 md:data-[state=open]:zoom-in-95 md:data-[state=closed]:zoom-out-95",
+            item ? "md:max-w-[55rem]" : "md:max-w-lg"
+          )}
+        >
+          {review ? (
+            <>
+              <DialogPrimitive.Close
+                aria-label={l.close}
+                className={cn(
+                  "absolute left-4 top-4 z-10 flex size-10 items-center justify-center rounded-md transition-colors",
+                  item
+                    ? "bg-black/40 text-white hover:bg-black/55"
+                    : "bg-muted text-foreground hover:bg-border"
+                )}
+              >
+                <X className="size-5" />
+              </DialogPrimitive.Close>
+
+              <div
+                className={cn(
+                  "flex h-full flex-col overflow-y-auto bg-background md:overflow-hidden md:rounded-lg md:shadow-popover",
+                  item ? "md:h-[min(40rem,calc(100dvh-4rem))] md:flex-row" : "md:h-auto md:max-h-[calc(100dvh-4rem)]"
+                )}
+              >
+                {item && position ? (
+                  <div className="relative flex h-[min(60vh,32rem)] shrink-0 items-center justify-center overflow-hidden bg-muted md:h-full md:w-[54%]">
+                    {item.type === "image" ? (
+                      <>
+                        <img
+                          src={item.url}
+                          alt=""
+                          aria-hidden
+                          className="pointer-events-none absolute inset-0 size-full scale-110 object-cover blur-2xl"
+                        />
+                        <img
+                          key={item.url}
+                          src={item.url}
+                          alt={formatLabel(l.mediaAlt, {
+                            n: position.media + 1,
+                            total: media.length,
+                            name,
+                          })}
+                          className="relative size-full object-contain"
+                        />
+                      </>
+                    ) : (
+                      <video
+                        key={item.url}
+                        src={`${item.url}#t=0.001`}
+                        controls
+                        autoPlay
+                        playsInline
+                        preload="metadata"
+                        className="relative size-full bg-black object-contain"
+                      />
+                    )}
+
+                    {media.length > 1 ? (
+                      <div
+                        className={cn(
+                          "absolute inset-x-0 flex justify-center gap-1.5",
+                          item.type === "video" ? "top-4" : "bottom-4"
+                        )}
+                      >
+                        {media.map((entry, index) => (
+                          <button
+                            key={`${entry.url}-${index}`}
+                            type="button"
+                            aria-label={formatLabel(l.showMediaAt, { n: index + 1 })}
+                            aria-current={index === position.media}
+                            onClick={() => onPositionChange({ review: position.review, media: index })}
+                            className={cn(
+                              "size-2 rounded-full ring-1 ring-black/20 transition-colors",
+                              index === position.media ? "bg-white" : "bg-white/50 hover:bg-white/80"
+                            )}
+                          />
+                        ))}
+                      </div>
+                    ) : null}
+                  </div>
+                ) : null}
+
+                <div
+                  className={cn(
+                    "flex min-w-0 flex-1 flex-col gap-4 p-6 md:overflow-y-auto md:p-7",
+                    !item && "pt-16 md:pt-16",
+                    stepping && "pb-20 md:pb-7"
+                  )}
+                >
+                  <div className="flex flex-col gap-1.5">
+                    <div className="flex items-center justify-between gap-3">
+                      <DialogPrimitive.Title className="min-w-0 truncate text-body text-foreground">
+                        {name}
+                      </DialogPrimitive.Title>
+                      <div className="flex shrink-0 items-center gap-2 text-body-small text-foreground">
+                        <span className="flex items-center gap-1.5">
+                          <CircleCheck aria-hidden className="size-4.5 fill-foreground text-background" />
+                          {l.verified}
+                        </span>
+                        <span aria-hidden className="h-5 w-px bg-border" />
+                        <Popover>
+                          <PopoverTrigger
+                            aria-label={l.verifiedInfo}
+                            className="flex size-7 items-center justify-center rounded-full transition-colors hover:bg-muted"
+                          >
+                            <Info className="size-4.5" />
+                          </PopoverTrigger>
+                          <PopoverContent align="end" className="w-64 text-body-small">
+                            {l.verifiedTitle}
+                          </PopoverContent>
+                        </Popover>
+                      </div>
+                    </div>
+                    <div className="flex items-center justify-between gap-3">
+                      <StarRow rating={review.rating} size="lg" />
+                      <span className="shrink-0 text-caption text-muted-foreground">
+                        {formatReviewDate(review.created_at, l)}
+                      </span>
+                    </div>
+                  </div>
+
+                  {review.title ? <p className="text-h6 text-foreground">{review.title}</p> : null}
+                  {review.body ? (
+                    <p className="whitespace-pre-wrap text-body text-foreground">{review.body}</p>
+                  ) : null}
+
+                  {review.admin_response ? (
+                    <div className="rounded-md bg-muted p-4">
+                      <p className="text-caption text-muted-foreground">{l.storeReply}</p>
+                      <p className="mt-1 whitespace-pre-wrap text-body-small text-foreground">
+                        {review.admin_response}
+                      </p>
+                    </div>
+                  ) : null}
+                </div>
+              </div>
+
+              {previous ? (
+                <StepButton
+                  label={l.previous}
+                  onClick={() => onPositionChange(previous)}
+                  className="bottom-4 left-4 md:-left-14"
+                >
+                  <ChevronLeft className="size-5" />
+                </StepButton>
+              ) : null}
+              {next ? (
+                <StepButton
+                  label={l.next}
+                  onClick={() => onPositionChange(next)}
+                  className="bottom-4 right-4 md:-right-14"
+                >
+                  <ChevronRight className="size-5" />
+                </StepButton>
+              ) : null}
+            </>
+          ) : null}
+        </DialogPrimitive.Content>
+      </DialogPortal>
+    </DialogPrimitive.Root>
+  )
+}
+
+/** A round arrow: in the bottom corners on a phone, beside the card on a wider screen. */
+function StepButton({
+  label,
+  onClick,
+  className,
+  children,
+}: {
+  label: string
+  onClick: () => void
+  className: string
+  children: ReactNode
+}) {
+  return (
+    <button
+      type="button"
+      aria-label={label}
+      onClick={onClick}
+      className={cn(
+        "absolute z-10 flex size-10 items-center justify-center rounded-full bg-background text-foreground shadow-popover transition-colors hover:bg-muted md:bottom-auto md:top-1/2 md:-translate-y-1/2",
+        className
+      )}
+    >
+      {children}
+    </button>
+  )
+}

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

@@ -1,251 +1,191 @@
-"use client"
-
-import { useEffect, useState } from "react"
-import { ShieldCheck, X } 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 { StarRow } from "./star-badge"
-
-/**
- * Review cards (masonry) + lightbox. Ported from the Alenika PDP reviews
- * section (src/components/product/reviews-list.tsx — the card grid +
- * `Lightbox`), 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).
- *
- * 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 }
-  // Lightbox: when set, the indicated review's media at the given index
-  // is shown full-bleed.
-  const [lightbox, setLightbox] = useState<{
-    reviewId: string
-    mediaIdx: number
-  } | 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) => {
-          const media = (r.media ?? []).filter(Boolean)
-          const hero = media[0]
-          const rest = media.slice(1)
-          return (
-            <li
-              key={r.id}
-              className="break-inside-avoid mb-4 rounded-[2px] border border-border bg-background overflow-hidden"
-            >
-              {/* Hero media on top */}
-              {hero && (
-                <button
-                  type="button"
-                  onClick={() => setLightbox({ reviewId: r.id, mediaIdx: 0 })}
-                  aria-label={hero.type === "image" ? l.showPhoto : l.playVideo}
-                  className="block w-full relative 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]"
-                    />
-                  ) : (
-                    <>
-                      <video
-                        src={hero.url}
-                        muted
-                        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="grid grid-cols-4 gap-2 mt-3">
-                    {rest.map((m, i) => (
-                      <button
-                        key={i}
-                        type="button"
-                        onClick={() =>
-                          setLightbox({ reviewId: r.id, mediaIdx: 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}
-                            muted
-                            preload="metadata"
-                            className="absolute inset-0 w-full h-full object-cover bg-black"
-                          />
-                        )}
-                      </button>
-                    ))}
-                  </div>
-                )}
-              </div>
-            </li>
-          )
-        })}
-      </ul>
-
-      {lightbox && (
-        <ReviewLightbox
-          review={reviews.find((r) => r.id === lightbox.reviewId)}
-          mediaIdx={lightbox.mediaIdx}
-          closeLabel={l.close}
-          onClose={() => setLightbox(null)}
-        />
-      )}
-    </>
-  )
-}
-
-/** Simple full-bleed overlay for the picked media. Closes on Escape/backdrop. */
-export function ReviewLightbox({
-  review,
-  mediaIdx,
-  closeLabel,
-  onClose,
-}: {
-  review: PublicReview | undefined
-  mediaIdx: number
-  closeLabel?: string
-  onClose: () => void
-}) {
-  const fallback = useLocaleArea("reviews", defaultReviewsUiLabels)
-  // Close on Escape
-  useEffect(() => {
-    const onKey = (e: KeyboardEvent) => {
-      if (e.key === "Escape") onClose()
-    }
-    window.addEventListener("keydown", onKey)
-    return () => window.removeEventListener("keydown", onKey)
-  }, [onClose])
-
-  if (!review) return null
-  // Index into the SAME filtered array the grid used to compute mediaIdx,
-  // so a falsy/hidden entry can't shift which item opens (production fix).
-  const items = (review.media ?? []).filter(Boolean)
-  const item = items[mediaIdx]
-  if (!item) return null
-
-  return (
-    <div
-      role="dialog"
-      aria-modal="true"
-      className="fixed inset-0 z-50 bg-black/90 flex items-center justify-center p-4"
-      onClick={onClose}
-    >
-      <button
-        type="button"
-        aria-label={closeLabel ?? fallback.close}
-        onClick={onClose}
-        className="absolute top-4 right-4 w-10 h-10 rounded-full bg-background/10 hover:bg-background/20 text-background flex items-center justify-center"
-      >
-        <X className="w-5 h-5" />
-      </button>
-      <div
-        className="max-w-5xl max-h-[90vh] w-full flex items-center justify-center"
-        onClick={(e) => e.stopPropagation()}
-      >
-        {item.type === "image" ? (
-          <img
-            src={item.url}
-            alt=""
-            className="max-w-full max-h-[90vh] object-contain"
-          />
-        ) : (
-          <video
-            src={item.url}
-            controls
-            autoPlay
-            className="max-w-full max-h-[90vh]"
-          />
-        )}
-      </div>
-    </div>
-  )
-}
+"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}
+      />
+    </>
+  )
+}

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

@@ -11,23 +11,33 @@ import { reviewCountLabel } from "./helpers"
  * arrives via props (`api/reviews.getAggregate` / `getWidget().aggregate`).
  */
 
-/** Five-star row, filled to `Math.round(rating)`. */
+/**
+ * Five-star row, filled to `Math.round(rating)` in the theme's `rating`
+ * colour. `lg` is the lightbox's row.
+ */
 export function StarRow({
   rating,
+  size = "sm",
   className,
 }: {
   rating: number
+  size?: "sm" | "lg"
   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 === "lg" ? "gap-px" : "gap-0.5", className)}
+    >
       {Array.from({ length: 5 }).map((_, i) => (
         <Star
           key={i}
+          aria-hidden
           className={cn(
-            "w-3.5 h-3.5",
+            size === "lg" ? "size-5" : "size-3.5",
             i < Math.round(rating)
-              ? "fill-warning text-warning"
+              ? "fill-rating text-rating"
               : "fill-muted text-muted-foreground"
           )}
           strokeWidth={0}
@@ -53,7 +63,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/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);