@cartbase/storefront 0.15.0 → 0.17.0

package/src/cart-drawer/cross-sell-sidebar.tsx

@@ -1,6 +1,6 @@
 "use client"
 
-import Image from "next/image"
+import { StoreImage as Image } from "../lib/media-image"
 import Link from "next/link"
 
 import type { StoreProduct } from "../api/products"

package/src/cart-drawer/free-gift.tsx

@@ -1,6 +1,6 @@
 "use client"
 
-import Image from "next/image"
+import { StoreImage as Image } from "../lib/media-image"
 
 import { convertToLocale } from "../lib/money"
 import { useCartDrawer } from "./context"

package/src/cart-drawer/item/index.tsx

@@ -1,6 +1,6 @@
 "use client"
 
-import Image from "next/image"
+import { StoreImage as Image } from "../../lib/media-image"
 import Link from "next/link"
 import { type ReactNode } from "react"
 

package/src/cart-drawer/item/upsell.tsx

@@ -1,6 +1,6 @@
 "use client"
 
-import Image from "next/image"
+import { StoreImage as Image } from "../../lib/media-image"
 import Link from "next/link"
 
 import { convertToLocale } from "../../lib/money"

package/src/lib/media-image.tsx

@@ -0,0 +1,39 @@
+import NextImage, { type ImageProps } from "next/image"
+
+/**
+ * The store's picture element (store-speed-law card, step 3, 2026-09-15).
+ *
+ * Product pictures live on the Cartbase media CDN, and Next resizes them on
+ * the store's own project, per device and in the modern formats, which the
+ * scaffold allows through `images.remotePatterns` (next.config.ts). The
+ * scaffold used to ship `images.unoptimized: true` instead, so no picture
+ * was ever resized: a phone downloaded the merchant's full upload.
+ *
+ * A picture from any other host (a catalogue not yet rehosted, a demo
+ * placeholder, a merchant's own asset host) renders as it is instead of
+ * failing the page: Next refuses to resize a host the config does not
+ * list, so this element switches resizing off for those. A merchant who
+ * adds their host to `remotePatterns` gets resizing there too by passing
+ * `unoptimized={false}` where they render it, or by using `next/image`
+ * directly.
+ */
+
+/** The public base of the media CDN (REGISTRY.md, CDN domain). */
+export const MEDIA_HOST = "cartbase.cloud"
+
+/** Is this picture served by the media CDN (or by the app itself)? */
+export function isResizableSrc(src: ImageProps["src"]): boolean {
+  if (typeof src !== "string") return true
+  if (src.startsWith("/")) return true
+  try {
+    const host = new URL(src).hostname
+    return host === MEDIA_HOST || host.endsWith(`.${MEDIA_HOST}`)
+  } catch {
+    return false
+  }
+}
+
+export function StoreImage(props: ImageProps) {
+  const unoptimized = props.unoptimized ?? !isResizableSrc(props.src)
+  return <NextImage {...props} unoptimized={unoptimized} />
+}

package/src/locales/bg.ts

@@ -28,6 +28,9 @@ export const bg: StorefrontLocale = {
     selectVariant: "Изберете вариант",
     outOfStock: "Изчерпан",
     addToCart: "Добави в кошницата",
+    quantity: "Количество",
+    decreaseQuantity: "По-малко",
+    increaseQuantity: "Повече",
     from: "От",
     original: "Оригинална цена:",
     productInformation: "Информация за продукта",

package/src/locales/es.ts

@@ -34,6 +34,9 @@ export const es: StorefrontLocale = {
     selectVariant: "Elige variante",
     outOfStock: "Agotado",
     addToCart: "Añadir al carrito",
+    quantity: "Cantidad",
+    decreaseQuantity: "Menos",
+    increaseQuantity: "Más",
     from: "Desde",
     original: "Antes:",
     productInformation: "Información del producto",

package/src/order/order-item.tsx

@@ -1,4 +1,4 @@
-import Image from "next/image"
+import { StoreImage as Image } from "../lib/media-image"
 import { ImageOff } from "lucide-react"
 import { Price } from "../lib/price"
 import { variantCaption } from "../lib/variant-caption"

package/src/products/image-gallery.tsx

@@ -5,7 +5,7 @@
  * (`@cartbase/storefront/api/products`; images arrive rank-ordered from the
  * API). Server-safe.
  */
-import Image from "next/image"
+import { StoreImage as Image } from "../lib/media-image"
 import type { StoreProductImage } from "../api/products"
 
 type ImageGalleryProps = {

package/src/products/index.ts

@@ -26,6 +26,20 @@ export {
   type PurchaseOptionsLabels,
 } from "./purchase-options"
 export { ImageGallery, type ImageGalleryProps } from "./image-gallery"
+// The product page contract: the address is the state, the default is the
+// merchant's, a switch is a browser event (variant-url + use-product-actions).
+export {
+  VARIANT_PARAM,
+  variantParamValue,
+  findVariantByParam,
+  defaultVariant,
+  variantHref,
+} from "./variant-url"
+export {
+  useProductActions,
+  type UseProductActionsInput,
+  type ProductActionsState,
+} from "./use-product-actions"
 export {
   ProductActions,
   type ProductActionsProps,

package/src/products/labels.ts

@@ -9,6 +9,10 @@ export type ProductLabels = {
   selectVariant: string
   outOfStock: string
   addToCart: string
+  /** The quantity stepper of the buy panel and its two controls. */
+  quantity: string
+  decreaseQuantity: string
+  increaseQuantity: string
   from: string
   original: string
   productInformation: string
@@ -39,6 +43,9 @@ export const defaultProductLabels: ProductLabels = {
   selectVariant: "Select variant",
   outOfStock: "Out of stock",
   addToCart: "Add to cart",
+  quantity: "Quantity",
+  decreaseQuantity: "Fewer",
+  increaseQuantity: "More",
   from: "From",
   original: "Original:",
   productInformation: "Product Information",

package/src/products/product-actions-wrapper.tsx

@@ -1,58 +1,62 @@
-/**
- * Fresh-price fetch wrapper for ProductActions — ported from
- * `@1click/ui/src/products/product-actions-wrapper.tsx` (v2.3.1). Data
- * seam: the Medusa `listProducts({id})` + region-priced fetch becomes
- * `api/products` `retrieveProduct(idOrHandle, pricingContext)` — the PDP
- * shell renders with the (possibly cached) product while this wrapper
- * re-fetches `calculated_price` with the live pricing context (and the
- * customer's Bearer JWT via the client, for group-aware B2B prices).
- *
- * Async server component — render inside `<Suspense>` with a disabled
- * `<ProductActions>` fallback (see ProductTemplate).
- */
-import type { StorefrontClient } from "../api/http"
-import type { PricingContextQuery } from "../api/types"
-import type { StoreProduct, StoreProductVariant } from "../api/products"
-import { retrieveProduct } from "../api/products"
-import { StoreApiError } from "../api/types"
-import { ProductActions, type AddToCartInput } from "./product-actions"
-
-type ProductActionsWrapperProps = {
-  client: StorefrontClient
-  /** Product id (`prod_…`) or handle. */
-  id: string
-  /** Pricing context so `calculated_price` is present for the price panel. */
-  pricingContext?: PricingContextQuery
-  addToCart: (input: AddToCartInput) => Promise<void>
-  onAddToCart?: (product: StoreProduct, variant: StoreProductVariant) => void
-  openCart?: () => void
-}
-
-export async function ProductActionsWrapper({
-  client,
-  id,
-  pricingContext,
-  addToCart,
-  onAddToCart,
-  openCart,
-}: ProductActionsWrapperProps) {
-  let product: StoreProduct
-  try {
-    const res = await retrieveProduct(client, id, pricingContext)
-    product = res.product
-  } catch (e) {
-    if (e instanceof StoreApiError && e.status === 404) return null
-    throw e
-  }
-
-  return (
-    <ProductActions
-      product={product}
-      addToCart={addToCart}
-      onAddToCart={onAddToCart}
-      openCart={openCart}
-    />
-  )
-}
-
-export { type ProductActionsWrapperProps }
+/**
+ * Fresh-price fetch wrapper for ProductActions — ported from
+ * `@1click/ui/src/products/product-actions-wrapper.tsx` (v2.3.1). Data
+ * seam: the Medusa `listProducts({id})` + region-priced fetch becomes
+ * `api/products` `retrieveProduct(idOrHandle, pricingContext)` — the PDP
+ * shell renders with the (possibly cached) product while this wrapper
+ * re-fetches `calculated_price` with the live pricing context (and the
+ * customer's Bearer JWT via the client, for group-aware B2B prices).
+ *
+ * Async server component — render inside `<Suspense>` with a disabled
+ * `<ProductActions>` fallback (see ProductTemplate).
+ */
+import type { StorefrontClient } from "../api/http"
+import type { PricingContextQuery } from "../api/types"
+import type { StoreProduct, StoreProductVariant } from "../api/products"
+import { retrieveProduct } from "../api/products"
+import { StoreApiError } from "../api/types"
+import { ProductActions, type AddToCartInput } from "./product-actions"
+
+type ProductActionsWrapperProps = {
+  client: StorefrontClient
+  /** Product id (`prod_…`) or handle. */
+  id: string
+  /** Pricing context so `calculated_price` is present for the price panel. */
+  pricingContext?: PricingContextQuery
+  /** The variant the address names; see the product page contract. */
+  initialVariantId?: string | null
+  addToCart: (input: AddToCartInput) => Promise<void>
+  onAddToCart?: (product: StoreProduct, variant: StoreProductVariant) => void
+  openCart?: () => void
+}
+
+export async function ProductActionsWrapper({
+  client,
+  id,
+  pricingContext,
+  initialVariantId,
+  addToCart,
+  onAddToCart,
+  openCart,
+}: ProductActionsWrapperProps) {
+  let product: StoreProduct
+  try {
+    const res = await retrieveProduct(client, id, pricingContext)
+    product = res.product
+  } catch (e) {
+    if (e instanceof StoreApiError && e.status === 404) return null
+    throw e
+  }
+
+  return (
+    <ProductActions
+      product={product}
+      initialVariantId={initialVariantId}
+      addToCart={addToCart}
+      onAddToCart={onAddToCart}
+      openCart={openCart}
+    />
+  )
+}
+
+export { type ProductActionsWrapperProps }

package/src/products/product-actions.tsx

@@ -1,31 +1,22 @@
 "use client"
 
 /**
- * PDP add-to-cart panel — ported from
- * `@1click/ui/src/products/product-actions.tsx` (v2.3.1).
+ * The package's default buy panel: options, price, quantity, the button,
+ * and the sticky bar on phones. Every rule of the product page contract
+ * lives in `useProductActions`; this file is only the markup, and a store
+ * that wants its own look draws its own panel on the same hook and
+ * inherits the same behaviour (evoo's `features/product/buy-box.tsx` is
+ * the reference).
  *
- * Data-seam adaptations (batch-10 port):
- * - `HttpTypes.*` → Cartbase SDK DTOs (`@cartbase/storefront/api/products`).
- * - The `addToCart` server action (Medusa js-sdk, cart-cookie owner) is now
- *   an injected prop: the host app wires it to its own cart orchestration
- *   (typically `api/carts` `addLineItem` + its cart-id cookie). Same for the
- *   cart drawer: `openCart` replaces the `useCartDrawer()` context import so
- *   the products family has no hard dependency on the cart-drawer family.
- * - `countryCode` (Medusa region routing) is dropped — Cartbase pricing
- *   context travels with the product fetch, and the host's `addToCart`
- *   closes over whatever routing it needs.
- * - Stock: the variant DTO carries `in_stock`, computed server-side by THE
- *   availability predicate — this component only reads it. The server still
- *   enforces stock at add (400 `insufficient_inventory` flips the button to
- *   the out-of-stock state). On a legacy wire without the field, managed
- *   variants fall back to the old optimistic behavior; richer DTOs carrying
- *   `inventory_quantity` keep the original quantity check.
- *
- * Variant matching is the extracted pure module `./variant-matching`
- * (handles Cartbase's option-value link shape).
+ * Until 2026-09-15 this panel carried the behaviour itself, and carried it
+ * wrong: it wrote the variant into the address through the router as
+ * `v_id=<whole key>`, so every click was a server render and the address
+ * lagged; it chose nothing on a product with several variants until the
+ * shopper clicked; and it added one unit, always. The hook fixed all three
+ * for every consumer at once.
  */
-import { usePathname, useRouter, useSearchParams } from "next/navigation"
-import { useEffect, useMemo, useRef, useState } from "react"
+import { useRef } from "react"
+import { Minus, Plus } from "lucide-react"
 
 import type { StoreProduct, StoreProductVariant } from "../api/products"
 import { useIntersection } from "../lib/hooks/use-intersection"
@@ -34,189 +25,125 @@ import { useProductLabels } from "./context"
 import { OptionSelect } from "./option-select"
 import { ProductPrice } from "./product-price"
 import { MobileActions } from "./mobile-actions"
-import { findMatchingVariant, optionsAsKeymap, optionsMatch } from "./variant-matching"
+import { useProductActions, type AddToCartInput } from "./use-product-actions"
 
-/** Input the host's cart seam receives on add. */
-export type AddToCartInput = {
-  variantId: string
-  quantity: number
-}
+export type { AddToCartInput }
 
 type ProductActionsProps = {
   product: StoreProduct
   /**
-   * The cart seam: called with the selected variant. Wire to the host's
-   * cart orchestration (`api/carts` `addLineItem` behind the host's cart-id
-   * storage). May throw `StoreApiError` — `insufficient_inventory` is
-   * handled here (button flips to out-of-stock).
+   * The cart seam: called with the selected variant and quantity. Wire to
+   * the host's cart orchestration (`api/carts` `addLineItem` behind the
+   * host's cart-id storage). May throw `StoreApiError`;
+   * `insufficient_inventory` is handled here (button flips to out of stock).
    */
   addToCart: (input: AddToCartInput) => Promise<void>
+  /**
+   * The variant the address names (`searchParams.variant`), passed from the
+   * page so the first paint is the right variant. See the product page
+   * contract in `use-product-actions.ts`.
+   */
+  initialVariantId?: string | null
   disabled?: boolean
   /** Fired after a successful add (analytics: trackAddToCart trio). */
   onAddToCart?: (product: StoreProduct, variant: StoreProductVariant) => void
   /** Open the host's cart drawer after a successful add. */
   openCart?: () => void
+  /** The quantity stepper; on by default. */
+  showQuantity?: boolean
 }
 
 export function ProductActions({
   product,
   addToCart,
+  initialVariantId,
   disabled,
   onAddToCart,
   openCart,
+  showQuantity = true,
 }: ProductActionsProps) {
   const labels = useProductLabels()
-  const router = useRouter()
-  const pathname = usePathname()
-  const searchParams = useSearchParams()
-
-  const [options, setOptions] = useState<Record<string, string | undefined>>({})
-  const [isAdding, setIsAdding] = useState(false)
-  // Set when the server rejected an add with `insufficient_inventory`
-  // (Cartbase exposes no inventory_quantity on the store surface — the server
-  // is the stock truth). Cleared when the selection changes.
-  const [stockExhausted, setStockExhausted] = useState(false)
-
-  useEffect(() => {
-    if (product.variants?.length === 1) {
-      const variantOptions = optionsAsKeymap(product.variants[0]?.options ?? null)
-      setOptions(variantOptions ?? {})
-    }
-  }, [product.variants])
-
-  const selectedVariant = useMemo(
-    () => findMatchingVariant(product.variants, options),
-    [product.variants, options]
-  )
-
-  const setOptionValue = (optionId: string, value: string) => {
-    setOptions((prev) => ({ ...prev, [optionId]: value }))
-  }
-
-  const isValidVariant = useMemo(() => {
-    return product.variants?.some((v) =>
-      optionsMatch(options, optionsAsKeymap(v.options))
-    )
-  }, [product.variants, options])
-
-  useEffect(() => {
-    setStockExhausted(false)
-  }, [selectedVariant?.id])
-
-  useEffect(() => {
-    const params = new URLSearchParams(searchParams.toString())
-    const value = isValidVariant ? selectedVariant?.id : null
-
-    if (params.get("v_id") === value) return
-
-    if (value) {
-      params.set("v_id", value)
-    } else {
-      params.delete("v_id")
-    }
-
-    router.replace(pathname + "?" + params.toString())
-  }, [selectedVariant, isValidVariant, searchParams, pathname, router])
-
-  const inStock = useMemo(() => {
-    if (!selectedVariant) return false
-    // The server computes THE availability predicate and emits it as
-    // `in_stock` on the variant DTO — read it, never re-derive it here
-    // (the hand-copied clauses this replaced could not see stock levels and
-    // showed an enabled Add to cart on sold-out variants until a 400).
-    if (typeof selectedVariant.in_stock === "boolean") {
-      return selectedVariant.in_stock && !stockExhausted
-    }
-    // Legacy wire (platform predates the field): optimistic fallback — the
-    // server still enforces stock on add.
-    if (!selectedVariant.manage_inventory) return true
-    if (selectedVariant.allow_backorder) return true
-    const qty = (selectedVariant as { inventory_quantity?: number })
-      .inventory_quantity
-    if (qty === undefined) return !stockExhausted
-    return qty > 0
-  }, [selectedVariant, stockExhausted])
+  const state = useProductActions({ product, addToCart, initialVariantId, onAddToCart, openCart })
+  const { variant, chosen, choose, quantity, setQuantity, inStock, isAdding, isValidVariant, add } = state
 
   const actionsRef = useRef<HTMLDivElement>(null)
   const inView = useIntersection(actionsRef, "0px")
-
-  const handleAddToCart = async () => {
-    if (!selectedVariant?.id) return
-
-    setIsAdding(true)
-    try {
-      await addToCart({ variantId: selectedVariant.id, quantity: 1 })
-    } catch (e) {
-      if ((e as { code?: string } | null)?.code === "insufficient_inventory") {
-        setStockExhausted(true)
-        return
-      }
-      throw e
-    } finally {
-      setIsAdding(false)
-    }
-
-    onAddToCart?.(product, selectedVariant)
-    openCart?.()
-    router.refresh()
-  }
+  const busy = !!disabled || isAdding
 
   return (
-    <>
-      <div className="flex flex-col gap-y-2" ref={actionsRef}>
-        <div>
-          {(product.variants?.length ?? 0) > 1 && (
-            <div className="flex flex-col gap-y-4">
-              {(product.options || []).map((option) => (
-                <div key={option.id}>
-                  <OptionSelect
-                    option={option}
-                    current={options[option.id]}
-                    updateOption={setOptionValue}
-                    title={option.title ?? ""}
-                    data-testid="product-options"
-                    disabled={!!disabled || isAdding}
-                  />
-                </div>
-              ))}
-              <div className="h-px bg-border" />
+    <div className="flex flex-col gap-y-2" ref={actionsRef}>
+      {(product.variants?.length ?? 0) > 1 && (
+        <div className="flex flex-col gap-y-4">
+          {(product.options || []).map((option) => (
+            <div key={option.id}>
+              <OptionSelect
+                option={option}
+                current={chosen[option.id]}
+                updateOption={choose}
+                title={option.title ?? ""}
+                data-testid="product-options"
+                disabled={busy}
+              />
             </div>
-          )}
+          ))}
+          <div className="h-px bg-border" />
         </div>
-
-        <ProductPrice product={product} variant={selectedVariant} />
-
-        <Button
-          onClick={handleAddToCart}
-          disabled={
-            !inStock ||
-            !selectedVariant ||
-            !!disabled ||
-            isAdding ||
-            !isValidVariant
-          }
-          className="w-full h-10"
-          data-testid="add-product-button"
-        >
-          {!selectedVariant && !options
-            ? labels.selectVariant
-            : !inStock || !isValidVariant
-              ? labels.outOfStock
-              : labels.addToCart}
-        </Button>
-        <MobileActions
-          product={product}
-          variant={selectedVariant}
-          options={options}
-          updateOptions={setOptionValue}
-          inStock={inStock}
-          handleAddToCart={handleAddToCart}
-          isAdding={isAdding}
-          show={!inView}
-          optionsDisabled={!!disabled || isAdding}
-        />
-      </div>
-    </>
+      )}
+
+      <ProductPrice product={product} variant={variant} />
+
+      {showQuantity && (
+        <div className="flex flex-col gap-y-2">
+          <span className="text-sm text-foreground">{labels.quantity}</span>
+          <div className="inline-flex w-fit items-stretch rounded-lg border border-border bg-card">
+            <button
+              type="button"
+              onClick={() => setQuantity(quantity - 1)}
+              aria-label={labels.decreaseQuantity}
+              disabled={quantity <= 1 || busy}
+              className="px-3 text-foreground transition-colors hover:bg-muted disabled:opacity-40"
+              data-testid="quantity-decrease"
+            >
+              <Minus className="size-4" aria-hidden />
+            </button>
+            <output className="min-w-10 py-2 text-center text-sm text-foreground" aria-live="polite" data-testid="quantity">
+              {quantity}
+            </output>
+            <button
+              type="button"
+              onClick={() => setQuantity(quantity + 1)}
+              aria-label={labels.increaseQuantity}
+              disabled={busy}
+              className="px-3 text-foreground transition-colors hover:bg-muted disabled:opacity-40"
+              data-testid="quantity-increase"
+            >
+              <Plus className="size-4" aria-hidden />
+            </button>
+          </div>
+        </div>
+      )}
+
+      <Button
+        onClick={add}
+        disabled={!inStock || !variant || busy || !isValidVariant}
+        className="w-full h-10"
+        data-testid="add-product-button"
+      >
+        {!variant ? labels.selectVariant : !inStock ? labels.outOfStock : labels.addToCart}
+      </Button>
+
+      <MobileActions
+        product={product}
+        variant={variant}
+        options={chosen}
+        updateOptions={choose}
+        inStock={inStock}
+        handleAddToCart={add}
+        isAdding={isAdding}
+        show={!inView}
+        optionsDisabled={busy}
+      />
+    </div>
   )
 }
 

package/src/products/product-info.tsx

@@ -1,8 +1,10 @@
 /**
  * PDP title/collection/description block — ported from
  * `@1click/ui/src/products/product-info.tsx` (v2.3.1). Data seam:
- * `HttpTypes.StoreProduct` → Cartbase `StoreProduct` (the collection embed is
- * `{id, title, handle}` — exactly what the link needs). Server-safe.
+ * `HttpTypes.StoreProduct` → Cartbase `StoreProduct`. The product carries
+ * EVERY collection it belongs to since 2026-09-15 (the membership join is
+ * the one store); the line above the title names the first of them, which is
+ * what the single `collection` object used to be. Server-safe.
  */
 import Link from "next/link"
 import type { StoreProduct } from "../api/products"
@@ -12,15 +14,18 @@ type ProductInfoProps = {
 }
 
 export function ProductInfo({ product }: ProductInfoProps) {
+  const collection = (product.collections ?? [])
+    .map((m) => m.collection)
+    .find((c): c is NonNullable<typeof c> => Boolean(c))
   return (
     <div id="product-info">
       <div className="flex flex-col gap-y-4 lg:max-w-[500px] mx-auto">
-        {product.collection && (
+        {collection && (
           <Link
-            href={`/collections/${product.collection.handle}`}
+            href={`/collections/${collection.handle}`}
             className="text-sm text-muted-foreground hover:text-muted-foreground"
           >
-            {product.collection.title}
+            {collection.title}
           </Link>
         )}
         <h2