@cartbase/storefront 0.20.0 → 0.21.0

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

@@ -1,218 +1,219 @@
-"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>
-  )
-}
+"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]"
+            : // Two on a phone, then as many ~14rem columns as the page is wide.
+              "columns-2 sm:columns-[14rem] [column-gap:1rem]",
+          loading && "opacity-60 transition-opacity"
+        )}
+      />
+
+      {hasMore && (
+        <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/widget-options.ts

@@ -1,55 +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,
-  }
-}
+/**
+ * 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: 20,
+  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,
+  }
+}