@cartbase/storefront 0.24.0 → 0.24.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cartbase/storefront",
-  "version": "0.24.0",
+  "version": "0.24.1",
   "description": "Storefront SDK + UI component library for Cartbase stores: typed API client, checkout orchestration, cart drawer, product/catalog components, tracking. Source-shipped TypeScript — add it to transpilePackages.",
   "license": "MIT",
   "repository": {

package/src/api/checkout.ts

@@ -146,6 +146,12 @@ export interface ListPaymentProvidersQuery {
    * checkout; without it cart-dependent hide rules cannot match here.
    */
   cart_id?: string
+  /**
+   * Evaluate payment rules for the delivery option the shopper just chose.
+   * This avoids waiting for the cart preference write before refreshing the
+   * server-authoritative payment list.
+   */
+  shipping_option_id?: string
 }
 
 /** A connected PROCESSOR entry of GET /api/store/payment-providers. */
@@ -197,6 +203,12 @@ export const isMethodEntry = (
 
 export interface PaymentProviderListResponse extends ListEnvelope {
   payment_providers: StorePaymentEntry[]
+  /**
+   * Server-evaluated payment choices keyed by delivery option. CheckoutClient
+   * uses this to react synchronously during rapid shipping switches without
+   * reproducing the rules engine in the browser.
+   */
+  payment_providers_by_shipping_option?: Record<string, StorePaymentEntry[]>
 }
 
 /**

package/src/checkout/checkout-client.tsx

@@ -59,8 +59,10 @@ type CheckoutClientProps = {
   client: StorefrontClient
   cart: Cart
   customer: StoreCustomer | null
-  availableShippingMethods: StoreShippingOption[] | null
+  availableShippingMethods: StoreShippingOption[] | null
   availablePaymentMethods: PaymentProviderLike[] | null
+  /** Server-evaluated tender lists keyed by delivery option id. */
+  paymentMethodsByShippingOption?: Record<string, PaymentProviderLike[]>
   /** Card and wallet marks returned by `GET /api/store/payment-marks`. */
   paymentMarks?: readonly PaymentMethod[]
   /** Store-owned terms notice, including links to its content pages. */
@@ -113,8 +115,9 @@ export function CheckoutClient({
   client,
   cart,
   customer,
-  availableShippingMethods,
+  availableShippingMethods,
   availablePaymentMethods,
+  paymentMethodsByShippingOption,
   paymentMarks,
   termsContent,
   countryCode,
@@ -136,8 +139,9 @@ export function CheckoutClient({
     client,
     cart,
     customer,
-    availableShippingMethods,
-    availablePaymentMethods,
+    availableShippingMethods,
+    availablePaymentMethods,
+    paymentMethodsByShippingOption,
     countryCode,
     countries,
     paymentMethodFilter,

package/src/checkout/discount-section.tsx

@@ -107,7 +107,7 @@ export function DiscountSection({
   }
 
   const field = (
-    <div className={cn("flex gap-2", !alwaysOpen && "mt-3")}>
+    <div className={cn("grid grid-cols-[minmax(0,1fr)_auto] gap-2", !alwaysOpen && "mt-3")}>
       <input
         type="text"
         value={code}
@@ -119,13 +119,13 @@ export function DiscountSection({
           }
         }}
         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"
+        className="w-full min-w-0 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"
+        className="px-4 h-11 text-sm font-semibold bg-foreground text-card rounded-xl hover:bg-foreground/90 transition-all disabled:opacity-40"
       >
         {labels.addCode}
       </button>
@@ -150,7 +150,7 @@ export function DiscountSection({
       <button
         type="button"
         onClick={() => setOpen(!open)}
-        className="flex items-center gap-3 w-full p-4 rounded-xl border border-border bg-muted/50 hover:bg-muted transition-colors"
+        className="grid grid-cols-[2.5rem_minmax(0,1fr)_auto] items-center gap-3 w-full p-4 rounded-xl border border-border bg-card hover:border-primary transition-colors"
       >
         <div className="w-10 h-10 rounded-full bg-gradient-to-br from-warning to-warning/70 flex items-center justify-center flex-shrink-0">
           <svg
@@ -172,13 +172,15 @@ export function DiscountSection({
             />
           </svg>
         </div>
-        <div className="flex-1 text-left">
-          <p className="text-sm font-semibold text-foreground">
+        <div className="min-w-0 text-left">
+          <p className="text-sm font-semibold leading-tight text-foreground truncate">
             {labels.discountCode}
           </p>
-          <p className="text-xs text-muted-foreground">{labels.discountSub}</p>
+          <p className="hidden min-[380px]:block text-xs text-muted-foreground truncate">
+            {labels.discountSub}
+          </p>
         </div>
-        <span className="text-sm font-medium text-foreground flex items-center gap-1.5">
+        <span className="shrink-0 whitespace-nowrap text-sm font-medium text-foreground flex items-center gap-1.5">
           {labels.addCode}
           <svg
             className={cn(

package/src/checkout/gift-card-section.tsx

@@ -100,7 +100,7 @@ export function GiftCardSection({
       <button
         type="button"
         onClick={() => setOpen(!open)}
-        className="flex items-center gap-3 w-full p-4 rounded-xl border border-border bg-muted/50 hover:bg-muted transition-colors"
+        className="grid grid-cols-[2.5rem_minmax(0,1fr)_auto] items-center gap-3 w-full p-4 rounded-xl border border-border bg-card hover:border-primary transition-colors"
       >
         <div className="w-10 h-10 rounded-full bg-gradient-to-br from-primary to-primary/70 flex items-center justify-center flex-shrink-0">
           {/* Gift icon */}
@@ -118,13 +118,15 @@ export function GiftCardSection({
             />
           </svg>
         </div>
-        <div className="flex-1 text-left">
-          <p className="text-sm font-semibold text-foreground">
+        <div className="min-w-0 text-left">
+          <p className="text-sm font-semibold leading-tight text-foreground truncate">
             {labels.giftCard}
           </p>
-          <p className="text-xs text-muted-foreground">{labels.giftCardSub}</p>
+          <p className="hidden min-[380px]:block text-xs text-muted-foreground truncate">
+            {labels.giftCardSub}
+          </p>
         </div>
-        <span className="text-sm font-medium text-foreground flex items-center gap-1.5">
+        <span className="shrink-0 whitespace-nowrap text-sm font-medium text-foreground flex items-center gap-1.5">
           {labels.addCode}
           <svg
             className={cn(
@@ -146,19 +148,19 @@ export function GiftCardSection({
       </button>
 
       {open && (
-        <div className="mt-3 flex gap-2">
+        <div className="mt-3 grid grid-cols-[minmax(0,1fr)_auto] gap-2">
           <input
             type="text"
             value={code}
             onChange={(e) => setCode(e.target.value.toUpperCase())}
             placeholder={labels.giftCardPlaceholder}
-            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"
+            className="w-full min-w-0 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"
+            className="px-4 h-11 text-sm font-semibold bg-foreground text-card rounded-xl hover:bg-foreground/90 transition-all disabled:opacity-40"
           >
             {labels.addCode}
           </button>

package/src/checkout/latest-write-queue.ts

@@ -0,0 +1,39 @@
+/**
+ * Serialize a rapidly changing preference while coalescing clicks that have
+ * not started yet. The write in flight finishes; then only the newest queued
+ * value is written. This guarantees that the final durable value is the last
+ * user intent even when network responses complete unpredictably.
+ */
+export function createLatestWriteQueue<T>() {
+  let queued: { value: T; write: (value: T) => Promise<unknown> } | null = null
+  let running = false
+
+  const drain = async () => {
+    if (running) return
+    running = true
+    try {
+      while (queued) {
+        const next = queued
+        queued = null
+        try {
+          await next.write(next.value)
+        } catch {
+          // Persistence is best effort. A newer queued value must still run,
+          // and checkout completion independently validates the final choice.
+        }
+      }
+    } finally {
+      running = false
+      // A push cannot interleave with synchronous code above, but keeping the
+      // final check makes the queue safe if its implementation later changes.
+      if (queued) void drain()
+    }
+  }
+
+  return {
+    push(value: T, write: (value: T) => Promise<unknown>) {
+      queued = { value, write }
+      void drain()
+    },
+  }
+}

package/src/checkout/mobile-checkout-top-bar.tsx

@@ -50,7 +50,7 @@ export function MobileCheckoutTopBar({
   })
 
   return (
-    <div className="sm:hidden bg-muted border-y border-border">
+    <div className="sm:hidden bg-card border-y border-border">
       <button
         type="button"
         onClick={() => setOpen((v) => !v)}

package/src/checkout/pickup-point-selector.tsx

@@ -146,11 +146,11 @@ export function PickupPointSelector({
       <button
         key={`${point.provider}-${point.id}`}
         type="button"
-        onClick={() => choose(point)}
-        className={cn(
-          "flex items-start gap-3 w-full px-3.5 py-3 text-left transition-all duration-150 rounded-lg",
-          "bg-card hover:bg-muted"
-        )}
+        onClick={() => choose(point)}
+        className={cn(
+          "flex items-start gap-3 w-full px-3.5 py-3 text-left transition-colors duration-150 rounded-lg border border-transparent",
+          "bg-card hover:border-primary"
+        )}
       >
         <div className="w-8 h-8 rounded-full bg-muted flex items-center justify-center flex-shrink-0 mt-0.5">
           <svg
@@ -175,8 +175,8 @@ export function PickupPointSelector({
         </div>
 
         <div className="flex-1 min-w-0">
-          <p className="text-sm font-medium text-foreground leading-tight">
-            {point.name}
+          <p className="text-sm font-medium text-foreground leading-tight uppercase">
+            {point.name}
           </p>
           <p className="text-xs text-muted-foreground mt-0.5">
             {point.secondary_name ||
@@ -223,7 +223,7 @@ export function PickupPointSelector({
               d="M9 12.75L11.25 15 15 9.75M21 12a9 9 0 11-18 0 9 9 0 0118 0z"
             />
           </svg>
-          <p className="text-sm font-medium text-primary">{selectedPoint.name}</p>
+          <p className="text-sm font-medium text-primary uppercase">{selectedPoint.name}</p>
           <button
             type="button"
             onClick={() => choose(null)}

package/src/checkout/shipping-method-list.tsx

@@ -195,10 +195,10 @@ export function CheckoutShippingMethodList({
               <div
                 key={option.id}
                 className={cn(
-                  "rounded-lg border overflow-hidden transition-colors duration-150",
-                  selected
-                    ? "border-primary bg-primary/5"
-                    : "border-border bg-card hover:border-muted-foreground"
+                  "rounded-lg border overflow-hidden transition-colors duration-150",
+                  selected
+                    ? "border-primary bg-primary/5"
+                    : "border-border bg-card hover:border-primary"
                 )}
               >
                 <button
@@ -235,13 +235,13 @@ export function CheckoutShippingMethodList({
                     </span>
                   )}
                   <div className="flex-1 min-w-0">
-                    <span className="text-sm font-medium text-foreground">
-                      {option.name}
-                    </span>
+                    <span className="text-sm font-medium text-foreground uppercase">
+                      {option.name}
+                    </span>
                     {selected && isPickup && pickup?.selectedPoint && (
-                      <p className="text-xs text-muted-foreground mt-0.5">
-                        {pickup.selectedPoint.name}
-                      </p>
+                      <p className="text-xs text-muted-foreground mt-0.5 uppercase">
+                        {pickup.selectedPoint.name}
+                      </p>
                     )}
                   </div>
                   <span

package/src/checkout/use-checkout-orchestration.ts

@@ -25,8 +25,9 @@ import {
   prepareCheckout,
   refreshPaymentIfTerminal as refreshPaymentIfTerminalApi,
   reportCheckoutError,
-  syncPaymentAmount as syncPaymentAmountApi,
-  isMethodEntry,
+  syncPaymentAmount as syncPaymentAmountApi,
+  isMethodEntry,
+  listPaymentProviders,
   type PrepareCheckoutInput,
   type RefreshPaymentResult,
   type StorePaymentEntry,
@@ -54,7 +55,8 @@ import { useCheckoutLabels, useOrderConfirmedPath } from "./context"
 import { fulfillmentOptionId } from "./fulfillment-option"
 import { useCheckoutFunnel } from "./use-checkout-funnel"
 import { amountDueAfterTender, isNothingToPay } from "./summary-math"
-import { forgetFiredEvents } from "../tracking/once"
+import { forgetFiredEvents } from "../tracking/once"
+import { createLatestWriteQueue } from "./latest-write-queue"
 
 /**
  * useCheckoutOrchestration — single source of truth for checkout-page
@@ -122,8 +124,13 @@ export type UseCheckoutOrchestrationOptions = {
   client: StorefrontClient
   cart: Cart
   customer: StoreCustomer | null
-  availableShippingMethods: StoreShippingOption[] | null
-  availablePaymentMethods: PaymentProviderLike[] | null
+  availableShippingMethods: StoreShippingOption[] | null
+  availablePaymentMethods: PaymentProviderLike[] | null
+  /**
+   * Server-evaluated payment availability keyed by delivery option. When
+   * supplied, a shipping click changes the tender list synchronously.
+   */
+  paymentMethodsByShippingOption?: Record<string, PaymentProviderLike[]>
   /** Default country code when the cart has no shipping address yet. */
   countryCode?: string
   /**
@@ -287,8 +294,9 @@ export function useCheckoutOrchestration({
   client,
   cart,
   customer,
-  availableShippingMethods,
-  availablePaymentMethods,
+  availableShippingMethods,
+  availablePaymentMethods,
+  paymentMethodsByShippingOption,
   countryCode = "",
   countries,
   paymentMethodFilter,
@@ -868,18 +876,49 @@ export function useCheckoutOrchestration({
     [availableShippingMethods]
   )
 
-  const selectedShippingOption = useMemo(
+  const selectedShippingOption = useMemo(
     () =>
       shippingMethods.find((sm) => sm.id === selectedShippingMethod) ?? null,
     [shippingMethods, selectedShippingMethod]
-  )
-
-  const effectiveAvailablePaymentMethods = useMemo(
-    () =>
-      paymentMethodFilter
-        ? paymentMethodFilter(availablePaymentMethods, selectedShippingOption)
-        : availablePaymentMethods,
-    [paymentMethodFilter, availablePaymentMethods, selectedShippingOption]
+  )
+
+  // Payment rules can depend on the selected delivery option. The host's
+  // initial list is server-rendered; after a delivery choice is remembered
+  // on the cart, ask the same server-side rules door for the new list. A
+  // sequence guard prevents a slower earlier choice from winning a rapid
+  // switch between carriers.
+  const [serverAvailablePaymentMethods, setServerAvailablePaymentMethods] =
+    useState<PaymentProviderLike[] | null>(availablePaymentMethods)
+  const paymentListingRequest = useRef(0)
+  useEffect(() => {
+    const mapped = selectedShippingMethod
+      ? paymentMethodsByShippingOption?.[selectedShippingMethod]
+      : undefined
+    setServerAvailablePaymentMethods(mapped ?? availablePaymentMethods)
+  }, [availablePaymentMethods, paymentMethodsByShippingOption, selectedShippingMethod])
+  const refreshPaymentMethods = useCallback(async (shippingOptionId: string) => {
+    const request = ++paymentListingRequest.current
+    try {
+      const result = await listPaymentProviders(client, {
+        cart_id: cart.id,
+        region_id: cart.region_id ?? undefined,
+        shipping_option_id: shippingOptionId,
+      })
+      if (request === paymentListingRequest.current) {
+        setServerAvailablePaymentMethods(result.payment_providers)
+      }
+    } catch {
+      // Keep the last good listing. Completion re-checks the same rule on
+      // the server, so a transient refresh failure cannot bypass it.
+    }
+  }, [client, cart.id, cart.region_id])
+
+  const effectiveAvailablePaymentMethods = useMemo(
+    () =>
+      paymentMethodFilter
+        ? paymentMethodFilter(serverAvailablePaymentMethods, selectedShippingOption)
+        : serverAvailablePaymentMethods,
+    [paymentMethodFilter, serverAvailablePaymentMethods, selectedShippingOption]
   )
 
   // Calculated-rate price resolution. Cartbase serves flat prices today
@@ -1039,10 +1078,10 @@ export function useCheckoutOrchestration({
   //   - null         → no prediction; render whatever the cart says
   //   - 0            → predict no fee (toggling to a fee-less tender)
   //   - positive     → predict the fee at this amount
-  const [optimisticMethodFee, setOptimisticMethodFee] = useState<number | null>(
-    null
-  )
-
+  const [optimisticMethodFee, setOptimisticMethodFee] = useState<number | null>(
+    null
+  )
+
   // Payment tab selection is client state only pre-Buy. No payment
   // session is created until Buy click — this eliminates the entire
   // class of session-rotation / amount-drift / iframe-remount bugs
@@ -1096,15 +1135,28 @@ export function useCheckoutOrchestration({
    * are the checkout's own notes to itself, and prepare-checkout overwrites
    * the real ones from them.
    */
-  const rememberChoice = useCallback(
-    (patch: Record<string, unknown>) => {
-      void updateCart(client, cart.id, { metadata: patch }).catch(() => {
-        // Best effort: forgetting a choice on reload is a worse checkout,
-        // never a broken one, so a failure here must not reach the shopper.
-      })
+  const rememberChoice = useCallback(
+    (patch: Record<string, unknown>) => {
+      return updateCart(client, cart.id, { metadata: patch })
+        .then(() => true)
+        .catch(() => {
+          // Best effort: forgetting a choice on reload is a worse checkout,
+          // never a broken one, so a failure here must not reach the shopper.
+          return false
+        })
     },
-    [client, cart.id]
-  )
+    [client, cart.id]
+  )
+  const choiceWrites = useMemo(
+    () => createLatestWriteQueue<Record<string, unknown>>(),
+    []
+  )
+  const enqueueChoiceWrite = useCallback(
+    (patch: Record<string, unknown>) => {
+      choiceWrites.push(patch, rememberChoice)
+    },
+    [choiceWrites, rememberChoice]
+  )
 
   // Shipping selection stays client state for the ORDER (no
   // addShippingMethod call, no metadata-clear updateCart: those wrote to the
@@ -1113,9 +1165,23 @@ export function useCheckoutOrchestration({
   // CHOICE, under our own key, so a reload restores it.
   const handleSelectShipping = useCallback(
     (id: string) => {
-      setShippingError(null)
-      setSelectedShippingMethod(id)
-      rememberChoice({ _checkout_shipping_option: id })
+      setShippingError(null)
+      setSelectedShippingMethod(id)
+
+      // The availability map came from the server with the checkout's first
+      // read. Selecting one of its answers is immediate and deterministic;
+      // no browser-side rule is being guessed. Older refreshes are invalidated
+      // before they can repaint a newer click.
+      const mappedPaymentMethods = paymentMethodsByShippingOption?.[id]
+      if (mappedPaymentMethods) {
+        paymentListingRequest.current += 1
+        setServerAvailablePaymentMethods(mappedPaymentMethods)
+      } else {
+        // Backward compatibility for hosts/platforms without the map: ask the
+        // rules endpoint about this prospective option immediately, without
+        // waiting for the preference write to make a round trip first.
+        void refreshPaymentMethods(id)
+      }
 
       // Optimistic shipping cost — paint the totals row immediately so
       // the customer sees the right number before any network call.
@@ -1135,14 +1201,20 @@ export function useCheckoutOrchestration({
       // our own note is cleared beside the state.
       setSelectedPickupPoint(null)
       setPickupKeys(null)
-      rememberChoice({
-        _checkout_shipping_option: id,
-        _checkout_pickup_point: null,
-        _checkout_pickup_keys: null,
-      })
-    },
-    [shippingMethods, calculatedPricesMap, rememberChoice]
-  )
+      enqueueChoiceWrite({
+        _checkout_shipping_option: id,
+        _checkout_pickup_point: null,
+        _checkout_pickup_keys: null,
+      })
+    },
+    [
+      shippingMethods,
+      calculatedPricesMap,
+      paymentMethodsByShippingOption,
+      refreshPaymentMethods,
+      enqueueChoiceWrite,
+    ]
+  )
 
   /**
    * The chosen pickup point, remembered the moment it is chosen. The keys
@@ -1154,13 +1226,13 @@ export function useCheckoutOrchestration({
     (point: PickupPoint | null, keys: PickupPointKeys | null) => {
       setSelectedPickupPoint(point)
       setPickupKeys(keys)
-      rememberChoice({
-        _checkout_pickup_point: point,
-        _checkout_pickup_keys: keys,
-      })
-    },
-    [rememberChoice]
-  )
+      enqueueChoiceWrite({
+        _checkout_pickup_point: point,
+        _checkout_pickup_keys: keys,
+      })
+    },
+    [enqueueChoiceWrite]
+  )
 
   // ── Delivery readiness ──────────────────────────────────────────────
   const selectedFulfillmentOptionId = useMemo(() => {
@@ -1197,19 +1269,18 @@ export function useCheckoutOrchestration({
       (cart?.shipping_methods?.length ?? 0) > 0) &&
     pickupSatisfied
 
-  // Reconcile paymentTab with currently-available methods. When the
-  // store's paymentMethodFilter strips a method in response to a shipping
-  // change (e.g. BoxNow → no COD), the previously selected tab can point
-  // to a method that's no longer rendered — leaving the remaining tab's
-  // radio looking unselected and the form collapsed.
-  useEffect(() => {
-    if (!deliveryReady) return
-    if (paymentTab === "cod" && !hasCod && hasCard) {
+  // Reconcile paymentTab with currently-available methods. The server map
+  // changes the rendered list synchronously on a shipping click; this effect
+  // then moves selection and fee state onto the first valid tender. It does
+  // not wait for delivery readiness: a locker may still need its point, but
+  // its payment rule is already true.
+  useEffect(() => {
+    if (paymentTab === "cod" && !hasCod && hasCard) {
       handlePaymentTab("card")
     } else if (paymentTab === "card" && !hasCard && hasCod) {
       handlePaymentTab("cod")
     }
-  }, [deliveryReady, paymentTab, hasCard, hasCod, handlePaymentTab])
+  }, [paymentTab, hasCard, hasCod, handlePaymentTab])
 
   const handlePaymentElementChange = useCallback(
     (_e: { complete: boolean; selectedMethod: string | null }) => {

package/src/locales/bg.ts

@@ -182,12 +182,12 @@ export const bg: StorefrontLocale = {
     remove: "Премахни",
     secureCheckout: "Защитено плащане",
 
-    giftCard: "Карта за подарък",
-    giftCardSub: "Използвайте карта за подарък",
+    giftCard: "Подаръчен ваучер",
+    giftCardSub: "Въведете код за ваучер",
     giftCardPlaceholder: "GIFT-XXXX-XXXX",
-    giftCardApplied: "Карти за подарък",
+    giftCardApplied: "Подаръчни ваучери",
     giftCardRemaining: "Остава за плащане",
-    giftCardEnding: "Карта, завършваща на",
+    giftCardEnding: "Ваучер, завършващ на",
 
     companyInvoice: "Фактура за фирма",
     companyName: "Име на фирма",