@cartbase/storefront 0.1.0

package/src/cart-drawer/context.tsx

@@ -0,0 +1,569 @@
+"use client"
+
+import {
+  createContext,
+  startTransition,
+  useCallback,
+  useContext,
+  useEffect,
+  useOptimistic,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react"
+
+import {
+  addLineItem as sdkAddLineItem,
+  createCart as sdkCreateCart,
+  deleteLineItem as sdkDeleteLineItem,
+  retrieveCart as sdkRetrieveCart,
+  updateLineItem as sdkUpdateLineItem,
+  type Cart,
+  type CartLineItem,
+} from "../api/carts"
+import type { StorefrontClient } from "../api/http"
+import { productItemCount } from "../lib/cart-helpers"
+import { defaultCartDrawerLabels, type CartDrawerLabels } from "./labels"
+
+/**
+ * Cart drawer context — open state + cart snapshot + labels + link hrefs.
+ *
+ * Stores wrap their root layout with `<CartDrawerProvider cart={cart}>`
+ * (the cart is fetched server-side and passed down as a prop). The
+ * provider manages open/close state, auto-opens when item count rises,
+ * locks body scroll while open, and closes on escape.
+ *
+ * Optimistic UI: the cart exposed via `useCartDrawer().cart` is wrapped
+ * in React 19's `useOptimistic`. Callers (PDP add buttons, drawer
+ * quantity steppers, drawer remove buttons) dispatch optimistic actions
+ * BEFORE awaiting the corresponding server mutation. The drawer reflects
+ * the change at React update speed (~16ms) instead of waiting for the
+ * full backend round-trip (~800-1500ms). On mutation failure the
+ * optimistic state reverts automatically because the confirmed cart
+ * snapshot never updated past the failed mutation. See
+ * https://react.dev/reference/react/useOptimistic.
+ *
+ * Ported from `@1click/ui/src/cart-drawer/context.tsx` (v2.3.1). Barter
+ * data seam: the Medusa server actions (`../data/cart`) are replaced by
+ * `@cartbase/storefront/api/carts` calls made through a `StorefrontClient`
+ * passed to the provider. Every mutation returns the FULL decorated cart
+ * (totals + gift_cards[]/gift_card_total/gift_card_remainder — SERVER
+ * truth), which the provider adopts as the new confirmed snapshot, so no
+ * RSC re-fetch is required for the drawer to settle. Amounts are EUR
+ * decimal major units (the optimistic `unit_price × quantity` arithmetic
+ * is unit-agnostic and unchanged).
+ *
+ * The source's `logEvent` ops funnel (backend error log endpoint) has no
+ * barter SDK equivalent yet — the same single-funnel discipline is kept
+ * via the `onOptimisticError` prop: every failed optimistic mutation
+ * (every PDP add, cross-sell add, drawer remove, drawer quantity change)
+ * flows through it with per-action context. Wire it to the store's ops
+ * logging; the console.error stays regardless.
+ */
+
+type CartDrawerHrefs = {
+  /** Href for the checkout button in the sticky footer */
+  checkout: string
+  /** Href for the "browse products" CTA on the empty state */
+  browse: string
+  /** Prefix for product links — full href is `${productPrefix}/${handle}` */
+  productPrefix: string
+}
+
+const defaultHrefs: CartDrawerHrefs = {
+  checkout: "/checkout",
+  browse: "/store",
+  productPrefix: "/products",
+}
+
+/** Context payload passed to `onOptimisticError` for every failed mutation. */
+export type OptimisticCartError = {
+  actionType: OptimisticCartAction["type"]
+  error: unknown
+  /** Structured per-action fields (quantity, line_id, variant/product ids). */
+  context: Record<string, unknown>
+}
+
+/**
+ * Display fields an "add" action carries so the drawer can render the row
+ * immediately, before the server confirms.
+ */
+export type OptimisticAddDisplay = {
+  product_id?: string
+  product_title?: string
+  product_handle?: string
+  thumbnail?: string | null
+  variant_title?: string | null
+  /** Per-unit price in EUR major units. total = price × qty. */
+  unit_price?: number
+}
+
+/**
+ * Optimistic action shapes — what callers can dispatch to update the
+ * cart UI ahead of the server confirmation.
+ */
+export type OptimisticCartAction =
+  | ({
+      type: "add"
+      /** Variant being added. We use this to merge with existing lines. */
+      variant_id: string
+      quantity: number
+    } & OptimisticAddDisplay)
+  | {
+      type: "remove"
+      lineId: string
+    }
+  | {
+      type: "update_quantity"
+      lineId: string
+      quantity: number
+    }
+
+type CartDrawerContextValue = {
+  isOpen: boolean
+  open: () => void
+  close: () => void
+  toggle: () => void
+  /** Cart snapshot AFTER any pending optimistic updates. */
+  cart: Cart | null
+  /**
+   * Dispatch an optimistic update. MUST be called inside a
+   * `startTransition` (React requirement for useOptimistic setters
+   * outside Action props). The CartDrawerProvider exposes a helper
+   * `applyOptimistic` that wraps the dispatch in startTransition for
+   * convenience; prefer that.
+   */
+  dispatchOptimistic: (action: OptimisticCartAction) => void
+  /**
+   * Convenience wrapper: dispatches the optimistic action AND awaits
+   * the provided server mutation inside a single transition. Use from
+   * PDP add buttons or anywhere the store owns the server call itself
+   * (e.g. a Next.js server action). The built-in helpers below cover
+   * the SDK-wired path.
+   */
+  applyOptimistic: (
+    action: OptimisticCartAction,
+    serverAction: () => Promise<unknown>
+  ) => void
+  /**
+   * SDK-wired mutations (require the provider's `client` prop). Each
+   * dispatches the optimistic action, calls the matching
+   * `@cartbase/storefront/api/carts` function, and adopts the returned
+   * decorated cart. Resolves `true` on server confirmation, `false` on
+   * failure (after funneling through `onOptimisticError`) or when no
+   * client is configured.
+   */
+  addItem: (
+    variantId: string,
+    quantity?: number,
+    display?: OptimisticAddDisplay
+  ) => Promise<boolean>
+  /** POST line-items/:id with `{quantity}` — barter contract: 0 deletes. */
+  updateQuantity: (lineId: string, quantity: number) => Promise<boolean>
+  removeItem: (lineId: string) => Promise<boolean>
+  /** Re-read the decorated cart (totals/gift-card tender are live per read). */
+  refresh: () => Promise<void>
+  labels: CartDrawerLabels
+  hrefs: CartDrawerHrefs
+}
+
+const CartDrawerContext = createContext<CartDrawerContextValue>({
+  isOpen: false,
+  open: () => {},
+  close: () => {},
+  toggle: () => {},
+  cart: null,
+  dispatchOptimistic: () => {},
+  applyOptimistic: () => {},
+  addItem: async () => false,
+  updateQuantity: async () => false,
+  removeItem: async () => false,
+  refresh: async () => {},
+  labels: defaultCartDrawerLabels,
+  hrefs: defaultHrefs,
+})
+
+export function useCartDrawer(): CartDrawerContextValue {
+  return useContext(CartDrawerContext)
+}
+
+/**
+ * Reducer for the useOptimistic cart. Pure function. Returns the next
+ * cart shape after applying the action. Falls back to a synthetic empty
+ * cart when there's no current cart yet so optimistic adds work even on
+ * first-add (the server backfills the real cart_id + line_id below).
+ *
+ * Exported for unit tests (pure logic, no React).
+ */
+export function reduceCart(
+  current: Cart | null,
+  action: OptimisticCartAction
+): Cart | null {
+  if (!current) {
+    // No cart yet on the server — synthesize a minimal one so the drawer
+    // can render the item immediately. The real createCart call will
+    // create the cart and the confirmed snapshot replaces this synthetic
+    // one.
+    if (action.type !== "add") return current
+    return {
+      id: "optimistic-cart",
+      items: [makeOptimisticLine(action)],
+    } as unknown as Cart
+  }
+
+  switch (action.type) {
+    case "add": {
+      const items = current.items ?? []
+      const existing = items.find((i) => i.variant_id === action.variant_id)
+      if (existing) {
+        return {
+          ...current,
+          items: items.map((i) =>
+            i.variant_id === action.variant_id
+              ? {
+                  ...i,
+                  quantity: i.quantity + action.quantity,
+                  total:
+                    (i.unit_price ?? 0) * (i.quantity + action.quantity),
+                }
+              : i
+          ),
+        }
+      }
+      return {
+        ...current,
+        items: [...items, makeOptimisticLine(action)],
+      }
+    }
+    case "remove": {
+      return {
+        ...current,
+        items: (current.items ?? []).filter((i) => i.id !== action.lineId),
+      }
+    }
+    case "update_quantity": {
+      return {
+        ...current,
+        items: (current.items ?? []).map((i) =>
+          i.id === action.lineId
+            ? {
+                ...i,
+                quantity: action.quantity,
+                total: (i.unit_price ?? 0) * action.quantity,
+              }
+            : i
+        ),
+      }
+    }
+  }
+}
+
+/**
+ * Build a synthetic line item from an "add" action. The real server
+ * response will replace this with the actual line on confirmation.
+ * Cast through `unknown` because `CartLineItem` has many fields we
+ * don't have at click time (created_at, tax_lines, adjustments…) — the
+ * renderer is lenient about missing optional fields.
+ */
+export function makeOptimisticLine(
+  action: Extract<OptimisticCartAction, { type: "add" }>
+): CartLineItem {
+  const unitPrice = action.unit_price ?? 0
+  return {
+    id: `optimistic-${action.variant_id}`,
+    variant_id: action.variant_id,
+    product_id: action.product_id,
+    product_title: action.product_title,
+    product_handle: action.product_handle,
+    thumbnail: action.thumbnail,
+    variant_title: action.variant_title,
+    quantity: action.quantity,
+    unit_price: unitPrice,
+    total: unitPrice * action.quantity,
+    original_total: unitPrice * action.quantity,
+  } as unknown as CartLineItem
+}
+
+export function CartDrawerProvider({
+  cart,
+  client,
+  cartId,
+  onCartChange,
+  onOptimisticError,
+  labels: labelOverrides,
+  hrefs: hrefOverrides,
+  children,
+}: {
+  /**
+   * Server-fetched cart snapshot (RSC/server-action pattern). When the
+   * prop changes (e.g. after a router refresh) it becomes the confirmed
+   * snapshot. Optional when `client` + `cartId` are given — the provider
+   * then retrieves the cart itself on mount.
+   */
+  cart?: Cart | null
+  /** StorefrontClient for the SDK-wired mutations (addItem/updateQuantity/removeItem/refresh). */
+  client?: StorefrontClient
+  /** Known cart id to retrieve when no `cart` snapshot is passed. */
+  cartId?: string | null
+  /**
+   * Fires with the decorated cart after every server-confirmed change,
+   * including first-add cart creation — persist `cart.id` (cookie/storage)
+   * here so the cart survives reloads.
+   */
+  onCartChange?: (cart: Cart) => void
+  /** Ops funnel for every failed optimistic mutation (see module JSDoc). */
+  onOptimisticError?: (failure: OptimisticCartError) => void
+  labels?: Partial<CartDrawerLabels>
+  hrefs?: Partial<CartDrawerHrefs>
+  children: ReactNode
+}) {
+  const [isOpen, setIsOpen] = useState(false)
+  const prevItemCount = useRef(0)
+
+  // Confirmed snapshot: seeded from the prop, replaced by every SDK
+  // mutation response (each returns the full decorated cart) and by
+  // prop updates from server refreshes.
+  const [serverCart, setServerCart] = useState<Cart | null>(cart ?? null)
+  useEffect(() => {
+    if (cart !== undefined) setServerCart(cart)
+  }, [cart])
+
+  // Client+cartId mode: retrieve the decorated cart on mount when no
+  // snapshot was provided.
+  useEffect(() => {
+    if (cart !== undefined || !client || !cartId) return
+    let cancelled = false
+    sdkRetrieveCart(client, cartId)
+      .then((res) => {
+        if (!cancelled) setServerCart(res.cart)
+      })
+      .catch(() => {
+        // 404 cart_not_found (expired/foreign id) → stay empty; the next
+        // addItem creates a fresh cart.
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [cart, client, cartId])
+
+  const [optimisticCart, dispatchOptimistic] = useOptimistic(
+    serverCart,
+    reduceCart
+  )
+
+  // totalItems counts PRODUCT lines only. Backend-injected fee lines
+  // (e.g. the COD fee added by the payment-session flow) are excluded
+  // — otherwise the auto-open useEffect below treats a fee insertion
+  // as "a new item was added," opens the drawer mid-checkout, and
+  // locks body scroll. See @cartbase/storefront/lib/cart-helpers for the
+  // shared predicate.
+  const totalItems = productItemCount(optimisticCart?.items)
+
+  // Auto-open when items are added (count increases AFTER initial load)
+  useEffect(() => {
+    if (totalItems > prevItemCount.current && prevItemCount.current > 0) {
+      setIsOpen(true)
+    }
+    prevItemCount.current = totalItems
+  }, [totalItems])
+
+  // Lock body scroll while open
+  useEffect(() => {
+    if (isOpen) {
+      document.body.style.overflow = "hidden"
+    } else {
+      document.body.style.overflow = ""
+    }
+    return () => {
+      document.body.style.overflow = ""
+    }
+  }, [isOpen])
+
+  // Escape closes
+  useEffect(() => {
+    const handleEscape = (e: KeyboardEvent) => {
+      if (e.key === "Escape" && isOpen) setIsOpen(false)
+    }
+    document.addEventListener("keydown", handleEscape)
+    return () => document.removeEventListener("keydown", handleEscape)
+  }, [isOpen])
+
+  const open = useCallback(() => setIsOpen(true), [])
+  const close = useCallback(() => setIsOpen(false), [])
+  const toggle = useCallback(() => setIsOpen((prev) => !prev), [])
+
+  /**
+   * Shared optimistic runner. useOptimistic setters MUST be called
+   * inside a transition or an Action prop, otherwise React errors
+   * during render. Wrapping both the dispatch AND the awaited server
+   * work in a single startTransition ensures the optimistic state stays
+   * "pending" for the entire round-trip — and reverts cleanly on throw.
+   *
+   * On failure the optimistic state auto-reverts because the confirmed
+   * snapshot hasn't updated. We do NOT rethrow — useOptimistic
+   * semantics require the transition to settle cleanly. Every failure
+   * is logged (console + `onOptimisticError`): this is the single
+   * funnel for every PDP add, cross-sell add, drawer remove, drawer
+   * quantity change. Without it those failures are invisible to ops.
+   */
+  const runOptimistic = useCallback(
+    (
+      action: OptimisticCartAction,
+      work: () => Promise<unknown>
+    ): Promise<boolean> =>
+      new Promise<boolean>((resolve) => {
+        startTransition(async () => {
+          dispatchOptimistic(action)
+          try {
+            await work()
+            resolve(true)
+          } catch (err) {
+            const err_ = err as { message?: string; name?: string }
+            // eslint-disable-next-line no-console
+            console.error("[cart-optimistic]", action.type, err_)
+            const ctx: Record<string, unknown> = { action_type: action.type }
+            if (action.type === "add") {
+              ctx.quantity = action.quantity
+              ctx.product_id = action.product_id
+              ctx.variant_id = action.variant_id
+            } else if (action.type === "remove") {
+              ctx.line_id = action.lineId
+            } else if (action.type === "update_quantity") {
+              ctx.line_id = action.lineId
+              ctx.quantity = action.quantity
+            }
+            ctx.err_name = err_?.name
+            ctx.err_message = err_?.message ?? String(err)
+            try {
+              onOptimisticError?.({ actionType: action.type, error: err, context: ctx })
+            } catch {
+              // The ops funnel itself must never break the UI.
+            }
+            resolve(false)
+          }
+        })
+      }),
+    [dispatchOptimistic, onOptimisticError]
+  )
+
+  const applyOptimistic = useCallback(
+    (action: OptimisticCartAction, serverAction: () => Promise<unknown>) => {
+      void runOptimistic(action, serverAction)
+    },
+    [runOptimistic]
+  )
+
+  /** Adopt a server-confirmed decorated cart. */
+  const confirm = useCallback(
+    (next: Cart) => {
+      setServerCart(next)
+      onCartChange?.(next)
+    },
+    [onCartChange]
+  )
+
+  const addItem = useCallback(
+    (
+      variantId: string,
+      quantity = 1,
+      display: OptimisticAddDisplay = {}
+    ): Promise<boolean> => {
+      if (!client) return Promise.resolve(false)
+      const action: OptimisticCartAction = {
+        type: "add",
+        variant_id: variantId,
+        quantity,
+        ...display,
+      }
+      return runOptimistic(action, async () => {
+        const existingId = serverCart?.id
+        if (existingId) {
+          const res = await sdkAddLineItem(client, existingId, {
+            variant_id: variantId,
+            quantity,
+          })
+          confirm(res.cart)
+        } else {
+          // First add with no cart: create one with the item in a single
+          // call. region_id falls back to the store default server-side.
+          const res = await sdkCreateCart(client, {
+            items: [{ variant_id: variantId, quantity }],
+          })
+          confirm(res.cart)
+        }
+      })
+    },
+    [client, serverCart?.id, runOptimistic, confirm]
+  )
+
+  const updateQuantity = useCallback(
+    (lineId: string, quantity: number): Promise<boolean> => {
+      const id = serverCart?.id
+      if (!client || !id) return Promise.resolve(false)
+      return runOptimistic(
+        { type: "update_quantity", lineId, quantity },
+        async () => {
+          // Barter contract: body is `{quantity}` only (metadata is NOT
+          // accepted on update, only on add); quantity 0 deletes the line.
+          const res = await sdkUpdateLineItem(client, id, lineId, { quantity })
+          confirm(res.cart)
+        }
+      )
+    },
+    [client, serverCart?.id, runOptimistic, confirm]
+  )
+
+  const removeItem = useCallback(
+    (lineId: string): Promise<boolean> => {
+      const id = serverCart?.id
+      if (!client || !id) return Promise.resolve(false)
+      return runOptimistic({ type: "remove", lineId }, async () => {
+        const res = await sdkDeleteLineItem(client, id, lineId)
+        confirm(res.cart)
+      })
+    },
+    [client, serverCart?.id, runOptimistic, confirm]
+  )
+
+  const refresh = useCallback(async (): Promise<void> => {
+    const id = serverCart?.id
+    if (!client || !id) return
+    try {
+      const res = await sdkRetrieveCart(client, id)
+      confirm(res.cart)
+    } catch {
+      // Keep the last snapshot on transient failure.
+    }
+  }, [client, serverCart?.id, confirm])
+
+  const labels: CartDrawerLabels = {
+    ...defaultCartDrawerLabels,
+    ...labelOverrides,
+  }
+  const hrefs: CartDrawerHrefs = {
+    ...defaultHrefs,
+    ...hrefOverrides,
+  }
+
+  return (
+    <CartDrawerContext.Provider
+      value={{
+        isOpen,
+        open,
+        close,
+        toggle,
+        cart: optimisticCart,
+        dispatchOptimistic,
+        applyOptimistic,
+        addItem,
+        updateQuantity,
+        removeItem,
+        refresh,
+        labels,
+        hrefs,
+      }}
+    >
+      {children}
+    </CartDrawerContext.Provider>
+  )
+}

package/src/cart-drawer/continue-shopping.tsx

@@ -0,0 +1,28 @@
+"use client"
+
+import { useCartDrawer } from "./context"
+
+/**
+ * CartContinueShopping — tiny "continue shopping" text link under the
+ * sticky footer.
+ *
+ * Ported from `@1click/ui/src/cart-drawer/continue-shopping.tsx` (v2.3.1);
+ * originally extracted from mindpages-storefront
+ * src/modules/cart-drawer/cart-continue-shopping.tsx.
+ */
+
+export function CartContinueShopping() {
+  const { close, labels } = useCartDrawer()
+
+  return (
+    <div className="flex justify-center px-5 pb-3">
+      <button
+        type="button"
+        onClick={close}
+        className="text-sm text-muted-foreground hover:text-foreground underline underline-offset-4 decoration-border hover:decoration-text-muted transition-colors"
+      >
+        {labels.continueShopping}
+      </button>
+    </div>
+  )
+}