@cartbase/storefront 0.19.0 → 0.20.1

package/src/products/variant-url.ts

@@ -1,74 +1,74 @@
-/**
- * The product page contract, part one: THE ADDRESS IS THE STATE.
- *
- * A product page names its chosen variant in the address, the way Shopify
- * does: `/products/<handle>?variant=<id>`. One parameter name for every
- * store, so a link in an email, an ad or a chat opens on the variant it was
- * copied from, and a refresh never forgets a choice.
- *
- * The value is the id's DIGITS, never the prefixed key: the platform's law
- * for every id in a URL (entity-numbers-everywhere card). `pvar_1000683784068`
- * travels as `1000683784068`; reading accepts both forms, so an old link
- * with the whole key still resolves.
- *
- * The default, when the address names nothing, is THE MERCHANT'S: the
- * variant made of each option's first value, in the option order the admin
- * shows. Not the first variant of the wire, which is whatever the database
- * scanned first (2026-09-15, evoo: the carton before the bottle on a product
- * whose option says bottle first). Pure module, no React.
- */
-import type { StoreProduct, StoreProductVariant } from "../api/products"
-import { findMatchingVariant } from "./variant-matching"
-
-/** Shopify's parameter name, and ours. */
-export const VARIANT_PARAM = "variant"
-
-/** The digits of a platform id; an id without a prefix travels whole. */
-export function variantParamValue(variantId: string): string {
-  const underscore = variantId.indexOf("_")
-  return underscore >= 0 ? variantId.slice(underscore + 1) : variantId
-}
-
-/** The variant an address names, by its digits or by its whole id. */
-export function findVariantByParam<V extends { id: string }>(
-  variants: V[] | null | undefined,
-  value: string | null | undefined
-): V | undefined {
-  if (!value) return undefined
-  return variants?.find((v) => v.id === value || variantParamValue(v.id) === value)
-}
-
-/**
- * The merchant's default variant: each option's first value, together;
- * failing that, the lowest rank; failing that, the first of the wire.
- */
-export function defaultVariant(
-  product: Pick<StoreProduct, "options" | "variants">
-): StoreProductVariant | undefined {
-  const variants = product.variants ?? []
-  if (!variants.length) return undefined
-  if (variants.length === 1) return variants[0]
-
-  const firstValues: Record<string, string> = {}
-  for (const option of product.options ?? []) {
-    const first = option.values?.[0]?.value
-    if (first) firstValues[option.id] = first
-  }
-  const byOptions = Object.keys(firstValues).length
-    ? findMatchingVariant(variants, firstValues)
-    : undefined
-  if (byOptions) return byOptions
-
-  return [...variants].sort((a, b) => (a.variant_rank ?? 0) - (b.variant_rank ?? 0))[0]
-}
-
-/** The page's address with the variant written in, every other parameter kept. */
-export function variantHref(
-  pathname: string,
-  search: string | URLSearchParams | null | undefined,
-  variantId: string
-): string {
-  const params = new URLSearchParams(search ?? "")
-  params.set(VARIANT_PARAM, variantParamValue(variantId))
-  return `${pathname}?${params.toString()}`
-}
+/**
+ * The product page contract, part one: THE ADDRESS IS THE STATE.
+ *
+ * A product page names its chosen variant in the address, the way Shopify
+ * does: `/products/<handle>?variant=<id>`. One parameter name for every
+ * store, so a link in an email, an ad or a chat opens on the variant it was
+ * copied from, and a refresh never forgets a choice.
+ *
+ * The value is the id's DIGITS, never the prefixed key: the platform's law
+ * for every id in a URL (entity-numbers-everywhere card). `pvar_1000683784068`
+ * travels as `1000683784068`; reading accepts both forms, so an old link
+ * with the whole key still resolves.
+ *
+ * The default, when the address names nothing, is THE MERCHANT'S: the
+ * variant made of each option's first value, in the option order the admin
+ * shows. Not the first variant of the wire, which is whatever the database
+ * scanned first (2026-09-15, evoo: the carton before the bottle on a product
+ * whose option says bottle first). Pure module, no React.
+ */
+import type { StoreProduct, StoreProductVariant } from "../api/products"
+import { findMatchingVariant } from "./variant-matching"
+
+/** Shopify's parameter name, and ours. */
+export const VARIANT_PARAM = "variant"
+
+/** The digits of a platform id; an id without a prefix travels whole. */
+export function variantParamValue(variantId: string): string {
+  const underscore = variantId.indexOf("_")
+  return underscore >= 0 ? variantId.slice(underscore + 1) : variantId
+}
+
+/** The variant an address names, by its digits or by its whole id. */
+export function findVariantByParam<V extends { id: string }>(
+  variants: V[] | null | undefined,
+  value: string | null | undefined
+): V | undefined {
+  if (!value) return undefined
+  return variants?.find((v) => v.id === value || variantParamValue(v.id) === value)
+}
+
+/**
+ * The merchant's default variant: each option's first value, together;
+ * failing that, the lowest rank; failing that, the first of the wire.
+ */
+export function defaultVariant(
+  product: Pick<StoreProduct, "options" | "variants">
+): StoreProductVariant | undefined {
+  const variants = product.variants ?? []
+  if (!variants.length) return undefined
+  if (variants.length === 1) return variants[0]
+
+  const firstValues: Record<string, string> = {}
+  for (const option of product.options ?? []) {
+    const first = option.values?.[0]?.value
+    if (first) firstValues[option.id] = first
+  }
+  const byOptions = Object.keys(firstValues).length
+    ? findMatchingVariant(variants, firstValues)
+    : undefined
+  if (byOptions) return byOptions
+
+  return [...variants].sort((a, b) => (a.variant_rank ?? 0) - (b.variant_rank ?? 0))[0]
+}
+
+/** The page's address with the variant written in, every other parameter kept. */
+export function variantHref(
+  pathname: string,
+  search: string | URLSearchParams | null | undefined,
+  variantId: string
+): string {
+  const params = new URLSearchParams(search ?? "")
+  params.set(VARIANT_PARAM, variantParamValue(variantId))
+  return `${pathname}?${params.toString()}`
+}

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/lightbox-state.ts

@@ -1,46 +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
-}
+/**
+ * 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>
+  )
+}