@cartbase/storefront 0.18.1 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cartbase/storefront",
-  "version": "0.18.1",
+  "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/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

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

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,14 @@ 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",
+    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,14 +50,30 @@ 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"
 
+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,20 @@ 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
+  /** 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. */
@@ -118,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",
@@ -133,6 +147,14 @@ 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",
+  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-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>
+  )
+}