@cartbase/storefront 0.17.0 → 0.18.0

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

@@ -1,73 +1,73 @@
-/**
- * @cartbase/storefront/reviews-ui — verified-purchase review components.
- * NEW family (no @1click/ui counterpart): ported/adapted from the Alenika
- * production storefront (src/components/product/reviews-list.tsx + the
- * /review/[token] page + review-form.tsx) over the batch-9 SDK
- * (`api/reviews` — DTOs mirror alenika/src/lib/reviews-api.ts verbatim).
- * Contracts: docs/storefront/components.md + docs/storefront/reviews.md.
- */
-export {
-  defaultReviewsUiLabels,
-  type ReviewsUiLabels,
-} from "./labels"
-
-export {
-  formatLabel,
-  reviewDisplayName,
-  firstNameOf,
-  formatReviewDate,
-  sortParamsFor,
-  reviewCountLabel,
-  checkFileForUpload,
-  MAX_IMAGES,
-  MAX_VIDEOS,
-  MAX_BODY,
-  MAX_IMAGE_BYTES,
-  MAX_VIDEO_BYTES,
-  MAX_VIDEO_SECONDS,
-  IMAGE_MIME,
-  VIDEO_MIME,
-  UPLOAD_ACCEPT,
-  type ReviewSortKey,
-  type FileCheckInput,
-  type FileCheckResult,
-} from "./helpers"
-
-export {
-  resolveWizardEntry,
-  submitErrorKeyFor,
-  canSubmitRating,
-  type WizardEntry,
-  type WizardStep,
-  type SubmitErrorKey,
-} from "./wizard-state"
-
-export {
-  StarRow,
-  StarBadge,
-  RatingDistribution,
-  type StarBadgeProps,
-  type RatingDistributionProps,
-} from "./star-badge"
-
-export {
-  ReviewList,
-  ReviewLightbox,
-  type ReviewListProps,
-} from "./review-list"
-
-export { ReviewWidget, type ReviewWidgetProps } from "./review-widget"
-
-export {
-  ReviewWizard,
-  ReviewWizardForm,
-  type ReviewWizardProps,
-} from "./review-wizard"
-
-export {
-  ReviewPhotoUpload,
-  readyMedia,
-  putToSignedUrl,
-  type LocalMedia,
-  type ReviewPhotoUploadProps,
-} from "./photo-upload"
+/**
+ * @cartbase/storefront/reviews-ui — verified-purchase review components.
+ * NEW family (no @1click/ui counterpart): ported/adapted from the Alenika
+ * production storefront (src/components/product/reviews-list.tsx + the
+ * /review/[token] page + review-form.tsx) over the batch-9 SDK
+ * (`api/reviews` — DTOs mirror alenika/src/lib/reviews-api.ts verbatim).
+ * Contracts: docs/storefront/components.md + docs/storefront/reviews.md.
+ */
+export {
+  defaultReviewsUiLabels,
+  type ReviewsUiLabels,
+} from "./labels"
+
+export {
+  formatLabel,
+  reviewDisplayName,
+  firstNameOf,
+  formatReviewDate,
+  sortParamsFor,
+  reviewCountLabel,
+  checkFileForUpload,
+  MAX_IMAGES,
+  MAX_VIDEOS,
+  MAX_BODY,
+  MAX_IMAGE_BYTES,
+  MAX_VIDEO_BYTES,
+  MAX_VIDEO_SECONDS,
+  IMAGE_MIME,
+  VIDEO_MIME,
+  UPLOAD_ACCEPT,
+  type ReviewSortKey,
+  type FileCheckInput,
+  type FileCheckResult,
+} from "./helpers"
+
+export {
+  resolveWizardEntry,
+  submitErrorKeyFor,
+  canSubmitRating,
+  type WizardEntry,
+  type WizardStep,
+  type SubmitErrorKey,
+} from "./wizard-state"
+
+export {
+  StarRow,
+  StarBadge,
+  RatingDistribution,
+  type StarBadgeProps,
+  type RatingDistributionProps,
+} from "./star-badge"
+
+export {
+  ReviewList,
+  ReviewLightbox,
+  type ReviewListProps,
+} from "./review-list"
+
+export { ReviewWidget, type ReviewWidgetProps } from "./review-widget"
+
+export {
+  ReviewWizard,
+  ReviewWizardForm,
+  type ReviewWizardProps,
+} from "./review-wizard"
+
+export {
+  ReviewPhotoUpload,
+  readyMedia,
+  putToSignedUrl,
+  type LocalMedia,
+  type ReviewPhotoUploadProps,
+} from "./photo-upload"

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"