@cartbase/storefront 0.2.0 → 0.3.0

package/src/checkout/order-summary.tsx

@@ -19,12 +19,12 @@ import { GiftCardSection } from "./gift-card-section"
  * Ported from `@1click/ui/src/checkout/order-summary.tsx` (v2.3.1) with
  * the Cartbase data seam:
  *
- *  - COD fee is CART-LEVEL decoration on the Cartbase wire —
- *    `cart.cod_fee_total` / `cart.cod_fee_label`, folded into `cart.total`
- *    while a live pp_cod session exists (docs/storefront/checkout.md) —
- *    NOT a metadata-flagged fee line item. The fee row + optimistic math
- *    read those fields; `isProductLine` is kept as a defensive filter for
- *    any legacy fee-line carts.
+ *  - The payment method fee is CART-LEVEL decoration on the Cartbase wire —
+ *    `cart.payment_method_fee_total` / `payment_method_fee_label`, folded
+ *    into `cart.total` while a live method session exists
+ *    (docs/storefront/checkout.md) — NOT a metadata-flagged fee line item.
+ *    The fee row + optimistic math read those fields; `isProductLine` is
+ *    kept as a defensive filter for any legacy fee-line carts.
  *  - Gift-card tender rows (Cartbase feature): `gift_card_total` renders as
  *    a negative tender row and `gift_card_remainder` as "Remaining to pay"
  *    UNDER the (unchanged) total — tender never moves totals
@@ -211,22 +211,22 @@ type OrderSummaryProps = {
   optimisticShippingCost: number | null
   onOptimisticShippingClear?: () => void
   /**
-   * Optimistic COD-fee prediction. Three values:
+   * Optimistic method-fee prediction. Three values:
    *   - null         → no prediction; render whatever the cart says.
-   *   - 0            → predict no fee (toggling away from COD).
+   *   - 0            → predict no fee (toggling to a fee-less tender).
    *   - positive     → predict the fee at this amount.
-   * Pass `useCheckoutOrchestration`'s `optimisticCodFee`. Needed because
-   * the deferred-checkout architecture defers the pp_cod session (and so
-   * the native fee) until Buy click.
+   * Pass `useCheckoutOrchestration`'s `optimisticMethodFee`. Needed because
+   * the deferred-checkout architecture defers the method session (and so
+   * the fee) until Buy click.
    */
-  optimisticCodFee?: number | null
-  onOptimisticCodFeeClear?: () => void
+  optimisticMethodFee?: number | null
+  onOptimisticMethodFeeClear?: () => void
   /**
-   * Override label for the cash-on-delivery fee row. Optional — falls
-   * back to the cart's server-provided `cod_fee_label` (admin-configured
-   * on the COD integration), then to `labels.codFee`.
+   * Override label for the payment-method fee row. Optional — falls back
+   * to the cart's server-provided `payment_method_fee_label` (the method's
+   * own fee_label), then to `labels.paymentMethodFee`.
    */
-  codFeeLabel?: string
+  methodFeeLabel?: string
   /** Show the gift-card widget. Default true; pass false for stores that
    * haven't enabled gift cards (the widget itself is harmless either way —
    * an unknown code gets the generic refusal). */
@@ -246,9 +246,9 @@ export function OrderSummary({
   cart,
   optimisticShippingCost,
   onOptimisticShippingClear,
-  optimisticCodFee,
-  onOptimisticCodFeeClear,
-  codFeeLabel,
+  optimisticMethodFee,
+  onOptimisticMethodFeeClear,
+  methodFeeLabel,
   showGiftCards = true,
   onCartChange,
 }: OrderSummaryProps) {
@@ -268,39 +268,39 @@ export function OrderSummary({
     optimisticShippingCost !== null ? optimisticShippingCost : cart.shipping_total
   const shippingKnown = shippingCost !== null && shippingCost !== undefined
 
-  // Effective COD fee: optimistic prediction wins until the cart catches
-  // up. Three states (null / 0 / positive). Cartbase server truth is
-  // `cart.cod_fee_total` (folded into cart.total while a pp_cod session
-  // lives — docs/storefront/checkout.md).
-  const realCodFeeAmount = cart.cod_fee_total ?? 0
-  const effectiveCodFee =
-    optimisticCodFee !== null && optimisticCodFee !== undefined
-      ? optimisticCodFee
-      : realCodFeeAmount
+  // Effective method fee: optimistic prediction wins until the cart
+  // catches up. Three states (null / 0 / positive). Server truth is
+  // `cart.payment_method_fee_total` (folded into cart.total while a live
+  // method session exists — docs/storefront/checkout.md).
+  const realMethodFeeAmount = cart.payment_method_fee_total ?? 0
+  const effectiveMethodFee =
+    optimisticMethodFee !== null && optimisticMethodFee !== undefined
+      ? optimisticMethodFee
+      : realMethodFeeAmount
 
   const displayTotal = useMemo(() => {
     let total = cart.total ?? 0
     if (optimisticShippingCost !== null) {
       total = total - (cart.shipping_total ?? 0) + optimisticShippingCost
     }
-    if (optimisticCodFee !== null && optimisticCodFee !== undefined) {
-      total = total - realCodFeeAmount + effectiveCodFee
+    if (optimisticMethodFee !== null && optimisticMethodFee !== undefined) {
+      total = total - realMethodFeeAmount + effectiveMethodFee
     }
     return total
   }, [
     cart.total,
     cart.shipping_total,
     optimisticShippingCost,
-    optimisticCodFee,
-    effectiveCodFee,
-    realCodFeeAmount,
+    optimisticMethodFee,
+    effectiveMethodFee,
+    realMethodFeeAmount,
   ])
 
-  // Subtotal: Cartbase's `item_total` is products-only (the COD fee is not a
+  // Subtotal: Cartbase's `item_total` is products-only (the fee is not a
   // line item), so no fee subtraction is needed — direct server truth.
   const productSubtotal = cart.item_total ?? 0
 
-  const codFeeAmount = effectiveCodFee
+  const methodFeeAmount = effectiveMethodFee
 
   // Gift-card tender decoration — SERVER truth, rendered as-is. Totals
   // never move; the tender rows sit under the total.
@@ -317,13 +317,13 @@ export function OrderSummary({
     }
   }, [cart.shipping_total, optimisticShippingCost, onOptimisticShippingClear])
 
-  // Clear optimistic COD fee once the cart's decoration matches the
-  // prediction (Cartbase: cod_fee_total, not a fee line item).
+  // Clear the optimistic fee once the cart's decoration matches the
+  // prediction (payment_method_fee_total, not a fee line item).
   useEffect(() => {
-    if (optimisticCodFee === null || optimisticCodFee === undefined) return
-    const synced = realCodFeeAmount === optimisticCodFee
-    if (synced) onOptimisticCodFeeClear?.()
-  }, [optimisticCodFee, realCodFeeAmount, onOptimisticCodFeeClear])
+    if (optimisticMethodFee === null || optimisticMethodFee === undefined) return
+    const synced = realMethodFeeAmount === optimisticMethodFee
+    if (synced) onOptimisticMethodFeeClear?.()
+  }, [optimisticMethodFee, realMethodFeeAmount, onOptimisticMethodFeeClear])
 
   return (
     <div>
@@ -404,13 +404,13 @@ export function OrderSummary({
             )}
           </div>
 
-          {codFeeAmount > 0 && (
+          {methodFeeAmount > 0 && (
             <div className="flex justify-between text-sm">
               <span className="text-muted-foreground">
-                {codFeeLabel ?? cart.cod_fee_label ?? labels.codFee}
+                {methodFeeLabel ?? cart.payment_method_fee_label ?? labels.paymentMethodFee}
               </span>
               <DualPrice
-                amount={codFeeAmount}
+                amount={methodFeeAmount}
                 currencyCode={cart.currency_code}
                 className="font-medium text-foreground"
               />

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

@@ -21,13 +21,14 @@ import type { CheckoutLogError } from "./use-checkout-orchestration"
  * Ported from `@1click/ui/src/checkout/payment-method-list.tsx` (v2.3.1)
  * with the Cartbase data seam: the `cart` prop is structural, and the
  * `logCheckoutError` Supabase writer becomes the optional `logError`
- * callback. Provider semantics on the Cartbase wire: the "card" tab is
- * `pp_stripe`, the "cod" tab is `pp_cod` (native fee via the integrations
- * `cod` block) or `pp_manual` (offline, no fee) — the orchestration hook
- * resolves the ids (`hasCard`/`hasCod`/`cardId`/`codId`); both listings
- * arrive rule-filtered server-side (`checkout.listPaymentProviders`,
- * docs/storefront/checkout.md). COD stays a separate rail — it's a plain
- * provider session, not a Stripe payment method.
+ * callback. Tender semantics on the Cartbase wire (pp_* kill): the "card"
+ * tab is the connected processor (`pp_stripe`); the "cod" tab is a
+ * merchant METHOD — the COD switch (native fee via the integrations `cod`
+ * block) or a manual method (no fee) — the orchestration hook resolves
+ * them (`hasCard`/`hasCod`/`cardId`/`codMethodId`); both listings arrive
+ * rule-filtered server-side (`checkout.listPaymentProviders`,
+ * docs/storefront/checkout.md). The method tab stays a separate rail —
+ * it's a provider-less session, not a Stripe payment method.
  */
 
 type CheckoutPaymentMethodListProps = {
@@ -87,6 +88,15 @@ type CheckoutPaymentMethodListProps = {
   total?: number
   /** Operational-visibility sink (successor of @1click's logCheckoutError). */
   logError?: CheckoutLogError
+  /**
+   * Additional payment tabs rendered as radio cards in the same visual
+   * language as the built-in card/cod tabs. The seam for embedded
+   * third-party providers (a myPOS-style frame carries its own pay
+   * action, so while an extra tab is active the PaymentButton is hidden
+   * and the tab's `content` owns completion). Absent = exact previous
+   * behavior.
+   */
+  extraTabs?: Array<{ id: string; label: string; content: React.ReactNode }>
 }
 
 export function CheckoutPaymentMethodList({
@@ -105,9 +115,14 @@ export function CheckoutPaymentMethodList({
   beforePaymentButton,
   total,
   logError,
+  extraTabs,
 }: CheckoutPaymentMethodListProps) {
   const labels = useCheckoutLabels()
 
+  // Which extra tab is active, if any. Selecting card/cod clears it; the
+  // radio group stays single-select across built-in and extra tabs.
+  const [extraTab, setExtraTab] = useState<string | null>(null)
+
   // When the store opts out of gating (gatePaymentUntilDelivery=false),
   // the payment section is always shown + interactive regardless of
   // delivery readiness. The Buy button remains independently gated by
@@ -203,23 +218,26 @@ export function CheckoutPaymentMethodList({
               <div
                 className={cn(
                   "rounded-lg border overflow-hidden transition-colors duration-150",
-                  paymentTab === "card"
+                  paymentTab === "card" && !extraTab
                     ? "border-primary bg-primary/5"
                     : "border-border bg-card hover:border-muted-foreground"
                 )}
               >
                 <button
                   type="button"
-                  onClick={() => onPaymentTab("card")}
+                  onClick={() => {
+                    setExtraTab(null)
+                    onPaymentTab("card")
+                  }}
                   className="flex items-center w-full px-4 py-3.5 text-left"
                 >
                   <div
                     className={cn(
                       "w-[18px] h-[18px] rounded-full border-2 flex items-center justify-center flex-shrink-0 mr-3 transition-colors",
-                      paymentTab === "card" ? "border-primary" : "border-border"
+                      paymentTab === "card" && !extraTab ? "border-primary" : "border-border"
                     )}
                   >
-                    {paymentTab === "card" && (
+                    {paymentTab === "card" && !extraTab && (
                       <div className="w-2 h-2 rounded-full bg-primary" />
                     )}
                   </div>
@@ -228,7 +246,7 @@ export function CheckoutPaymentMethodList({
                   </span>
                 </button>
 
-                {paymentTab === "card" && (
+                {paymentTab === "card" && !extraTab && (
                   <div className="px-4 pb-4 pt-2">
                     {/*
                       Skeleton vs PaymentElement gated by stripeReady.
@@ -279,23 +297,26 @@ export function CheckoutPaymentMethodList({
               <div
                 className={cn(
                   "rounded-lg border overflow-hidden transition-colors duration-150",
-                  paymentTab === "cod"
+                  paymentTab === "cod" && !extraTab
                     ? "border-primary bg-primary/5"
                     : "border-border bg-card hover:border-muted-foreground"
                 )}
               >
                 <button
                   type="button"
-                  onClick={() => onPaymentTab("cod")}
+                  onClick={() => {
+                    setExtraTab(null)
+                    onPaymentTab("cod")
+                  }}
                   className="flex items-center w-full px-4 py-3.5 text-left"
                 >
                   <div
                     className={cn(
                       "w-[18px] h-[18px] rounded-full border-2 flex items-center justify-center flex-shrink-0 mr-3 transition-colors",
-                      paymentTab === "cod" ? "border-primary" : "border-border"
+                      paymentTab === "cod" && !extraTab ? "border-primary" : "border-border"
                     )}
                   >
-                    {paymentTab === "cod" && (
+                    {paymentTab === "cod" && !extraTab && (
                       <div className="w-2 h-2 rounded-full bg-primary" />
                     )}
                   </div>
@@ -303,7 +324,7 @@ export function CheckoutPaymentMethodList({
                     {labels.cashOnDelivery}
                   </span>
                 </button>
-                {paymentTab === "cod" && (
+                {paymentTab === "cod" && !extraTab && (
                   <div className="px-4 pb-3 pt-0">
                     <p className="text-xs text-muted-foreground ml-[30px]">
                       {labels.codNote}
@@ -312,6 +333,41 @@ export function CheckoutPaymentMethodList({
                 )}
               </div>
             )}
+
+            {extraTabs?.map((tab) => (
+              <div
+                key={tab.id}
+                className={cn(
+                  "rounded-lg border overflow-hidden transition-colors duration-150",
+                  extraTab === tab.id
+                    ? "border-primary bg-primary/5"
+                    : "border-border bg-card hover:border-muted-foreground"
+                )}
+              >
+                <button
+                  type="button"
+                  onClick={() => setExtraTab(tab.id)}
+                  className="flex items-center w-full px-4 py-3.5 text-left"
+                >
+                  <div
+                    className={cn(
+                      "w-[18px] h-[18px] rounded-full border-2 flex items-center justify-center flex-shrink-0 mr-3 transition-colors",
+                      extraTab === tab.id ? "border-primary" : "border-border"
+                    )}
+                  >
+                    {extraTab === tab.id && (
+                      <div className="w-2 h-2 rounded-full bg-primary" />
+                    )}
+                  </div>
+                  <span className="text-sm font-medium text-foreground">
+                    {tab.label}
+                  </span>
+                </button>
+                {extraTab === tab.id && (
+                  <div className="px-4 pb-4 pt-2">{tab.content}</div>
+                )}
+              </div>
+            ))}
           </div>
 
           <ErrorMessage
@@ -323,7 +379,7 @@ export function CheckoutPaymentMethodList({
             <div className="mt-5">{beforePaymentButton}</div>
           )}
 
-          {buyButtonNotReady && buyButtonNotReadyReason && (
+          {!extraTab && buyButtonNotReady && buyButtonNotReadyReason && (
             <div className="mt-4 flex items-center justify-center gap-1.5 text-muted-foreground">
               <svg
                 viewBox="0 0 24 24"
@@ -344,20 +400,24 @@ export function CheckoutPaymentMethodList({
             </div>
           )}
 
-          <div className="mt-5">
-            <PaymentButton
-              cart={cart}
-              paymentTab={paymentTab}
-              notReady={buyButtonNotReady}
-              performBuyClick={performBuyClick}
-              paymentElementComplete={
-                paymentTab === "cod" ? true : paymentElementComplete
-              }
-              total={total}
-              logError={logError}
-              data-testid="submit-order-button"
-            />
-          </div>
+          {/* An active extra tab owns its own pay action (embedded
+              provider frames ship their own button), so ours hides. */}
+          {!extraTab && (
+            <div className="mt-5">
+              <PaymentButton
+                cart={cart}
+                paymentTab={paymentTab}
+                notReady={buyButtonNotReady}
+                performBuyClick={performBuyClick}
+                paymentElementComplete={
+                  paymentTab === "cod" ? true : paymentElementComplete
+                }
+                total={total}
+                logError={logError}
+                data-testid="submit-order-button"
+              />
+            </div>
+          )}
         </StripeElementsScope>
       )}
     </div>