@cartbase/storefront 0.19.0 → 0.20.1

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

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

package/src/reviews-ui/widget-options.ts

@@ -0,0 +1,55 @@
+/**
+ * The reviews widget's display options with every default filled, from the
+ * payload the platform serves (`getWidget().options`) or from nothing. A
+ * platform older than a field leaves it out; the widget then shows what
+ * Loox shows by default. Pure. Unit-tested in
+ * tests/unit/storefront-review-lightbox.test.ts.
+ */
+import type {
+  ReviewWidgetHeader,
+  ReviewWidgetHeaderContent,
+  ReviewWidgetPayload,
+} from "../api/reviews"
+
+export interface ReviewWidgetOptions {
+  layout: "masonry" | "list"
+  pageSize: number
+  header: ReviewWidgetHeader
+  headerContent: ReviewWidgetHeaderContent
+  showDistribution: boolean
+  showSort: boolean
+  showDate: boolean
+}
+
+export const DEFAULT_REVIEW_WIDGET_OPTIONS: ReviewWidgetOptions = {
+  layout: "masonry",
+  pageSize: 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,
+  }
+}

package/src/store/category-template.tsx

@@ -1,136 +1,136 @@
-/**
- * Category page — ported from
- * `@1click/ui/src/store/category-template.tsx` (v2.3.1). Data seam:
- * `HttpTypes.StoreProductCategory` → Cartbase `StoreProductCategory`
- * (`@cartbase/storefront/api/categories`); products come from the plain
- * listing filtered by `category_id` (membership), via `PaginatedProducts`.
- *
- * Breadcrumbs need `parent_category` chains and the child list needs
- * `category_children` — fetch the category with `include_ancestors_tree` +
- * `include_descendants_tree` (`retrieveCategory` query flags), otherwise
- * those sections simply don't render. Skeleton count is the fixed default
- * (Cartbase categories don't embed a products array).
- */
-import { Suspense } from "react"
-import { notFound } from "next/navigation"
-import Link from "next/link"
-import type { StorefrontClient } from "../api/http"
-import type { PricingContextQuery } from "../api/types"
-import type { StoreProductCategory } from "../api/categories"
-import type { SortOptions } from "../lib/sort-products"
-import type { StoreLabels } from "./labels"
-import { SortSelect } from "./sort-select"
-import { PaginatedProducts, type ProductCardComponent } from "./paginated-products"
-import { SkeletonProductGrid } from "./skeleton-product-grid"
-
-type CategoryTemplateProps = {
-  client: StorefrontClient
-  category: StoreProductCategory
-  sortBy?: SortOptions
-  /** From the `page` query param. */
-  page?: string
-  pricingContext?: PricingContextQuery
-  /**
-   * The store's pack for this area, REQUIRED: this is a server component and
-   * cannot read `StorefrontLocaleProvider`, so the page passes
-   * `STORE_LOCALE.store` (`en.store` for an English store). Required since
-   * 2026-09-14 so that forgetting it fails the build instead of shipping
-   * silent English.
-   */
-  labels: StoreLabels
-  /** Override the default ProductPreview with a store-specific card. */
-  renderProduct?: ProductCardComponent
-}
-
-export function CategoryTemplate({
-  client,
-  category,
-  sortBy,
-  page,
-  pricingContext,
-  labels,
-  renderProduct,
-}: CategoryTemplateProps) {
-  const pageNumber = page ? parseInt(page) : 1
-  const sort = sortBy || "created_at"
-
-  if (!category) notFound()
-
-  const parents: StoreProductCategory[] = []
-  const getParents = (cat: StoreProductCategory) => {
-    if (cat.parent_category) {
-      parents.push(cat.parent_category)
-      getParents(cat.parent_category)
-    }
-  }
-  getParents(category)
-
-  return (
-    <div
-      className="flex flex-col sm:flex-row sm:items-start py-6 max-w-7xl mx-auto px-4"
-      data-testid="category-container"
-    >
-      <div className="flex sm:flex-col gap-12 py-4 mb-8 sm:px-0 pl-6 sm:min-w-[250px]">
-        <SortSelect
-          sortBy={sort}
-          labels={labels}
-          data-testid="sort-by-container"
-        />
-      </div>
-      <div className="w-full">
-        <div className="flex flex-row mb-8 gap-4">
-          {parents.map((parent) => (
-            <span key={parent.id} className="text-muted-foreground text-2xl">
-              <Link
-                className="mr-4 hover:text-foreground"
-                href={`/categories/${parent.handle}`}
-              >
-                {parent.name}
-              </Link>
-              /
-            </span>
-          ))}
-          <h1
-            className="text-2xl font-semibold text-foreground"
-            data-testid="category-page-title"
-          >
-            {category.name}
-          </h1>
-        </div>
-        {category.description && (
-          <div className="mb-8 text-sm text-muted-foreground">
-            <p>{category.description}</p>
-          </div>
-        )}
-        {category.category_children && (
-          <div className="mb-8">
-            <ul className="grid grid-cols-1 gap-2">
-              {category.category_children.map((c) => (
-                <li key={c.id}>
-                  <Link
-                    href={`/categories/${c.handle}`}
-                    className="text-primary hover:underline"
-                  >
-                    {c.name}
-                  </Link>
-                </li>
-              ))}
-            </ul>
-          </div>
-        )}
-        <Suspense fallback={<SkeletonProductGrid />}>
-          <PaginatedProducts
-            client={client}
-            sortBy={sort}
-            page={pageNumber}
-            categoryId={category.id}
-            pricingContext={pricingContext}
-            renderProduct={renderProduct}
-          />
-        </Suspense>
-      </div>
-    </div>
-  )
-}
-
-export { type CategoryTemplateProps }
+/**
+ * Category page — ported from
+ * `@1click/ui/src/store/category-template.tsx` (v2.3.1). Data seam:
+ * `HttpTypes.StoreProductCategory` → Cartbase `StoreProductCategory`
+ * (`@cartbase/storefront/api/categories`); products come from the plain
+ * listing filtered by `category_id` (membership), via `PaginatedProducts`.
+ *
+ * Breadcrumbs need `parent_category` chains and the child list needs
+ * `category_children` — fetch the category with `include_ancestors_tree` +
+ * `include_descendants_tree` (`retrieveCategory` query flags), otherwise
+ * those sections simply don't render. Skeleton count is the fixed default
+ * (Cartbase categories don't embed a products array).
+ */
+import { Suspense } from "react"
+import { notFound } from "next/navigation"
+import Link from "next/link"
+import type { StorefrontClient } from "../api/http"
+import type { PricingContextQuery } from "../api/types"
+import type { StoreProductCategory } from "../api/categories"
+import type { SortOptions } from "../lib/sort-products"
+import type { StoreLabels } from "./labels"
+import { SortSelect } from "./sort-select"
+import { PaginatedProducts, type ProductCardComponent } from "./paginated-products"
+import { SkeletonProductGrid } from "./skeleton-product-grid"
+
+type CategoryTemplateProps = {
+  client: StorefrontClient
+  category: StoreProductCategory
+  sortBy?: SortOptions
+  /** From the `page` query param. */
+  page?: string
+  pricingContext?: PricingContextQuery
+  /**
+   * The store's pack for this area, REQUIRED: this is a server component and
+   * cannot read `StorefrontLocaleProvider`, so the page passes
+   * `STORE_LOCALE.store` (`en.store` for an English store). Required since
+   * 2026-09-14 so that forgetting it fails the build instead of shipping
+   * silent English.
+   */
+  labels: StoreLabels
+  /** Override the default ProductPreview with a store-specific card. */
+  renderProduct?: ProductCardComponent
+}
+
+export function CategoryTemplate({
+  client,
+  category,
+  sortBy,
+  page,
+  pricingContext,
+  labels,
+  renderProduct,
+}: CategoryTemplateProps) {
+  const pageNumber = page ? parseInt(page) : 1
+  const sort = sortBy || "created_at"
+
+  if (!category) notFound()
+
+  const parents: StoreProductCategory[] = []
+  const getParents = (cat: StoreProductCategory) => {
+    if (cat.parent_category) {
+      parents.push(cat.parent_category)
+      getParents(cat.parent_category)
+    }
+  }
+  getParents(category)
+
+  return (
+    <div
+      className="flex flex-col sm:flex-row sm:items-start py-6 max-w-7xl mx-auto px-4"
+      data-testid="category-container"
+    >
+      <div className="flex sm:flex-col gap-12 py-4 mb-8 sm:px-0 pl-6 sm:min-w-[250px]">
+        <SortSelect
+          sortBy={sort}
+          labels={labels}
+          data-testid="sort-by-container"
+        />
+      </div>
+      <div className="w-full">
+        <div className="flex flex-row mb-8 gap-4">
+          {parents.map((parent) => (
+            <span key={parent.id} className="text-muted-foreground text-2xl">
+              <Link
+                className="mr-4 hover:text-foreground"
+                href={`/categories/${parent.handle}`}
+              >
+                {parent.name}
+              </Link>
+              /
+            </span>
+          ))}
+          <h1
+            className="text-2xl font-semibold text-foreground"
+            data-testid="category-page-title"
+          >
+            {category.name}
+          </h1>
+        </div>
+        {category.description && (
+          <div className="mb-8 text-sm text-muted-foreground">
+            <p>{category.description}</p>
+          </div>
+        )}
+        {category.category_children && (
+          <div className="mb-8">
+            <ul className="grid grid-cols-1 gap-2">
+              {category.category_children.map((c) => (
+                <li key={c.id}>
+                  <Link
+                    href={`/categories/${c.handle}`}
+                    className="text-primary hover:underline"
+                  >
+                    {c.name}
+                  </Link>
+                </li>
+              ))}
+            </ul>
+          </div>
+        )}
+        <Suspense fallback={<SkeletonProductGrid />}>
+          <PaginatedProducts
+            client={client}
+            sortBy={sort}
+            page={pageNumber}
+            categoryId={category.id}
+            pricingContext={pricingContext}
+            renderProduct={renderProduct}
+          />
+        </Suspense>
+      </div>
+    </div>
+  )
+}
+
+export { type CategoryTemplateProps }

package/src/store/index.ts

@@ -1,40 +1,40 @@
-/**
- * @cartbase/storefront — store (listing) family barrel. Prefer subpath
- * imports in apps; the barrel exists for convenience and for the extra pure
- * module (search-params).
- */
-export {
-  defaultStoreLabels,
-  sortOptionLabelKeys,
-  type StoreLabels,
-} from "./labels"
-
-export { Pagination } from "./pagination"
-export { SortSelect, type SortSelectProps } from "./sort-select"
-export { PaginatedProducts, type ProductCardComponent } from "./paginated-products"
-export { SkeletonProductGrid } from "./skeleton-product-grid"
-export { StoreTemplate, type StoreTemplateProps } from "./store-template"
-export {
-  CollectionTemplate,
-  type CollectionTemplateProps,
-} from "./collection-template"
-export {
-  CategoryTemplate,
-  type CategoryTemplateProps,
-} from "./category-template"
-export { SearchTemplate, type SearchTemplateProps } from "./search-template"
-
-export {
-  parseSearchParams,
-  buildSearchQueryString,
-  fromQueryString,
-  toggleFacetSelection,
-  isFacetSelected,
-  clearFilters,
-  toSearchQuery,
-  type SearchPageState,
-  type RawSearchParams,
-  type FacetBucketRef,
-} from "./search-params"
-
-export { type SortOptions } from "../lib/sort-products"
+/**
+ * @cartbase/storefront — store (listing) family barrel. Prefer subpath
+ * imports in apps; the barrel exists for convenience and for the extra pure
+ * module (search-params).
+ */
+export {
+  defaultStoreLabels,
+  sortOptionLabelKeys,
+  type StoreLabels,
+} from "./labels"
+
+export { Pagination } from "./pagination"
+export { SortSelect, type SortSelectProps } from "./sort-select"
+export { PaginatedProducts, type ProductCardComponent } from "./paginated-products"
+export { SkeletonProductGrid } from "./skeleton-product-grid"
+export { StoreTemplate, type StoreTemplateProps } from "./store-template"
+export {
+  CollectionTemplate,
+  type CollectionTemplateProps,
+} from "./collection-template"
+export {
+  CategoryTemplate,
+  type CategoryTemplateProps,
+} from "./category-template"
+export { SearchTemplate, type SearchTemplateProps } from "./search-template"
+
+export {
+  parseSearchParams,
+  buildSearchQueryString,
+  fromQueryString,
+  toggleFacetSelection,
+  isFacetSelected,
+  clearFilters,
+  toSearchQuery,
+  type SearchPageState,
+  type RawSearchParams,
+  type FacetBucketRef,
+} from "./search-params"
+
+export { type SortOptions } from "../lib/sort-products"

package/src/tracking/chatgpt-pixel.tsx

@@ -1,99 +1,99 @@
-"use client"
-
-import Script from "next/script"
-
-import { adsConsentSnippet } from "./consent"
-import { jsStringLiteral } from "./inline-script"
-
-/**
- * ChatGptPixel — the OpenAI measurement pixel, the ChatGPT Ads twin of
- * <MetaPixel> and <TikTokPixel>.
- *
- * The loader is OpenAI's own, verbatim from
- * https://developers.openai.com/ads/measurement-pixel: a command queue on
- * `window.oaiq` that buffers calls until the SDK arrives from
- * bzrcdn.openai.com, injected with `<Script strategy="afterInteractive">`.
- *
- * CONSENT IS CLOSED BEFORE INIT, and that order is the whole point. Their
- * consent default is TRUE, so an unconsented visitor is measured unless we
- * say otherwise first:
- *
- *     oaiq("consent", false)   // queued BEFORE init — no pings
- *     oaiq("init", { pixelId })
- *     oaiq("consent", true)    // only once the visitor accepted
- *
- * The script is LOADED either way, like the Meta and TikTok gates beside
- * it, so a later grant costs no round trip. But the page view is fired
- * only AFTER a grant, and that is deliberate rather than cautious: their
- * docs state that with consent false the pixel sends no measurement
- * pings, and they do NOT document whether a call made while consent was
- * false is released on a later grant. TikTok documents exactly that
- * (`holdConsent` queues, `grantConsent` flushes) and our TikTok gate
- * relies on it. Nothing here relies on behaviour OpenAI has not written
- * down: an unconsented page view is not sent, and not counted on later.
- *
- * The decision is the store's default overridden by the visitor's stored
- * choice (`adsConsentSnippet`), resolved inside the snippet before anything
- * can be sent: a store that collects consent starts closed, a store with
- * no consent gate starts open, the cookie winning either way. Live changes
- * arrive through `applyConsent()` in ./consent.ts — there is no cookie
- * watcher. `consentRequired` is `tracking.consent_required`, passed by
- * <StorefrontTags>, and required for the reason <ConsentInit> gives.
- *
- * The page view is ours to fire at all: their pixel sends nothing at init,
- * unlike Meta's and TikTok's base code.
- *
- * Their SDK also captures `oppref` off the landing URL into a first-party
- * `__oppref` cookie by itself. Our attribution module captures the same
- * parameter into `_1c_oppref` independently, so the server-side
- * Conversions API event can carry the click even on a visit where this
- * script never loaded at all.
- *
- * Renders nothing when `pixelId` is falsy, so a layout can mount it
- * unconditionally.
- */
-export function ChatGptPixel({
-  pixelId,
-  consentRequired,
-}: {
-  pixelId?: string
-  /** `tracking.consent_required`: does this store collect consent before it tracks? */
-  consentRequired: boolean
-}) {
-  if (!pixelId) return null
-
-  const id = jsStringLiteral(pixelId)
-
-  const initSnippet = `
-(function (w, d, s, u) {
-  if (w.oaiq) return;
-  var q = function () { q.q.push(arguments); };
-  q.q = [];
-  w.oaiq = q;
-  var js = d.createElement(s);
-  js.async = true;
-  js.src = u;
-  var f = d.getElementsByTagName(s)[0];
-  f.parentNode.insertBefore(js, f);
-})(window, document, "script", "https://bzrcdn.openai.com/sdk/oaiq.min.js");
-
-oaiq("consent", false);
-oaiq("init", { pixelId: ${id} });
-
-(function (d) {
-  ${adsConsentSnippet(consentRequired, "d")}
-  if (ads) {
-    oaiq("consent", true);
-    oaiq("measure", "page_viewed", { type: "contents" });
-  }
-})(document);
-`.trim()
-
-  return (
-    <Script
-      id="chatgpt-pixel-init"
-      strategy="afterInteractive"
-      dangerouslySetInnerHTML={{ __html: initSnippet }}
-    />
-  )
-}
+"use client"
+
+import Script from "next/script"
+
+import { adsConsentSnippet } from "./consent"
+import { jsStringLiteral } from "./inline-script"
+
+/**
+ * ChatGptPixel — the OpenAI measurement pixel, the ChatGPT Ads twin of
+ * <MetaPixel> and <TikTokPixel>.
+ *
+ * The loader is OpenAI's own, verbatim from
+ * https://developers.openai.com/ads/measurement-pixel: a command queue on
+ * `window.oaiq` that buffers calls until the SDK arrives from
+ * bzrcdn.openai.com, injected with `<Script strategy="afterInteractive">`.
+ *
+ * CONSENT IS CLOSED BEFORE INIT, and that order is the whole point. Their
+ * consent default is TRUE, so an unconsented visitor is measured unless we
+ * say otherwise first:
+ *
+ *     oaiq("consent", false)   // queued BEFORE init — no pings
+ *     oaiq("init", { pixelId })
+ *     oaiq("consent", true)    // only once the visitor accepted
+ *
+ * The script is LOADED either way, like the Meta and TikTok gates beside
+ * it, so a later grant costs no round trip. But the page view is fired
+ * only AFTER a grant, and that is deliberate rather than cautious: their
+ * docs state that with consent false the pixel sends no measurement
+ * pings, and they do NOT document whether a call made while consent was
+ * false is released on a later grant. TikTok documents exactly that
+ * (`holdConsent` queues, `grantConsent` flushes) and our TikTok gate
+ * relies on it. Nothing here relies on behaviour OpenAI has not written
+ * down: an unconsented page view is not sent, and not counted on later.
+ *
+ * The decision is the store's default overridden by the visitor's stored
+ * choice (`adsConsentSnippet`), resolved inside the snippet before anything
+ * can be sent: a store that collects consent starts closed, a store with
+ * no consent gate starts open, the cookie winning either way. Live changes
+ * arrive through `applyConsent()` in ./consent.ts — there is no cookie
+ * watcher. `consentRequired` is `tracking.consent_required`, passed by
+ * <StorefrontTags>, and required for the reason <ConsentInit> gives.
+ *
+ * The page view is ours to fire at all: their pixel sends nothing at init,
+ * unlike Meta's and TikTok's base code.
+ *
+ * Their SDK also captures `oppref` off the landing URL into a first-party
+ * `__oppref` cookie by itself. Our attribution module captures the same
+ * parameter into `_1c_oppref` independently, so the server-side
+ * Conversions API event can carry the click even on a visit where this
+ * script never loaded at all.
+ *
+ * Renders nothing when `pixelId` is falsy, so a layout can mount it
+ * unconditionally.
+ */
+export function ChatGptPixel({
+  pixelId,
+  consentRequired,
+}: {
+  pixelId?: string
+  /** `tracking.consent_required`: does this store collect consent before it tracks? */
+  consentRequired: boolean
+}) {
+  if (!pixelId) return null
+
+  const id = jsStringLiteral(pixelId)
+
+  const initSnippet = `
+(function (w, d, s, u) {
+  if (w.oaiq) return;
+  var q = function () { q.q.push(arguments); };
+  q.q = [];
+  w.oaiq = q;
+  var js = d.createElement(s);
+  js.async = true;
+  js.src = u;
+  var f = d.getElementsByTagName(s)[0];
+  f.parentNode.insertBefore(js, f);
+})(window, document, "script", "https://bzrcdn.openai.com/sdk/oaiq.min.js");
+
+oaiq("consent", false);
+oaiq("init", { pixelId: ${id} });
+
+(function (d) {
+  ${adsConsentSnippet(consentRequired, "d")}
+  if (ads) {
+    oaiq("consent", true);
+    oaiq("measure", "page_viewed", { type: "contents" });
+  }
+})(document);
+`.trim()
+
+  return (
+    <Script
+      id="chatgpt-pixel-init"
+      strategy="afterInteractive"
+      dangerouslySetInnerHTML={{ __html: initSnippet }}
+    />
+  )
+}