@cartbase/storefront 0.17.0 → 0.18.1

package/src/products/sets.ts

@@ -0,0 +1,110 @@
+/**
+ * SETS: what a set holds, and which sets hold a product.
+ *
+ * A set on Cartbase is an inventory kit, Medusa's model: the set's variant
+ * draws on the stock items of the products inside it, and the product read
+ * hands those links out when asked with `fields: SET_FIELDS`
+ * (`listProducts`, `retrieveProduct`). Every stock item is born with its own
+ * variant's SKU, so a link's owner is the linked variant, of another
+ * product, whose SKU is the item's. These are the two walks a cart makes:
+ * a set's line shows the products inside it, and a product's line offers
+ * the sets that contain it. Pure module, no React, no network.
+ */
+import type {
+  StoreInventoryItemLink,
+  StoreInventoryLinkedVariant,
+  StoreProduct,
+  StoreProductVariant,
+} from "../api/products"
+
+/** The `fields` value that makes a product read carry its kit links. */
+export const SET_FIELDS = [
+  "*variants.inventory_items",
+  "*variants.inventory_items.inventory",
+  "*variants.inventory_items.inventory.variants",
+  "*variants.inventory_items.inventory.variants.product",
+].join(",")
+
+/** A product inside a set, and how many of it the set holds. */
+export interface SetPart {
+  productId: string
+  variantId: string
+  title: string
+  handle: string
+  thumbnail: string | null
+  quantity: number
+}
+
+/** The product a stock item belongs to: the other product's variant carrying the item's SKU. */
+export function linkOwner(
+  link: StoreInventoryItemLink,
+  selfProductId: string
+): StoreInventoryLinkedVariant | null {
+  const inventory = link.inventory
+  if (!inventory?.sku) return null
+  return (
+    inventory.variants.find(
+      (linked) => linked.product_id !== selfProductId && linked.sku === inventory.sku
+    ) ?? null
+  )
+}
+
+/**
+ * What a variant holds when it is a set: the products whose stock it draws
+ * on, in the merchant's order. Empty for a product sold on its own stock,
+ * and for a read made without `SET_FIELDS`.
+ */
+export function setContents(
+  product: Pick<StoreProduct, "id">,
+  variant: Pick<StoreProductVariant, "inventory_items">
+): SetPart[] {
+  return (variant.inventory_items ?? []).flatMap((link) => {
+    const owner = linkOwner(link, product.id)
+    if (!owner?.product) return []
+    return [
+      {
+        productId: owner.product.id,
+        variantId: owner.id,
+        title: owner.product.title,
+        handle: owner.product.handle,
+        thumbnail: owner.product.thumbnail,
+        quantity: Number(link.required_quantity) || 1,
+      },
+    ]
+  })
+}
+
+/** Every set variant among these products, keyed by variant id, with what it holds. */
+export function setContentsByVariant(
+  products: Array<Pick<StoreProduct, "id"> & { variants?: Array<Pick<StoreProductVariant, "id" | "inventory_items">> | null }>
+): Record<string, SetPart[]> {
+  const byVariant: Record<string, SetPart[]> = {}
+  for (const product of products) {
+    for (const variant of product.variants ?? []) {
+      const parts = setContents(product, variant)
+      if (parts.length) byVariant[variant.id] = parts
+    }
+  }
+  return byVariant
+}
+
+/**
+ * The products that hold this variant's own stock item: the sets it is in.
+ * Ids of other products, each once; empty when the read carried no kit
+ * links or the variant has no SKU.
+ */
+export function setsContaining(
+  product: Pick<StoreProduct, "id">,
+  variant: Pick<StoreProductVariant, "sku" | "inventory_items">
+): string[] {
+  if (!variant.sku) return []
+  const found = new Set<string>()
+  for (const link of variant.inventory_items ?? []) {
+    const inventory = link.inventory
+    if (!inventory || inventory.sku !== variant.sku) continue
+    for (const linked of inventory.variants) {
+      if (linked.product_id !== product.id) found.add(linked.product_id)
+    }
+  }
+  return [...found]
+}

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

@@ -1,164 +1,199 @@
-"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,
-  }
-}
+"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.
+ *   6. The add is instant (2026-09-16): with no `addToCart` seam, the add
+ *      goes through the mounted cart drawer (`useCartDrawer().addLine`),
+ *      the drawer opens at the click with the product already in it, the
+ *      platform confirms behind it, and no page render runs. A store that
+ *      passes its own `addToCart` (a server action) keeps the old path:
+ *      await the seam, open the cart, refresh the page so its
+ *      server-rendered cart follows.
+ *
+ * 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 { useCartDrawer } from "../cart-drawer/context"
+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 host's own cart seam (a server action). Leave it out for the
+   * instant add through the mounted `CartDrawerProvider` (rule 6). 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: at the click on the instant path, after the seam
+   * answers on the server-action path. The instant path opens the mounted
+   * drawer when this is left out.
+   */
+  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
+  /** True while a server-action add runs; never on the instant path, which shows the product at once. */
+  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 drawer = useCartDrawer()
+  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
+
+    if (!addToCart) {
+      // Rule 6: the instant add. The drawer opens now, with the line in it.
+      ;(openCart ?? drawer.open)()
+      const result = await drawer.addLine(variant.id, quantity, {
+        product_id: product.id,
+        product_title: product.title,
+        product_handle: product.handle,
+        thumbnail: variant.thumbnail ?? product.thumbnail ?? product.images?.[0]?.url ?? null,
+        variant_title: variant.title ?? null,
+        unit_price: price?.calculated_price_number ?? 0,
+      })
+      if (result.ok) {
+        onAddToCart?.(product, variant)
+      } else if ((result.error as { code?: string } | null)?.code === "insufficient_inventory") {
+        setExhausted(true)
+      }
+      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, drawer, price])
+
+  return {
+    variant,
+    chosen,
+    choose,
+    quantity,
+    setQuantity,
+    inStock,
+    isAdding,
+    price,
+    isValidVariant: Boolean(variant),
+    add,
+  }
+}

package/src/products/variant-matching.ts

@@ -1,71 +1,71 @@
-/**
- * Pure variant-matching logic — extracted from
- * `@1click/ui/src/products/product-actions.tsx` (v2.3.1) so the
- * option-choice → variant resolution is testable without React
- * (tests/unit/storefront-catalog.test.ts).
- *
- * Data-seam translation: Medusa served `variant.options[]` as flat
- * `{option_id, value}` rows; Cartbase serves option-value LINKS
- * (`{value: {option_id, value, option}}` — see
- * `@cartbase/storefront/api/products` `StoreVariantOptionValueLink`).
- * `optionsAsKeymap` reads the Cartbase link shape (null-safe) and falls back
- * to the flat Medusa row shape so both wire formats resolve identically.
- */
-
-/** Either Cartbase's option-value link or Medusa's flat option-value row. */
-export type VariantOptionLike =
-  | {
-      option_id?: string
-      value?: string | { option_id: string; value: string } | null
-    }
-  | null
-
-/** Chosen options on a PDP: option_id → chosen value (undefined = not chosen). */
-export type OptionChoices = Record<string, string | undefined>
-
-/**
- * Flatten a variant's option values into `{[option_id]: value}` for
- * comparison against the user's current choices.
- */
-export function optionsAsKeymap(
-  variantOptions: VariantOptionLike[] | null | undefined
-): Record<string, string> | undefined {
-  return variantOptions?.reduce((acc: Record<string, string>, varopt) => {
-    if (!varopt) return acc
-    const v = varopt.value
-    if (v && typeof v === "object") {
-      // Cartbase link shape: { value: { option_id, value } }
-      if (v.option_id) acc[v.option_id] = v.value
-    } else if (varopt.option_id && typeof v === "string") {
-      // Medusa flat row shape: { option_id, value }
-      acc[varopt.option_id] = v
-    }
-    return acc
-  }, {})
-}
-
-/**
- * True when the chosen options exactly cover the variant's keymap — same
- * key count, same values. Partial choices never match (the add-to-cart
- * button stays disabled until every option is picked).
- */
-export function optionsMatch(
-  a: OptionChoices,
-  b: Record<string, string> | undefined
-): boolean {
-  if (!b) return false
-  const keys = Object.keys(a)
-  if (keys.length !== Object.keys(b).length) return false
-  return keys.every((k) => a[k] === b[k])
-}
-
-/** Resolve the variant whose options exactly match the current choices. */
-export function findMatchingVariant<
-  V extends { options?: VariantOptionLike[] | null }
->(
-  variants: V[] | null | undefined,
-  options: OptionChoices
-): V | undefined {
-  if (!variants || variants.length === 0) return undefined
-  return variants.find((v) => optionsMatch(options, optionsAsKeymap(v.options)))
-}
+/**
+ * Pure variant-matching logic — extracted from
+ * `@1click/ui/src/products/product-actions.tsx` (v2.3.1) so the
+ * option-choice → variant resolution is testable without React
+ * (tests/unit/storefront-catalog.test.ts).
+ *
+ * Data-seam translation: Medusa served `variant.options[]` as flat
+ * `{option_id, value}` rows; Cartbase serves option-value LINKS
+ * (`{value: {option_id, value, option}}` — see
+ * `@cartbase/storefront/api/products` `StoreVariantOptionValueLink`).
+ * `optionsAsKeymap` reads the Cartbase link shape (null-safe) and falls back
+ * to the flat Medusa row shape so both wire formats resolve identically.
+ */
+
+/** Either Cartbase's option-value link or Medusa's flat option-value row. */
+export type VariantOptionLike =
+  | {
+      option_id?: string
+      value?: string | { option_id: string; value: string } | null
+    }
+  | null
+
+/** Chosen options on a PDP: option_id → chosen value (undefined = not chosen). */
+export type OptionChoices = Record<string, string | undefined>
+
+/**
+ * Flatten a variant's option values into `{[option_id]: value}` for
+ * comparison against the user's current choices.
+ */
+export function optionsAsKeymap(
+  variantOptions: VariantOptionLike[] | null | undefined
+): Record<string, string> | undefined {
+  return variantOptions?.reduce((acc: Record<string, string>, varopt) => {
+    if (!varopt) return acc
+    const v = varopt.value
+    if (v && typeof v === "object") {
+      // Cartbase link shape: { value: { option_id, value } }
+      if (v.option_id) acc[v.option_id] = v.value
+    } else if (varopt.option_id && typeof v === "string") {
+      // Medusa flat row shape: { option_id, value }
+      acc[varopt.option_id] = v
+    }
+    return acc
+  }, {})
+}
+
+/**
+ * True when the chosen options exactly cover the variant's keymap — same
+ * key count, same values. Partial choices never match (the add-to-cart
+ * button stays disabled until every option is picked).
+ */
+export function optionsMatch(
+  a: OptionChoices,
+  b: Record<string, string> | undefined
+): boolean {
+  if (!b) return false
+  const keys = Object.keys(a)
+  if (keys.length !== Object.keys(b).length) return false
+  return keys.every((k) => a[k] === b[k])
+}
+
+/** Resolve the variant whose options exactly match the current choices. */
+export function findMatchingVariant<
+  V extends { options?: VariantOptionLike[] | null }
+>(
+  variants: V[] | null | undefined,
+  options: OptionChoices
+): V | undefined {
+  if (!variants || variants.length === 0) return undefined
+  return variants.find((v) => optionsMatch(options, optionsAsKeymap(v.options)))
+}