@cartbase/storefront 0.15.0 → 0.16.0

package/src/products/product-template.tsx

@@ -1,149 +1,162 @@
-/**
- * Full PDP layout — ported from
- * `@1click/ui/src/products/product-template.tsx` (v2.3.1). Data seam:
- * `region`/`countryCode` (Medusa region routing) are replaced by
- * `client` + `pricingContext`; the cart seam (`addToCart`/`openCart`)
- * threads through to `ProductActions` (see product-actions.tsx for the
- * seam rationale). Layout — sticky info column, scrolling gallery, sticky
- * actions column, related strip — unchanged.
- *
- * Server component: fetch the product in the page (`retrieveProduct` by
- * handle with the pricing context) and pass it in; the wrapper re-fetches
- * live prices inside Suspense.
- */
-import { Suspense } from "react"
-import { notFound } from "next/navigation"
-
-import type { StorefrontClient } from "../api/http"
-import type { PricingContextQuery } from "../api/types"
-import type { StoreProduct, StoreProductVariant } from "../api/products"
-import { ImageGallery } from "./image-gallery"
-import { ProductActions, type AddToCartInput } from "./product-actions"
-import { ProductTabs, type ProductSection } from "./product-tabs"
-import type { ProductPromise } from "./product-promises"
-import type { ProductLabels } from "./labels"
-import { RelatedProducts } from "./related-products"
-import { ProductInfo } from "./product-info"
-import { ProductActionsWrapper } from "./product-actions-wrapper"
-
-type ProductTemplateProps = {
-  client: StorefrontClient
-  product: StoreProduct
-  /** Pricing context (currency_code/region_id) for actions + related. */
-  pricingContext?: PricingContextQuery
-  addToCart: (input: AddToCartInput) => Promise<void>
-  onAddToCart?: (product: StoreProduct, variant: StoreProductVariant) => void
-  openCart?: () => void
-  /**
-   * The store's delivery, exchange and return promises, shown in the
-   * accordion. No default: with none, that section does not exist, because
-   * the library cannot promise anything on a merchant's behalf.
-   */
-  promises?: ProductPromise[]
-  /**
-   * The store's product pack, REQUIRED even when a `StorefrontLocaleProvider`
-   * is mounted: the related-products strip is a SERVER component and a
-   * server component cannot read a client context, so its heading stays
-   * English unless the pack arrives as a prop. Until 2026-09-13 this
-   * template did not accept one at all and did not pass one down, which made
-   * that strip untranslatable without ejecting the file (Alexander found it
-   * on evoo: a Bulgarian page ending in "Related products / You might also
-   * want to check out these products"). Optional until 2026-09-14, which is
-   * how a page could still forget it; now the build refuses the page.
-   * Pass `STORE_LOCALE.products` (`en.products` for an English store).
-   */
-  labels: ProductLabels
-  /** Drop the physical-facts section even for a product that has facts. */
-  hideSpecs?: boolean
-  /** Anything else the store wants in the accordion, appended in order. */
-  sections?: ProductSection[]
-}
-
-export function ProductTemplate({
-  client,
-  product,
-  pricingContext,
-  addToCart,
-  onAddToCart,
-  openCart,
-  promises,
-  labels,
-  hideSpecs,
-  sections,
-}: ProductTemplateProps) {
-  if (!product || !product.id) {
-    return notFound()
-  }
-
-  const images = product.images ?? []
-
-  return (
-    <>
-      <div
-        className="max-w-7xl mx-auto px-4 flex flex-col sm:flex-row sm:items-start py-6 relative"
-        data-testid="product-container"
-      >
-        <div className="flex flex-col sm:sticky sm:top-48 sm:py-0 sm:max-w-[300px] w-full py-8 gap-y-6">
-          <ProductInfo product={product} />
-          <ProductTabs
-            product={product}
-            promises={promises}
-            hideSpecs={hideSpecs}
-            sections={sections}
-          />
-        </div>
-        <div className="block w-full relative">
-          <ImageGallery images={images} />
-        </div>
-        <div className="flex flex-col sm:sticky sm:top-48 sm:py-0 sm:max-w-[300px] w-full py-8 gap-y-12">
-          <Suspense
-            fallback={
-              <ProductActions
-                disabled={true}
-                product={product}
-                addToCart={addToCart}
-                onAddToCart={onAddToCart}
-                openCart={openCart}
-              />
-            }
-          >
-            <ProductActionsWrapper
-              client={client}
-              id={product.id}
-              pricingContext={pricingContext}
-              addToCart={addToCart}
-              onAddToCart={onAddToCart}
-              openCart={openCart}
-            />
-          </Suspense>
-        </div>
-      </div>
-      <div
-        className="max-w-7xl mx-auto px-4 my-16 sm:my-32"
-        data-testid="related-products-container"
-      >
-        <Suspense
-          fallback={
-            <div className="grid grid-cols-2 sm:grid-cols-4 gap-4">
-              {Array.from({ length: 4 }).map((_, i) => (
-                <div
-                  key={i}
-                  className="aspect-[9/16] bg-muted animate-pulse rounded-lg"
-                />
-              ))}
-            </div>
-          }
-        >
-          <RelatedProducts
-            client={client}
-            product={product}
-            pricingContext={pricingContext}
-            labels={labels}
-          />
-        </Suspense>
-      </div>
-    </>
-  )
-}
-
-export { type ProductTemplateProps }
+/**
+ * Full PDP layout — ported from
+ * `@1click/ui/src/products/product-template.tsx` (v2.3.1). Data seam:
+ * `region`/`countryCode` (Medusa region routing) are replaced by
+ * `client` + `pricingContext`; the cart seam (`addToCart`/`openCart`)
+ * threads through to `ProductActions` (see product-actions.tsx for the
+ * seam rationale). Layout — sticky info column, scrolling gallery, sticky
+ * actions column, related strip — unchanged.
+ *
+ * Server component: fetch the product in the page (`retrieveProduct` by
+ * handle with the pricing context) and pass it in; the wrapper re-fetches
+ * live prices inside Suspense.
+ */
+import { Suspense, type ComponentType } from "react"
+import { notFound } from "next/navigation"
+
+import type { StorefrontClient } from "../api/http"
+import type { PricingContextQuery } from "../api/types"
+import type { StoreProduct, StoreProductVariant } from "../api/products"
+import { ImageGallery } from "./image-gallery"
+import { ProductActions, type AddToCartInput } from "./product-actions"
+import { ProductTabs, type ProductSection } from "./product-tabs"
+import type { ProductPromise } from "./product-promises"
+import type { ProductLabels } from "./labels"
+import { RelatedProducts } from "./related-products"
+import { ProductInfo } from "./product-info"
+import { ProductActionsWrapper } from "./product-actions-wrapper"
+
+type ProductTemplateProps = {
+  client: StorefrontClient
+  product: StoreProduct
+  /** Pricing context (currency_code/region_id) for actions + related. */
+  pricingContext?: PricingContextQuery
+  addToCart: (input: AddToCartInput) => Promise<void>
+  onAddToCart?: (product: StoreProduct, variant: StoreProductVariant) => void
+  openCart?: () => void
+  /**
+   * The store's delivery, exchange and return promises, shown in the
+   * accordion. No default: with none, that section does not exist, because
+   * the library cannot promise anything on a merchant's behalf.
+   */
+  promises?: ProductPromise[]
+  /**
+   * The store's product pack, REQUIRED even when a `StorefrontLocaleProvider`
+   * is mounted: the related-products strip is a SERVER component and a
+   * server component cannot read a client context, so its heading stays
+   * English unless the pack arrives as a prop. Until 2026-09-13 this
+   * template did not accept one at all and did not pass one down, which made
+   * that strip untranslatable without ejecting the file (Alexander found it
+   * on evoo: a Bulgarian page ending in "Related products / You might also
+   * want to check out these products"). Optional until 2026-09-14, which is
+   * how a page could still forget it; now the build refuses the page.
+   * Pass `STORE_LOCALE.products` (`en.products` for an English store).
+   */
+  labels: ProductLabels
+  /** Drop the physical-facts section even for a product that has facts. */
+  hideSpecs?: boolean
+  /** 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`).
+   */
+  initialVariantId?: string | null
+  /** The store's own card for the related strip; the library's preview without it. */
+  renderProduct?: ComponentType<{ product: StoreProduct }>
+}
+
+export function ProductTemplate({
+  client,
+  product,
+  pricingContext,
+  addToCart,
+  onAddToCart,
+  openCart,
+  promises,
+  labels,
+  hideSpecs,
+  sections,
+  initialVariantId,
+  renderProduct,
+}: ProductTemplateProps) {
+  if (!product || !product.id) {
+    return notFound()
+  }
+
+  const images = product.images ?? []
+
+  return (
+    <>
+      <div
+        className="max-w-7xl mx-auto px-4 flex flex-col sm:flex-row sm:items-start py-6 relative"
+        data-testid="product-container"
+      >
+        <div className="flex flex-col sm:sticky sm:top-48 sm:py-0 sm:max-w-[300px] w-full py-8 gap-y-6">
+          <ProductInfo product={product} />
+          <ProductTabs
+            product={product}
+            promises={promises}
+            hideSpecs={hideSpecs}
+            sections={sections}
+          />
+        </div>
+        <div className="block w-full relative">
+          <ImageGallery images={images} />
+        </div>
+        <div className="flex flex-col sm:sticky sm:top-48 sm:py-0 sm:max-w-[300px] w-full py-8 gap-y-12">
+          <Suspense
+            fallback={
+              <ProductActions
+                disabled={true}
+                product={product}
+                initialVariantId={initialVariantId}
+                addToCart={addToCart}
+                onAddToCart={onAddToCart}
+                openCart={openCart}
+              />
+            }
+          >
+            <ProductActionsWrapper
+              client={client}
+              id={product.id}
+              pricingContext={pricingContext}
+              initialVariantId={initialVariantId}
+              addToCart={addToCart}
+              onAddToCart={onAddToCart}
+              openCart={openCart}
+            />
+          </Suspense>
+        </div>
+      </div>
+      <div
+        className="max-w-7xl mx-auto px-4 my-16 sm:my-32"
+        data-testid="related-products-container"
+      >
+        <Suspense
+          fallback={
+            <div className="grid grid-cols-2 sm:grid-cols-4 gap-4">
+              {Array.from({ length: 4 }).map((_, i) => (
+                <div
+                  key={i}
+                  className="aspect-[9/16] bg-muted animate-pulse rounded-lg"
+                />
+              ))}
+            </div>
+          }
+        >
+          <RelatedProducts
+            client={client}
+            product={product}
+            pricingContext={pricingContext}
+            labels={labels}
+            renderProduct={renderProduct}
+          />
+        </Suspense>
+      </div>
+    </>
+  )
+}
+
+export { type ProductTemplateProps }

package/src/products/use-product-actions.ts

@@ -0,0 +1,164 @@
+"use client"
+
+/**
+ * The product page contract, as a headless hook: the BEHAVIOUR of a
+ * product's buy panel, with no markup, so a store draws its own panel and
+ * inherits the rules, and the package's own `ProductActions` is one more
+ * consumer of it. The contract (docs/storefront/components.md, "The product
+ * page contract"):
+ *
+ *   1. The address is the state: `?variant=<digits>` (variant-url.ts).
+ *   2. The first paint is right: the page passes the address's variant in
+ *      as `initialVariantId`, so the server renders that variant's price,
+ *      code and stock and nothing flashes.
+ *   3. A switch is a browser event: the address is rewritten with the
+ *      browser's own history call, which Next's router picks up, and NO
+ *      server render runs. Going through the router made every click a
+ *      navigation: the address lagged a whole page render behind the click
+ *      and a fast second click left it on the first variant (2026-09-15).
+ *   4. The default is the merchant's: each option's first value, together.
+ *   5. The server is asked only for what needs it: adding to the cart.
+ *
+ * Stock is the server's `in_stock` predicate on the variant, read here and
+ * never re-derived; a 400 `insufficient_inventory` on add flips the panel
+ * to out of stock until the choice changes.
+ */
+import { useCallback, useEffect, useMemo, useState } from "react"
+import { usePathname, useRouter, useSearchParams } from "next/navigation"
+
+import type { StoreProduct, StoreProductVariant } from "../api/products"
+import { getProductPrice, type VariantPrice } from "../lib/get-product-price"
+import { findMatchingVariant, optionsAsKeymap, type OptionChoices } from "./variant-matching"
+import { VARIANT_PARAM, defaultVariant, findVariantByParam, variantHref, variantParamValue } from "./variant-url"
+
+/** Input the host's cart seam receives on add. */
+export type AddToCartInput = {
+  variantId: string
+  quantity: number
+}
+
+export interface UseProductActionsInput {
+  product: StoreProduct
+  /**
+   * The cart seam: the host's server action or cart call. May throw a
+   * `StoreApiError`; `insufficient_inventory` is handled here.
+   */
+  addToCart: (input: AddToCartInput) => Promise<void>
+  /**
+   * The variant the address named when the page was rendered on the
+   * server (`searchParams.variant`, digits or whole id). Passing it is what
+   * makes the first paint right; without it the merchant's default is chosen.
+   */
+  initialVariantId?: string | null
+  /** Fired after a successful add (analytics). */
+  onAddToCart?: (product: StoreProduct, variant: StoreProductVariant) => void
+  /** Open the host's cart drawer after a successful add. */
+  openCart?: () => void
+  /** Write the choice into the address. On by default; off for a panel outside the product page (a quick-buy card). */
+  syncAddress?: boolean
+}
+
+export interface ProductActionsState {
+  /** The variant the choices name; undefined until every option is chosen. */
+  variant: StoreProductVariant | undefined
+  /** Chosen option values by option id. */
+  chosen: OptionChoices
+  choose: (optionId: string, value: string) => void
+  quantity: number
+  setQuantity: (quantity: number) => void
+  /** The server's availability for the chosen variant; false with no variant. */
+  inStock: boolean
+  isAdding: boolean
+  /** The chosen variant's price, or the cheapest while none is chosen. */
+  price: VariantPrice | null
+  /** True when every option has a value that names a real variant. */
+  isValidVariant: boolean
+  /** Add the chosen variant at the chosen quantity. Resolves after the host's cart seam. */
+  add: () => Promise<void>
+}
+
+export function useProductActions({
+  product,
+  addToCart,
+  initialVariantId,
+  onAddToCart,
+  openCart,
+  syncAddress = true,
+}: UseProductActionsInput): ProductActionsState {
+  const router = useRouter()
+  const pathname = usePathname()
+  const searchParams = useSearchParams()
+  const variants = product.variants ?? []
+
+  const [chosen, setChosen] = useState<OptionChoices>(() => {
+    const start = findVariantByParam(variants, initialVariantId) ?? defaultVariant(product)
+    return start ? optionsAsKeymap(start.options) ?? {} : {}
+  })
+  const [quantity, setQuantityState] = useState(1)
+  const [isAdding, setIsAdding] = useState(false)
+  const [exhausted, setExhausted] = useState(false)
+
+  const variant = useMemo(
+    () => (variants.length === 1 ? variants[0] : findMatchingVariant(variants, chosen)),
+    [variants, chosen]
+  )
+
+  const choose = useCallback((optionId: string, value: string) => {
+    setExhausted(false)
+    setChosen((prev) => ({ ...prev, [optionId]: value }))
+  }, [])
+
+  const setQuantity = useCallback((next: number) => {
+    setQuantityState(Math.max(1, Math.floor(next) || 1))
+  }, [])
+
+  // Rule 3: the address follows the choice, in the browser alone.
+  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 inStock = useMemo(() => {
+    if (!variant) return false
+    if (typeof variant.in_stock === "boolean") return variant.in_stock && !exhausted
+    // A wire without the predicate: optimistic, the server still enforces stock on add.
+    if (!variant.manage_inventory || variant.allow_backorder) return true
+    return !exhausted
+  }, [variant, exhausted])
+
+  const { cheapestPrice, variantPrice } = getProductPrice({ product, variantId: variant?.id })
+  const price = variant ? variantPrice : cheapestPrice
+
+  const add = useCallback(async () => {
+    if (!variant?.id) return
+    setIsAdding(true)
+    try {
+      await addToCart({ variantId: variant.id, quantity })
+    } catch (e) {
+      if ((e as { code?: string } | null)?.code === "insufficient_inventory") {
+        setExhausted(true)
+        return
+      }
+      throw e
+    } finally {
+      setIsAdding(false)
+    }
+    onAddToCart?.(product, variant)
+    openCart?.()
+    router.refresh()
+  }, [variant, quantity, addToCart, onAddToCart, openCart, product, router])
+
+  return {
+    variant,
+    chosen,
+    choose,
+    quantity,
+    setQuantity,
+    inStock,
+    isAdding,
+    price,
+    isValidVariant: Boolean(variant),
+    add,
+  }
+}

package/src/products/variant-url.ts

@@ -0,0 +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()}`
+}

package/src/store/paginated-products.tsx

@@ -48,8 +48,9 @@ export async function PaginatedProducts({
   client: StorefrontClient
   sortBy?: SortOptions
   page: number
-  /** Filters by PRIMARY collection (`products.collection_id`) — for the
-   *  membership join use collection-template / `listCollectionProducts`. */
+  /** Filters by collection MEMBERSHIP since 2026-09-15 (a product in three
+   *  collections is listed under all three). For the collection's OWN order
+   *  use collection-template / `listCollectionProducts`. */
   collectionId?: string
   categoryId?: string
   productsIds?: string[]