@cartbase/storefront 0.20.1 → 0.22.0

package/src/checkout/checkout-error-screen.tsx

@@ -0,0 +1,113 @@
+"use client"
+
+import { useEffect, useRef } from "react"
+
+import { reportCheckoutError } from "../api/checkout"
+import type { StorefrontClient } from "../api/http"
+import { useCheckoutLabels } from "./context"
+
+/**
+ * CheckoutErrorScreen — what a shopper sees when the checkout PAGE fails,
+ * as opposed to a call inside it.
+ *
+ * Next renders a route's `error.tsx` in place of the page when anything in
+ * it throws, a server component included, through the RSC bridge. Without
+ * one, a checkout that throws shows the framework's own error page: a
+ * shopper at the moment of paying is handed a stack trace or a blank
+ * screen, their cart looks lost, and nobody is told. The kit's own
+ * failures already reach the merchant's checkout error log; this closes
+ * the one class that never did, because the component that reports them
+ * was the component that died.
+ *
+ * Mount it as the route's boundary:
+ *
+ *   // src/app/checkout/error.tsx
+ *   "use client"
+ *   import { CheckoutErrorScreen } from "@cartbase/storefront/checkout"
+ *   import { storeClient } from "@/lib/store"
+ *
+ *   export default function CheckoutError(props) {
+ *     return <CheckoutErrorScreen {...props} client={storeClient} />
+ *   }
+ *
+ * The copy comes from the label pack when a `CheckoutProvider` stands
+ * above the boundary (a provider in the route's LAYOUT does; one inside
+ * the page does not, because the page is what Next replaced). Pass the
+ * three strings for a store whose provider sits inside the page.
+ */
+
+export type CheckoutErrorScreenProps = {
+  /** Next's error boundary argument. */
+  error: Error & { digest?: string }
+  /** Next's retry: re-renders the route's tree. */
+  reset: () => void
+  /**
+   * The SDK transport. With it the failure reaches the merchant's checkout
+   * error log; without it the screen still renders, and nobody hears.
+   */
+  client?: StorefrontClient
+  /** The cart the shopper was checking out, when the store knows it. */
+  cartId?: string
+  /** Copy override, for a boundary that stands outside the provider. */
+  title?: string
+  body?: string
+  retryLabel?: string
+}
+
+export function CheckoutErrorScreen({
+  error,
+  reset,
+  client,
+  cartId,
+  title,
+  body,
+  retryLabel,
+}: CheckoutErrorScreenProps) {
+  const labels = useCheckoutLabels()
+  // React runs effects twice in development's strict mode, and a retry
+  // that fails again remounts this component: the ref keeps one failure to
+  // one report instead of filling the merchant's log with copies.
+  const reportedRef = useRef<string | null>(null)
+
+  useEffect(() => {
+    if (!client) return
+    const key = error.digest ?? error.message ?? "unknown"
+    if (reportedRef.current === key) return
+    reportedRef.current = key
+
+    void reportCheckoutError(client, {
+      error_type: "error_boundary_checkout",
+      message: error.message || String(error),
+      ...(cartId ? { cart_id: cartId } : {}),
+      context: {
+        digest: error.digest ?? null,
+        err_name: error.name ?? null,
+        // Enough of the stack to find the component, short enough to stay
+        // inside the sink's limit.
+        err_stack: error.stack?.slice(0, 1500) ?? null,
+        path:
+          typeof window !== "undefined" ? window.location.pathname : null,
+      },
+    })
+  }, [client, cartId, error])
+
+  return (
+    <div className="min-h-[60vh] flex items-center justify-center px-5 py-16">
+      <div className="max-w-md text-center">
+        <h1 className="text-xl font-semibold text-foreground mb-2">
+          {title ?? labels.errorTitle}
+        </h1>
+        <p className="text-sm text-muted-foreground mb-5">
+          {body ?? labels.errorBody}
+        </p>
+        <button
+          type="button"
+          onClick={reset}
+          className="inline-flex items-center justify-center h-11 px-5 rounded-xl bg-foreground text-card text-sm font-semibold transition-colors hover:bg-foreground/90"
+        >
+          {retryLabel ?? labels.errorRetry}
+        </button>
+      </div>
+    </div>
+  )
+}

package/src/checkout/discount-section.tsx

@@ -62,6 +62,13 @@ type DiscountSectionProps = {
   /** The SDK transport — the promotions route is called through it. */
   client: StorefrontClient
   cart: Cart
+  /**
+   * Show the field itself instead of the door that opens it. The checkout
+   * passes this on the phone, where the door would be the second tap
+   * inside an already-closed summary bar and a shopper holding a code
+   * would never find it.
+   */
+  alwaysOpen?: boolean
   /** Receives the decorated cart returned by a successful apply. */
   onCartChange?: (cart: Cart) => void
 }
@@ -69,6 +76,7 @@ type DiscountSectionProps = {
 export function DiscountSection({
   client,
   cart,
+  alwaysOpen = false,
   onCartChange,
 }: DiscountSectionProps) {
   const labels = useCheckoutLabels()
@@ -98,6 +106,45 @@ export function DiscountSection({
     }
   }
 
+  const field = (
+    <div className={cn("flex gap-2", !alwaysOpen && "mt-3")}>
+      <input
+        type="text"
+        value={code}
+        onChange={(e) => setCode(e.target.value.toUpperCase())}
+        onKeyDown={(e) => {
+          if (e.key === "Enter") {
+            e.preventDefault()
+            void handleApply()
+          }
+        }}
+        placeholder="PROMO2024"
+        className="flex-1 h-11 px-4 text-sm bg-card border border-border rounded-xl focus:outline-none focus:border-primary focus:ring-2 focus:ring-primary/20 transition-all"
+      />
+      <button
+        type="button"
+        onClick={handleApply}
+        disabled={loading || !code.trim()}
+        className="px-5 h-11 text-sm font-semibold bg-foreground text-card rounded-xl hover:bg-foreground/90 transition-all disabled:opacity-40"
+      >
+        {labels.addCode}
+      </button>
+    </div>
+  )
+
+  if (alwaysOpen) {
+    return (
+      <div>
+        <p className="text-xs font-medium text-muted-foreground mb-1.5">
+          {labels.discountCode}
+        </p>
+        {field}
+        {error && <p className="text-xs text-destructive mt-2">{error}</p>}
+        {promotions.length > 0 && <AppliedList promotions={promotions} />}
+      </div>
+    )
+  }
+
   return (
     <div>
       <button
@@ -152,67 +199,52 @@ export function DiscountSection({
         </span>
       </button>
 
-      {open && (
-        <div className="mt-3 flex gap-2">
-          <input
-            type="text"
-            value={code}
-            onChange={(e) => setCode(e.target.value.toUpperCase())}
-            placeholder="PROMO2024"
-            className="flex-1 h-11 px-4 text-sm bg-card border border-border rounded-xl focus:outline-none focus:border-primary focus:ring-2 focus:ring-primary/20 transition-all"
-          />
-          <button
-            type="button"
-            onClick={handleApply}
-            disabled={loading || !code.trim()}
-            className="px-5 h-11 text-sm font-semibold bg-foreground text-card rounded-xl hover:bg-foreground/90 transition-all disabled:opacity-40"
-          >
-            {labels.addCode}
-          </button>
-        </div>
-      )}
+      {open && field}
 
       {error && <p className="text-xs text-destructive mt-2">{error}</p>}
 
-      {promotions.length > 0 && (
-        <div className="mt-3 space-y-1.5">
-          {promotions.map((p) => (
-            <div
-              key={p.id}
-              className="flex items-center justify-between px-4 py-2.5 bg-success/10 border border-success/20 rounded-lg"
+      {promotions.length > 0 && <AppliedList promotions={promotions} />}
+    </div>
+  )
+}
+
+/** The codes already on the cart, with what each one takes off. */
+function AppliedList({ promotions }: { promotions: AppliedPromotion[] }) {
+  return (
+    <div className="mt-3 space-y-1.5">
+      {promotions.map((p) => (
+        <div
+          key={p.id}
+          className="flex items-center justify-between px-4 py-2.5 bg-success/10 border border-success/20 rounded-lg"
+        >
+          <div className="flex items-center gap-2">
+            <svg
+              className="w-4 h-4 text-success"
+              fill="none"
+              viewBox="0 0 24 24"
+              stroke="currentColor"
+              strokeWidth={2}
             >
-              <div className="flex items-center gap-2">
-                <svg
-                  className="w-4 h-4 text-success"
-                  fill="none"
-                  viewBox="0 0 24 24"
-                  stroke="currentColor"
-                  strokeWidth={2}
-                >
-                  <path
-                    strokeLinecap="round"
-                    strokeLinejoin="round"
-                    d="M9 12.75L11.25 15 15 9.75M21 12a9 9 0 11-18 0 9 9 0 0118 0z"
-                  />
-                </svg>
-                <span className="text-sm font-semibold text-success">
-                  {p.code}
-                </span>
-              </div>
-              <span className="text-sm font-medium text-success">
-                {p.application_method?.type === "percentage"
-                  ? `-${p.application_method.value}%`
-                  : p.application_method?.value && p.application_method?.currency_code
-                    ? `-${convertToLocale({
-                        amount: +p.application_method.value,
-                        currency_code: p.application_method.currency_code,
-                      })}`
-                    : ""}
-              </span>
-            </div>
-          ))}
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                d="M9 12.75L11.25 15 15 9.75M21 12a9 9 0 11-18 0 9 9 0 0118 0z"
+              />
+            </svg>
+            <span className="text-sm font-semibold text-success">{p.code}</span>
+          </div>
+          <span className="text-sm font-medium text-success">
+            {p.application_method?.type === "percentage"
+              ? `-${p.application_method.value}%`
+              : p.application_method?.value && p.application_method?.currency_code
+                ? `-${convertToLocale({
+                    amount: +p.application_method.value,
+                    currency_code: p.application_method.currency_code,
+                  })}`
+                : ""}
+          </span>
         </div>
-      )}
+      ))}
     </div>
   )
 }

package/src/checkout/fulfillment-option.ts

@@ -0,0 +1,30 @@
+import type { StoreShippingOption } from "../api/checkout"
+
+/**
+ * WHICH DESTINATION a shipping option books, read from the option itself.
+ *
+ * Cartbase writes the merchant's choice as `data.fulfillment_option` (the
+ * Shipping option drawer's "To an Econt office", "To a BoxNow locker" and
+ * the rest, from the carrier registry). The kit was ported from a platform
+ * that put the same value at `data.id`, and nothing on this side ever wrote
+ * that key, so on a Cartbase store every reader of it saw null: no office
+ * or locker picker ever opened, no carrier mark ever keyed, and a cart
+ * could reach Buy with an office option and no office chosen (found live on
+ * the Demo Store, 2026-09-18).
+ *
+ * So the Cartbase key is read first and the ported one stays as a fallback,
+ * because a cart carried over from that platform still speaks it.
+ */
+export function fulfillmentOptionId(
+  option: Pick<StoreShippingOption, "data"> | null | undefined
+): string | null {
+  const data = option?.data as
+    | { fulfillment_option?: unknown; id?: unknown }
+    | null
+    | undefined
+  if (typeof data?.fulfillment_option === "string" && data.fulfillment_option) {
+    return data.fulfillment_option
+  }
+  if (typeof data?.id === "string" && data.id) return data.id
+  return null
+}

package/src/checkout/index.ts

@@ -1,11 +1,11 @@
 // @cartbase/storefront/checkout — barrel export.
 //
-// Ported from `@1click/ui/src/checkout/index.ts` (v2.3.1). Not ported in
-// this batch: CheckoutLineItem's standalone file (its flat row lives inside
-// order-summary.tsx and is re-exported below) and the Mobile* bars (out of
-// the pre-declared file list; stores compose their own from the hook).
-// Extra modules beyond the pre-declared export list (geocode,
-// compare-addresses) are exported from here only.
+// Ported from `@1click/ui/src/checkout/index.ts` (v2.3.1). CheckoutLineItem
+// has no standalone file here: its flat row lives inside order-summary.tsx
+// and is re-exported below. The mobile bars are exported too, so a store
+// with its own checkout layout composes the same phone summary the default
+// layout mounts. Extra modules beyond the pre-declared export list
+// (geocode, compare-addresses) are exported from here only.
 
 export {
   CheckoutProvider,
@@ -21,6 +21,11 @@ export {
   useStripeScope,
 } from "./stripe-wrapper"
 export { PaymentWrapper } from "./payment-wrapper"
+export {
+  resolveCardOffer,
+  type CardEntryLike,
+  type CardOffer,
+} from "./card-offer"
 export { PaymentButton } from "./payment-button"
 export {
   EcontOfficeSelector,
@@ -30,16 +35,41 @@ export {
   BoxNowLockerSelector,
   type BoxNowLocker,
 } from "./boxnow-locker-selector"
+export {
+  PigeonOfficeSelector,
+  type PigeonOffice,
+} from "./pigeon-office-selector"
+export {
+  PickupPointSelector,
+  type PickupPoint,
+} from "./pickup-point-selector"
+export { pickupOptionOf, type PickupOption } from "./pickup-option"
+export { carrierMarks } from "./carrier-marks"
 export { AddressSelect } from "./address-select"
 export { CompanyDetails } from "./company-details"
 export { DiscountSection } from "./discount-section"
 export { GiftCardSection } from "./gift-card-section"
 export { LineItemCard } from "./line-item-card"
 export { OrderSummary, CheckoutLineItem } from "./order-summary"
+export { MobileCheckoutTopBar } from "./mobile-checkout-top-bar"
+export { MobileCheckoutBottomBar } from "./mobile-checkout-bottom-bar"
+export { MobileOrderSummaryBody } from "./mobile-order-summary-body"
+export {
+  checkoutTotals,
+  amountDueAfterTender,
+  isNothingToPay,
+  isCompanyOrder,
+  type CheckoutTotals,
+  type CheckoutTotalsInput,
+} from "./summary-math"
 export { CheckoutAddressForm } from "./address-form"
 export { CheckoutShippingMethodList } from "./shipping-method-list"
 export { CheckoutPaymentMethodList } from "./payment-method-list"
 export { CheckoutClient } from "./checkout-client"
+export {
+  CheckoutErrorScreen,
+  type CheckoutErrorScreenProps,
+} from "./checkout-error-screen"
 export {
   useCheckoutOrchestration,
   resolveOrderConfirmedPath,
@@ -47,6 +77,11 @@ export {
   type CheckoutLogError,
   type PaymentProviderLike,
 } from "./use-checkout-orchestration"
+export {
+  useCheckoutFunnel,
+  type UseCheckoutFunnelOptions,
+} from "./use-checkout-funnel"
+export { fulfillmentOptionId } from "./fulfillment-option"
 export {
   translatePaymentError,
   translateGiftCardError,

package/src/checkout/labels.ts

@@ -46,6 +46,15 @@ export type CheckoutLabels = {
   addCode: string
 
   // States / empty / disabled
+  /**
+   * The checkout with nothing to check out. A shopper who lands here with
+   * an empty cart, or after their order was placed in another tab, used to
+   * be bounced to the home page without a word, which reads as the store
+   * losing their order. The page says it instead, and offers the way back.
+   */
+  cartEmptyTitle: string
+  cartEmptyText: string
+  cartEmptyBack: string
   deliveryDisabled: string
   noShippingOptions: string
   paymentDisabled: string
@@ -80,6 +89,18 @@ export type CheckoutLabels = {
   shipping: string
   shippingCalc: string
   shippingFree: string
+  /**
+   * What a line that costs nothing says in place of its price: a gift a
+   * promotion added, or a line a discount took to zero.
+   *
+   * A SEPARATE label from `shippingFree` on purpose, and not a saving of
+   * one string: in Bulgarian the shipping row reads "Безплатна", agreeing
+   * with доставка, and a product line reads "Безплатно". One label would
+   * print the wrong gender on one of the two rows for every Bulgarian
+   * store, which is exactly the kind of detail a shopper reads as
+   * carelessness at the moment of paying.
+   */
+  lineFree: string
   tax: string
   /**
    * What the tax is, in the store's words. OPTIONAL and undefined by
@@ -124,7 +145,19 @@ export type CheckoutLabels = {
 
   // Place order button
   placeOrder: string
+  /** The button on an order with nothing left to pay. */
+  completeOrder: string
   selectPaymentMethod: string
+  /** What stands where the tender list would be on a covered order. */
+  nothingToPay: string
+
+  /**
+   * The checkout's own error screen (`CheckoutErrorScreen`), shown when
+   * the page itself fails rather than a call inside it.
+   */
+  errorTitle: string
+  errorBody: string
+  errorRetry: string
 
   /**
    * Processing-state messages shown beneath the spinning Buy button
@@ -141,6 +174,27 @@ export type CheckoutLabels = {
   processingCard: string[]
   processingCod: string[]
 
+  /**
+   * The pickup picker, for every carrier (2026-09-18). One picker means one
+   * set of words: a shopper choosing a Speedy office and a shopper choosing
+   * an Econt office are doing the same thing, and the carrier is already
+   * named on the row above by its own mark. The three per-carrier sets below
+   * stay for stores that still mount the old components; new work reads
+   * these.
+   */
+  pickupLoading: string
+  pickupNearestOffices: string
+  pickupNearestLockers: string
+  pickupSearchOffice: string
+  pickupSearchLocker: string
+  pickupSearchOfficePlaceholder: string
+  pickupSearchLockerPlaceholder: string
+  pickupNoResults: string
+  pickupChange: string
+  pickupUnavailable: string
+  /** Why Buy is still disabled: an office option with no office named. */
+  pickupRequired: string
+
   // Econt office selector
   econtLoadingOffices: string
   econtNearestOffices: string
@@ -158,6 +212,16 @@ export type CheckoutLabels = {
   boxnowChange: string
   boxnowUnavailable: string
   boxnowNoLockersInCity: string
+
+  // Pigeon Express office selector
+  pigeonLoadingOffices: string
+  pigeonNearestOffices: string
+  pigeonSearchAnother: string
+  pigeonSearchPlaceholder: string
+  pigeonNoResults: string
+  pigeonChange: string
+  pigeonUnavailable: string
+  pigeonNoOfficesInCity: string
   /**
    * What a shopper reads when saving the address fails. It used to be
    * hardcoded BULGARIAN inside `address-error-copy.ts` with no way to
@@ -287,6 +351,9 @@ export const defaultCheckoutLabels: CheckoutLabels = {
   addToOrder: "+ Add to order",
   addCode: "Apply",
 
+  cartEmptyTitle: "Your cart is empty",
+  cartEmptyText: "Add something to it and your order starts here.",
+  cartEmptyBack: "Back to the shop",
   deliveryDisabled:
     "Enter your delivery address to see available shipping options.",
   noShippingOptions: "No shipping options available for your address.",
@@ -312,6 +379,7 @@ export const defaultCheckoutLabels: CheckoutLabels = {
   shipping: "Shipping",
   shippingCalc: "Calculated at checkout",
   shippingFree: "Free",
+  lineFree: "Free",
   // The row NAME, neutral on purpose: it sits beside a number, so it must
   // say something, but "VAT incl." names one tax regime and asserts that
   // prices include it. That is Bulgaria's answer, not Germany's, and not any
@@ -347,7 +415,14 @@ export const defaultCheckoutLabels: CheckoutLabels = {
   companyAddress: "Company address",
 
   placeOrder: "Place order",
+  completeOrder: "Complete order",
   selectPaymentMethod: "Select a payment method",
+  nothingToPay: "Your order is fully covered. There is nothing left to pay.",
+
+  errorTitle: "Something went wrong at checkout",
+  errorBody:
+    "Your cart is safe. Try again, and if it keeps happening, get in touch.",
+  errorRetry: "Try again",
 
   processingCard: [
     "Connecting to the bank...",
@@ -361,6 +436,18 @@ export const defaultCheckoutLabels: CheckoutLabels = {
     "Attending to every detail...",
   ],
 
+  pickupLoading: "Loading pickup points...",
+  pickupNearestOffices: "Nearest offices",
+  pickupNearestLockers: "Nearest lockers",
+  pickupSearchOffice: "Search for another office",
+  pickupSearchLocker: "Search for another locker",
+  pickupSearchOfficePlaceholder: "Search by name, city, or address...",
+  pickupSearchLockerPlaceholder: "Search by name, city, or address...",
+  pickupNoResults: "Nothing found",
+  pickupChange: "Change",
+  pickupUnavailable: "Pickup points are unavailable right now",
+  pickupRequired: "Choose a pickup point",
+
   econtLoadingOffices: "Loading offices...",
   econtNearestOffices: "Nearest offices",
   econtSearchAnother: "Search for another office",
@@ -378,6 +465,17 @@ export const defaultCheckoutLabels: CheckoutLabels = {
     "BoxNow is temporarily unavailable, please choose a different shipping method.",
   boxnowNoLockersInCity:
     "No BoxNow lockers found in your city. Please choose a different shipping method.",
+
+  pigeonLoadingOffices: "Loading offices...",
+  pigeonNearestOffices: "Nearest offices",
+  pigeonSearchAnother: "Search for another office",
+  pigeonSearchPlaceholder: "Search by name, city, or address...",
+  pigeonNoResults: "No offices found for",
+  pigeonChange: "Change",
+  pigeonUnavailable:
+    "Pigeon Express is temporarily unavailable, please choose a different shipping method.",
+  pigeonNoOfficesInCity:
+    "No Pigeon Express offices found in your city. Please choose a different shipping method.",
   addressErrors: {
     generic:
       "We could not save your address. Please check the details and try again.",