@tribe-nest/forge 1.13.0

package/src/ui/styled/Checkout.tsx

@@ -0,0 +1,988 @@
+import React, { useEffect, useState } from "react";
+import { useForm, Controller } from "react-hook-form";
+import { CreditCard, MapPin, Package, User } from "lucide-react";
+import { useCheckout, CHECKOUT_STAGE_ORDER, type CheckoutStage } from "../headless/checkout/useCheckout";
+import type { SelectedShippingRate } from "../headless/checkout/useCheckout";
+import type { ShippingRate, ShippingGroup } from "../../data/queries/useShipping";
+import { useForgeTheme } from "../theme/ForgeThemeProvider";
+import { readableTextOn } from "../theme/contrast";
+import { useFormatCurrency } from "../format/useFormatCurrency";
+import { summarizeTaxQuote } from "../format/PriceDisplay";
+import { usePricesIncludeTax } from "../../data/queries/useWebsite";
+import { usePaymentRenderer } from "../payment/ForgePaymentProvider";
+import { Loading } from "./Loading";
+
+export interface CheckoutProps {
+  /** Path used to build the post-payment return URL. Defaults to `/checkout/finalise`. */
+  finalisePath?: string;
+  /** Where "Continue shopping" (empty cart) goes. Defaults to `/store`. */
+  storePath?: string;
+  /** Where the guest "Login" button goes (a `?redirect=` back to this page is appended). Defaults to `/login`. */
+  loginPath?: string;
+  /** SPA navigation. Defaults to a full-page `window.location` redirect. */
+  onNavigate?: (path: string) => void;
+  className?: string;
+  style?: React.CSSProperties;
+}
+
+function alpha(value: number) {
+  return Math.round(value * 255)
+    .toString(16)
+    .padStart(2, "0");
+}
+
+type GuestFormData = { firstName: string; lastName: string; email: string };
+type ShippingFormData = {
+  address1: string;
+  city: string;
+  stateCode: string;
+  countryCode: string;
+  zip: string;
+  phone: string;
+};
+
+const stageIdx = (s: CheckoutStage) => CHECKOUT_STAGE_ORDER.indexOf(s);
+
+/**
+ * Themed cart checkout — the full staged flow the client app ships, built on
+ * `useCheckout`: guest details → (physical only) shipping address + per-product
+ * rate selection → create order + start payment → coupon → redirect payment (or
+ * a free-order shortcut). Inline-themed from `ForgeThemeProvider`; the payment
+ * UI (Stripe) is rendered by Forge itself, and every amount formats through
+ * `useFormatCurrency`, whose source currency is the tenant's runtime settlement
+ * currency — so nothing here needs a baked currency.
+ */
+export function Checkout({
+  finalisePath = "/checkout/finalise",
+  storePath = "/store",
+  loginPath = "/login",
+  onNavigate,
+  className,
+  style,
+}: CheckoutProps) {
+  const theme = useForgeTheme();
+  const { formatCurrency } = useFormatCurrency();
+  // Store display mode (site config) — drives the pre-quote "incl. tax" caption.
+  // Once the payment starts, the authoritative taxQuote from start-payment wins.
+  const pricesIncludeTax = usePricesIncludeTax();
+
+  const c = useCheckout({ finalisePath });
+  const taxSummary = summarizeTaxQuote(c.taxQuote, formatCurrency);
+
+  const go = (path: string) => {
+    if (onNavigate) onNavigate(path);
+    else if (typeof window !== "undefined") window.location.href = path;
+  };
+
+  // Guest + shipping forms (react-hook-form). Declared unconditionally; only the
+  // relevant one is rendered per stage.
+  const guestForm = useForm<GuestFormData>({ defaultValues: { firstName: "", lastName: "", email: "" } });
+  const shippingForm = useForm<ShippingFormData>({
+    defaultValues: { address1: "", city: "", stateCode: "", countryCode: "", zip: "", phone: "" },
+  });
+
+  // Reset the chosen state whenever the country changes (form-level).
+  const selectedCountryCode = shippingForm.watch("countryCode");
+  const selectedCountry = c.countries.find((country) => country.code === selectedCountryCode);
+  useEffect(() => {
+    if (selectedCountryCode) shippingForm.setValue("stateCode", "");
+  }, [selectedCountryCode, shippingForm]);
+
+  const handleLogin = () => {
+    const here = typeof window !== "undefined" ? window.location.pathname : "/checkout";
+    go(`${loginPath}?redirect=${encodeURIComponent(here)}`);
+  };
+
+  const handleFreeCheckout = async () => {
+    const id = await c.freeCheckout();
+    if (id) go(`${finalisePath}?orderId=${id}`);
+  };
+
+  // ── Shared style helpers ────────────────────────────────────────────────────
+  const inputStyle: React.CSSProperties = {
+    width: "100%",
+    padding: "8px 12px",
+    border: `1px solid ${theme.colors.primary}${alpha(0.3)}`,
+    backgroundColor: theme.colors.background,
+    color: theme.colors.text,
+    borderRadius: `${theme.cornerRadius}px`,
+  };
+
+  const PrimaryButton = ({
+    text,
+    onClick,
+    type = "button",
+    fullWidth,
+    disabled,
+  }: {
+    text: string;
+    onClick?: () => void;
+    type?: "button" | "submit";
+    fullWidth?: boolean;
+    disabled?: boolean;
+  }) => (
+    <button
+      type={type}
+      onClick={onClick}
+      disabled={disabled}
+      className={fullWidth ? "w-full" : ""}
+      style={{
+        padding: "12px 18px",
+        backgroundColor: theme.colors.primary,
+        color: readableTextOn(theme.colors.primary),
+        border: "none",
+        borderRadius: `${theme.cornerRadius}px`,
+        fontWeight: 600,
+        cursor: disabled ? "not-allowed" : "pointer",
+        opacity: disabled ? 0.6 : 1,
+      }}
+    >
+      {text}
+    </button>
+  );
+
+  const SecondaryButton = ({ text, onClick, fullWidth }: { text: string; onClick?: () => void; fullWidth?: boolean }) => (
+    <button
+      type="button"
+      onClick={onClick}
+      className={fullWidth ? "w-full" : ""}
+      style={{
+        padding: "12px 18px",
+        backgroundColor: "transparent",
+        color: theme.colors.primary,
+        border: `1px solid ${theme.colors.primary}`,
+        borderRadius: `${theme.cornerRadius}px`,
+        fontWeight: 600,
+        cursor: "pointer",
+      }}
+    >
+      {text}
+    </button>
+  );
+
+  // The cart loads from storage after mount; don't flash the empty state until we
+  // actually know it's empty.
+  if (!c.isCartReady) {
+    return <Loading fullPage />;
+  }
+
+  if (c.cartItems.length === 0) {
+    return (
+      <div
+        className={["w-full max-w-4xl mx-auto p-6", className].filter(Boolean).join(" ")}
+        style={{ backgroundColor: theme.colors.background, color: theme.colors.text, fontFamily: theme.fontFamily, ...style }}
+      >
+        <div className="text-center py-12">
+          <h1 className="text-2xl font-bold mb-4" style={{ color: theme.colors.text }}>
+            Your cart is empty
+          </h1>
+          <p className="mb-6" style={{ color: `${theme.colors.text}${alpha(0.7)}` }}>
+            Add some items to your cart before checking out.
+          </p>
+          <PrimaryButton text="Continue Shopping" onClick={() => go(storePath)} />
+        </div>
+      </div>
+    );
+  }
+
+  const stages = c.hasPhysicalProduct
+    ? [
+        { key: "userDetails" as const, label: "User", icon: User },
+        { key: "shippingAddress" as const, label: "Address", icon: MapPin },
+        { key: "shippingRates" as const, label: "Shipping", icon: Package },
+        { key: "payment" as const, label: "Payment", icon: CreditCard },
+      ]
+    : [
+        { key: "userDetails" as const, label: "User", icon: User },
+        { key: "payment" as const, label: "Payment", icon: CreditCard },
+      ];
+
+  const currentIdx = stageIdx(c.currentStage);
+
+  return (
+    <div
+      className={["w-full max-w-6xl mx-auto p-6", className].filter(Boolean).join(" ")}
+      style={{ backgroundColor: theme.colors.background, color: theme.colors.text, fontFamily: theme.fontFamily, ...style }}
+    >
+      {/* Progress Indicator */}
+      <div className="mb-8">
+        <div className="flex items-center justify-center space-x-4">
+          {stages.map((stage, idx) => {
+            const reached = currentIdx >= stageIdx(stage.key);
+            return (
+              <React.Fragment key={stage.key}>
+                {idx > 0 && <div className="w-4 h-0.5" style={{ backgroundColor: `${theme.colors.text}${alpha(0.3)}` }} />}
+                <div
+                  className="flex items-center"
+                  style={{ color: reached ? theme.colors.primary : `${theme.colors.text}${alpha(0.4)}` }}
+                >
+                  <div
+                    className="w-8 h-8 rounded-full flex items-center justify-center border-2"
+                    style={{
+                      borderColor: reached ? theme.colors.primary : `${theme.colors.text}${alpha(0.3)}`,
+                      backgroundColor: reached ? theme.colors.primary : "transparent",
+                      color: reached ? "#fff" : theme.colors.text,
+                      borderRadius: `${theme.cornerRadius}px`,
+                    }}
+                  >
+                    <stage.icon size={16} />
+                  </div>
+                  <span className="ml-2">{stage.label}</span>
+                </div>
+              </React.Fragment>
+            );
+          })}
+        </div>
+      </div>
+
+      <div className="grid grid-cols-1 lg:grid-cols-3 gap-8">
+        {/* Main Content */}
+        <div className="lg:col-span-2">
+          {c.pageError && (
+            <div
+              className="mb-4 p-3 text-sm"
+              style={{ color: "#ef4444", border: "1px solid #ef444440", borderRadius: `${theme.cornerRadius}px` }}
+            >
+              {c.pageError}
+            </div>
+          )}
+
+          {/* Stage: User Details */}
+          {c.currentStage === "userDetails" && !c.user && (
+            <div
+              className="rounded-lg shadow-md p-6"
+              style={{
+                backgroundColor: theme.colors.background,
+                border: `1px solid ${theme.colors.primary}${alpha(0.2)}`,
+                borderRadius: `${theme.cornerRadius}px`,
+              }}
+            >
+              <div className="pb-6" style={{ borderTop: `1px solid ${theme.colors.primary}${alpha(0.2)}` }}>
+                <h3 className="text-lg font-semibold mb-4" style={{ color: theme.colors.text }}>
+                  Already have an account?
+                </h3>
+                <PrimaryButton text="Login" onClick={handleLogin} fullWidth />
+              </div>
+              <h2 className="text-2xl font-bold mb-6" style={{ color: theme.colors.text }}>
+                Or
+              </h2>
+
+              <div className="mb-6">
+                <h3 className="text-lg font-semibold mb-4" style={{ color: theme.colors.text }}>
+                  Continue as Guest
+                </h3>
+                <form onSubmit={guestForm.handleSubmit(c.submitGuest)} className="space-y-4">
+                  <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+                    <div>
+                      <label className="block text-sm font-medium mb-2" style={{ color: theme.colors.text }}>
+                        First Name
+                      </label>
+                      <Controller
+                        control={guestForm.control}
+                        name="firstName"
+                        rules={{ required: "First name is required" }}
+                        render={({ field }) => <input {...field} placeholder="First Name" style={inputStyle} />}
+                      />
+                      {guestForm.formState.errors.firstName && (
+                        <p className="text-sm text-red-500 mt-1">{guestForm.formState.errors.firstName.message}</p>
+                      )}
+                    </div>
+                    <div>
+                      <label className="block text-sm font-medium mb-2" style={{ color: theme.colors.text }}>
+                        Last Name
+                      </label>
+                      <Controller
+                        control={guestForm.control}
+                        name="lastName"
+                        rules={{ required: "Last name is required" }}
+                        render={({ field }) => <input {...field} placeholder="Last Name" style={inputStyle} />}
+                      />
+                      {guestForm.formState.errors.lastName && (
+                        <p className="text-sm text-red-500 mt-1">{guestForm.formState.errors.lastName.message}</p>
+                      )}
+                    </div>
+                  </div>
+                  <div>
+                    <label className="block text-sm font-medium mb-2" style={{ color: theme.colors.text }}>
+                      Email
+                    </label>
+                    <Controller
+                      control={guestForm.control}
+                      name="email"
+                      rules={{
+                        required: "Email is required",
+                        pattern: { value: /^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i, message: "Invalid email address" },
+                      }}
+                      render={({ field }) => <input {...field} type="email" placeholder="Email" style={inputStyle} />}
+                    />
+                    {guestForm.formState.errors.email && (
+                      <p className="text-sm text-red-500 mt-1">{guestForm.formState.errors.email.message}</p>
+                    )}
+                  </div>
+                  <div className="flex items-start gap-2">
+                    <input
+                      type="checkbox"
+                      id="joinEmailList"
+                      checked={c.joinEmailList}
+                      onChange={(e) => c.setJoinEmailList(e.target.checked)}
+                      className="mt-1 h-4 w-4 rounded"
+                      style={{ accentColor: theme.colors.primary }}
+                    />
+                    <label htmlFor="joinEmailList" className="text-sm" style={{ color: theme.colors.text }}>
+                      Sign up to receive updates
+                    </label>
+                  </div>
+                  <PrimaryButton text="Continue as Guest" type="submit" fullWidth />
+                </form>
+              </div>
+            </div>
+          )}
+
+          {/* Stage: Shipping Address */}
+          {c.currentStage === "shippingAddress" && c.hasPhysicalProduct && (
+            <div
+              className="rounded-lg shadow-md p-6"
+              style={{
+                backgroundColor: theme.colors.background,
+                border: `1px solid ${theme.colors.primary}${alpha(0.2)}`,
+                borderRadius: `${theme.cornerRadius}px`,
+              }}
+            >
+              <h2 className="text-2xl font-bold mb-6" style={{ color: theme.colors.text }}>
+                Shipping Address
+              </h2>
+              <form onSubmit={shippingForm.handleSubmit(c.submitAddress)} className="space-y-4">
+                <div>
+                  <label className="block text-sm font-medium mb-2" style={{ color: theme.colors.text }}>
+                    Address Line 1
+                  </label>
+                  <Controller
+                    control={shippingForm.control}
+                    name="address1"
+                    rules={{ required: "Address is required" }}
+                    render={({ field }) => <input {...field} placeholder="12 address avenue, Bankstown" style={inputStyle} />}
+                  />
+                  {shippingForm.formState.errors.address1 && (
+                    <p className="text-sm text-red-500 mt-1">{shippingForm.formState.errors.address1.message}</p>
+                  )}
+                </div>
+
+                <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+                  <div>
+                    <label className="block text-sm font-medium mb-2" style={{ color: theme.colors.text }}>
+                      City
+                    </label>
+                    <Controller
+                      control={shippingForm.control}
+                      name="city"
+                      rules={{ required: "City is required" }}
+                      render={({ field }) => <input {...field} placeholder="Sydney" style={inputStyle} />}
+                    />
+                    {shippingForm.formState.errors.city && (
+                      <p className="text-sm text-red-500 mt-1">{shippingForm.formState.errors.city.message}</p>
+                    )}
+                  </div>
+
+                  <div>
+                    <label className="block text-sm font-medium mb-2" style={{ color: theme.colors.text }}>
+                      Postal Code
+                    </label>
+                    <Controller
+                      control={shippingForm.control}
+                      name="zip"
+                      rules={{ required: "Postal code is required" }}
+                      render={({ field }) => <input {...field} placeholder="2200" style={inputStyle} />}
+                    />
+                    {shippingForm.formState.errors.zip && (
+                      <p className="text-sm text-red-500 mt-1">{shippingForm.formState.errors.zip.message}</p>
+                    )}
+                  </div>
+                </div>
+
+                <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+                  <div>
+                    <label className="block text-sm font-medium mb-2" style={{ color: theme.colors.text }}>
+                      Country
+                    </label>
+                    <Controller
+                      control={shippingForm.control}
+                      name="countryCode"
+                      rules={{ required: "Country is required" }}
+                      render={({ field }) => (
+                        <select {...field} style={inputStyle}>
+                          <option value="">Select Country</option>
+                          {c.countries.map((country) => (
+                            <option key={country.code} value={country.code}>
+                              {country.name}
+                            </option>
+                          ))}
+                        </select>
+                      )}
+                    />
+                    {shippingForm.formState.errors.countryCode && (
+                      <p className="text-sm text-red-500 mt-1">{shippingForm.formState.errors.countryCode.message}</p>
+                    )}
+                  </div>
+
+                  {selectedCountry?.states && selectedCountry.states.length > 0 && (
+                    <div>
+                      <label className="block text-sm font-medium mb-2" style={{ color: theme.colors.text }}>
+                        State/Province
+                      </label>
+                      <Controller
+                        control={shippingForm.control}
+                        name="stateCode"
+                        rules={{ required: "State/Province is required" }}
+                        render={({ field }) => (
+                          <select {...field} style={inputStyle}>
+                            <option value="">Select State/Province</option>
+                            {selectedCountry.states!.map((state) => (
+                              <option key={state.code} value={state.code}>
+                                {state.name}
+                              </option>
+                            ))}
+                          </select>
+                        )}
+                      />
+                      {shippingForm.formState.errors.stateCode && (
+                        <p className="text-sm text-red-500 mt-1">{shippingForm.formState.errors.stateCode.message}</p>
+                      )}
+                    </div>
+                  )}
+                </div>
+
+                <div>
+                  <label className="block text-sm font-medium mb-2" style={{ color: theme.colors.text }}>
+                    Phone Number
+                  </label>
+                  <Controller
+                    control={shippingForm.control}
+                    name="phone"
+                    rules={{ required: "Phone number is required" }}
+                    render={({ field }) => <input {...field} placeholder="Phone number" style={inputStyle} />}
+                  />
+                  {shippingForm.formState.errors.phone && (
+                    <p className="text-sm text-red-500 mt-1">{shippingForm.formState.errors.phone.message}</p>
+                  )}
+                </div>
+
+                <div className="flex gap-4 pt-4">
+                  {!c.user && <SecondaryButton text="Back" onClick={() => c.setCurrentStage("userDetails")} />}
+                  <PrimaryButton
+                    text={c.isFetchingRates ? "Fetching shipping rates..." : "Continue to Shipping"}
+                    type="submit"
+                    fullWidth
+                    disabled={c.isFetchingRates}
+                  />
+                </div>
+              </form>
+            </div>
+          )}
+
+          {/* Stage: Shipping Rates */}
+          {c.currentStage === "shippingRates" && c.hasPhysicalProduct && c.shippingData && (
+            <div
+              className="rounded-lg shadow-md p-6"
+              style={{
+                backgroundColor: theme.colors.background,
+                border: `1px solid ${theme.colors.primary}${alpha(0.2)}`,
+                borderRadius: `${theme.cornerRadius}px`,
+              }}
+            >
+              <h2 className="text-2xl font-bold mb-6" style={{ color: theme.colors.text }}>
+                Shipping Options
+              </h2>
+
+              <ShippingRateSelector
+                groups={c.shippingGroups}
+                selections={c.selections}
+                onSelect={c.selectShippingRate}
+                formatCurrency={formatCurrency}
+              />
+
+              <div className="flex gap-4 pt-6">
+                <SecondaryButton text="Back" onClick={() => c.setCurrentStage("shippingAddress")} />
+                <PrimaryButton
+                  text="Continue to Payment"
+                  onClick={c.confirmRates}
+                  fullWidth
+                  disabled={c.shippingGroups.some((g) => g.selectable && !c.selections[g.id])}
+                />
+              </div>
+            </div>
+          )}
+
+          {/* Stage: Payment */}
+          {c.currentStage === "payment" && c.isPaidCheckout && (
+            <PaymentSection
+              checkout={c}
+              onBack={
+                c.hasPhysicalProduct
+                  ? () => c.setCurrentStage("shippingRates")
+                  : !c.user
+                    ? () => c.setCurrentStage("userDetails")
+                    : undefined
+              }
+            />
+          )}
+
+          {/* Stage: Payment — Free */}
+          {c.currentStage === "payment" && !c.isPaidCheckout && (
+            <div
+              className="rounded-lg shadow-md p-6"
+              style={{
+                backgroundColor: theme.colors.background,
+                border: `1px solid ${theme.colors.primary}${alpha(0.2)}`,
+                borderRadius: `${theme.cornerRadius}px`,
+              }}
+            >
+              <h2 className="text-2xl font-bold mb-6" style={{ color: theme.colors.text }}>
+                Payment Information
+              </h2>
+              <p className="text-sm mb-8" style={{ color: `${theme.colors.text}${alpha(0.7)}` }}>
+                This is a free checkout. You will not be charged anything.
+              </p>
+              <PrimaryButton text="Complete Checkout" onClick={handleFreeCheckout} fullWidth disabled={c.isFreeCheckoutLoading} />
+            </div>
+          )}
+        </div>
+
+        {/* Order Summary */}
+        <div className="lg:col-span-1">
+          <div
+            className="rounded-lg shadow-md p-6 sticky top-6"
+            style={{
+              backgroundColor: theme.colors.background,
+              border: `1px solid ${theme.colors.primary}${alpha(0.2)}`,
+              borderRadius: `${theme.cornerRadius}px`,
+            }}
+          >
+            <h3 className="text-xl font-bold mb-4" style={{ color: theme.colors.text }}>
+              Order Summary
+            </h3>
+
+            {/* Customer */}
+            <div className="mb-4 pb-4" style={{ borderBottom: `1px solid ${theme.colors.primary}${alpha(0.2)}` }}>
+              <h4 className="font-semibold mb-2" style={{ color: theme.colors.text }}>
+                Customer
+              </h4>
+              {c.user ? (
+                <div className="text-sm">
+                  <p style={{ color: theme.colors.text }}>
+                    {c.user?.firstName} {c.user?.lastName}
+                  </p>
+                  <p style={{ color: `${theme.colors.text}${alpha(0.6)}` }}>{c.user?.email}</p>
+                </div>
+              ) : c.guestUserData ? (
+                <div className="text-sm">
+                  <p style={{ color: theme.colors.text }}>
+                    {c.guestUserData.firstName} {c.guestUserData.lastName}
+                  </p>
+                  <p style={{ color: `${theme.colors.text}${alpha(0.6)}` }}>{c.guestUserData.email}</p>
+                </div>
+              ) : (
+                <p className="text-sm" style={{ color: `${theme.colors.text}${alpha(0.5)}` }}>
+                  Guest checkout
+                </p>
+              )}
+            </div>
+
+            {/* Shipping Info */}
+            {c.hasPhysicalProduct && c.shippingData && (
+              <div className="mb-4 pb-4" style={{ borderBottom: `1px solid ${theme.colors.primary}${alpha(0.2)}` }}>
+                <h4 className="font-semibold mb-2" style={{ color: theme.colors.text }}>
+                  Shipping Address
+                </h4>
+                <div className="text-sm">
+                  <p style={{ color: theme.colors.text }}>{c.shippingData.address1}</p>
+                  <p style={{ color: theme.colors.text }}>
+                    {c.shippingData.city}, {c.shippingData.stateCode} {c.shippingData.zip}
+                  </p>
+                  <p style={{ color: `${theme.colors.text}${alpha(0.6)}` }}>
+                    {c.countries.find((cc) => cc.code === c.shippingData!.countryCode)?.name}
+                  </p>
+                </div>
+              </div>
+            )}
+
+            {/* Cart Items */}
+            <div className="mb-4 pb-4" style={{ borderBottom: `1px solid ${theme.colors.primary}${alpha(0.2)}` }}>
+              <h4 className="font-semibold mb-2" style={{ color: theme.colors.text }}>
+                Items
+              </h4>
+              <div className="space-y-2">
+                {c.cartItems.map((item) => (
+                  <div
+                    key={`${item.productId}-${item.productVariantId}-${item.isGift}-${item.recipientEmail}`}
+                    className="flex justify-between text-sm"
+                  >
+                    <div className="flex-1">
+                      <p className="font-medium" style={{ color: theme.colors.text }}>
+                        {item.title}
+                      </p>
+                      {item.isGift && (
+                        <p className="text-xs" style={{ color: `${theme.colors.text}${alpha(0.6)}` }}>
+                          Gift for {item.recipientName}
+                        </p>
+                      )}
+                      <p className="text-xs" style={{ color: `${theme.colors.text}${alpha(0.6)}` }}>
+                        Qty: {item.quantity}
+                      </p>
+                    </div>
+                    <p className="font-medium" style={{ color: theme.colors.text }}>
+                      {formatCurrency(item.price * item.quantity)}
+                    </p>
+                  </div>
+                ))}
+              </div>
+            </div>
+
+            {/* Coupon */}
+            {c.currentStage === "payment" && c.orderId && (
+              <div className="mb-4 pb-4" style={{ borderBottom: `1px solid ${theme.colors.primary}${alpha(0.2)}` }}>
+                {!c.showCouponInput && !c.appliedCoupon && (
+                  <button
+                    type="button"
+                    className="text-sm underline"
+                    style={{ color: theme.colors.primary }}
+                    onClick={() => c.setShowCouponInput(true)}
+                  >
+                    Have a coupon code?
+                  </button>
+                )}
+                {c.showCouponInput && !c.appliedCoupon && (
+                  <div className="flex gap-2 items-end">
+                    <div className="flex-1">
+                      <p className="text-sm mb-1" style={{ color: theme.colors.text }}>
+                        Coupon Code
+                      </p>
+                      <input
+                        placeholder="Enter coupon code"
+                        style={inputStyle}
+                        value={c.couponCode}
+                        onChange={(e) => c.setCouponCode(e.target.value.toUpperCase())}
+                      />
+                    </div>
+                    <PrimaryButton
+                      text={c.isApplyingCoupon ? "..." : "Apply"}
+                      onClick={c.applyCoupon}
+                      disabled={c.isApplyingCoupon || !c.couponCode.trim()}
+                    />
+                  </div>
+                )}
+                {c.couponError && <p className="text-sm text-red-500 mt-1">{c.couponError}</p>}
+                {c.appliedCoupon && (
+                  <div
+                    className="p-3 rounded-lg flex justify-between items-center"
+                    style={{ backgroundColor: `${theme.colors.primary}${alpha(0.1)}` }}
+                  >
+                    <div>
+                      <p className="text-sm font-semibold" style={{ color: theme.colors.primary }}>
+                        Coupon applied: {c.appliedCoupon.code}
+                      </p>
+                      <p className="text-xs" style={{ color: theme.colors.text }}>
+                        {c.appliedCoupon.discountType === "percentage"
+                          ? `${c.appliedCoupon.discountValue}% off`
+                          : `${formatCurrency(c.appliedCoupon.discountValue ?? 0)} off`}
+                      </p>
+                    </div>
+                    <button
+                      type="button"
+                      className="text-sm underline"
+                      style={{ color: theme.colors.text }}
+                      onClick={c.removeCoupon}
+                      disabled={c.isApplyingCoupon}
+                    >
+                      Remove
+                    </button>
+                  </div>
+                )}
+              </div>
+            )}
+
+            {/* Totals */}
+            <div className="space-y-2">
+              <div className="flex justify-between">
+                <span style={{ color: theme.colors.text }}>Subtotal</span>
+                <span style={{ color: theme.colors.text }}>{formatCurrency(c.subTotal)}</span>
+              </div>
+              {c.discountAmount > 0 && (
+                <div className="flex justify-between">
+                  <span style={{ color: theme.colors.text }}>Discount</span>
+                  <span style={{ color: theme.colors.primary }}>-{formatCurrency(c.discountAmount)}</span>
+                </div>
+              )}
+              {c.shippingCost > 0 && (
+                <div className="flex justify-between">
+                  <span style={{ color: theme.colors.text }}>Shipping</span>
+                  <span style={{ color: theme.colors.text }}>{formatCurrency(c.shippingCost)}</span>
+                </div>
+              )}
+              {/* Exclusive mode: the authoritative tax line, once the checkout
+                  quote is known (added on top of the total). */}
+              {taxSummary?.mode === "exclusive" && (
+                <div className="flex justify-between">
+                  <span style={{ color: theme.colors.text }}>Tax</span>
+                  <span style={{ color: theme.colors.text }}>{taxSummary.formattedTax}</span>
+                </div>
+              )}
+              <div
+                className="flex justify-between font-bold text-lg pt-2"
+                style={{ borderTop: `1px solid ${theme.colors.primary}${alpha(0.2)}`, color: theme.colors.primary }}
+              >
+                <span>Total</span>
+                <span>
+                  {c.chargedTotal
+                    ? formatCurrency(c.chargedTotal.amount, c.chargedTotal.currency)
+                    : formatCurrency(c.subTotal + c.shippingCost)}
+                </span>
+              </div>
+              {/* Inclusive mode: the total already contains tax — break out the
+                  contained amount once known, else a generic muted caption. */}
+              {taxSummary?.mode === "inclusive" ? (
+                <p className="text-xs text-right" style={{ color: `${theme.colors.text}${alpha(0.6)}`, margin: 0 }}>
+                  {taxSummary.label}
+                </p>
+              ) : (
+                !taxSummary &&
+                pricesIncludeTax && (
+                  <p className="text-xs text-right" style={{ color: `${theme.colors.text}${alpha(0.6)}`, margin: 0 }}>
+                    incl. tax
+                  </p>
+                )
+              )}
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+// ── Payment section ───────────────────────────────────────────────────────────
+/**
+ * The payment stage. The order + payment-intent are created by `useCheckout`
+ * (on entering this stage); here we only render the resolved provider UI —
+ * Stripe via the registered `<ForgePaymentProvider>` renderer, Paystack via a
+ * redirect button (the flow also auto-redirects). Re-keyed on the client secret
+ * so a coupon that re-issues the intent remounts the form against the latest one.
+ */
+function PaymentSection({
+  checkout,
+  onBack,
+}: {
+  checkout: ReturnType<typeof useCheckout>;
+  onBack?: () => void;
+}) {
+  const theme = useForgeTheme();
+  const { formatCurrency } = useFormatCurrency();
+  const renderPay = usePaymentRenderer();
+  const { paymentSecret, chargedAmount, chargedCurrency, returnUrl, isPaystack, isCreatingOrder, startError } = checkout;
+
+  // Paystack has no in-app form — send the buyer to the hosted checkout as soon
+  // as the redirect URL (paymentSecret) is ready. The button below is a manual
+  // fallback in case the automatic redirect is blocked (e.g. a pop-up blocker).
+  useEffect(() => {
+    if (isPaystack && paymentSecret && typeof window !== "undefined") {
+      window.location.href = paymentSecret;
+    }
+  }, [isPaystack, paymentSecret]);
+
+  const backButton = onBack ? (
+    <button
+      type="button"
+      onClick={onBack}
+      className="px-4 py-3 font-semibold"
+      style={{
+        border: `1px solid ${theme.colors.primary}`,
+        color: theme.colors.primary,
+        borderRadius: `${theme.cornerRadius}px`,
+      }}
+    >
+      Back
+    </button>
+  ) : null;
+
+  // Stripe (the default renderer) needs a registered provider.
+  if (!isPaystack && !renderPay) {
+    return (
+      <div
+        className="rounded-lg shadow-md p-6"
+        style={{
+          backgroundColor: theme.colors.background,
+          border: `1px solid ${theme.colors.primary}${alpha(0.2)}`,
+          borderRadius: `${theme.cornerRadius}px`,
+        }}
+      >
+        <h2 className="text-2xl font-bold mb-2" style={{ color: theme.colors.text }}>
+          Payment
+        </h2>
+        <p className="text-lg mb-4" style={{ color: theme.colors.text }}>
+          Payment is not configured
+        </p>
+        {backButton}
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className="rounded-lg shadow-md p-6"
+      style={{
+        backgroundColor: theme.colors.background,
+        border: `1px solid ${theme.colors.primary}${alpha(0.2)}`,
+        borderRadius: `${theme.cornerRadius}px`,
+      }}
+    >
+      <h2 className="text-2xl font-bold mb-6" style={{ color: theme.colors.text }}>
+        Payment Information
+      </h2>
+
+      {startError && (
+        <p className="text-sm mb-4" style={{ color: "#ef4444" }}>
+          {startError}
+        </p>
+      )}
+
+      {isCreatingOrder && !paymentSecret && <Loading label="Preparing payment…" size={22} />}
+
+      {isPaystack
+        ? paymentSecret &&
+          !!chargedAmount && (
+            <button
+              type="button"
+              onClick={() => {
+                window.location.href = paymentSecret;
+              }}
+              className="w-full px-4 py-3 font-semibold"
+              style={{
+                backgroundColor: theme.colors.primary,
+                color: readableTextOn(theme.colors.primary),
+                borderRadius: `${theme.cornerRadius}px`,
+              }}
+            >
+              {`Pay ${formatCurrency(chargedAmount, chargedCurrency || undefined)} Now`}
+            </button>
+          )
+        : paymentSecret &&
+          renderPay && (
+            <div key={paymentSecret}>
+              {renderPay({
+                clientSecret: paymentSecret,
+                returnUrl,
+                amount: chargedAmount,
+                currency: chargedCurrency || undefined,
+                mode: "redirect",
+              })}
+            </div>
+          )}
+
+      {backButton && <div className="mt-4">{backButton}</div>}
+    </div>
+  );
+}
+
+// ── Shipping rate selector ──────────────────────────────────────────────────────
+/**
+ * Renders the shipping groups: fixed lines for auto-selected flat/external
+ * groups, and a radio list for the selectable (dynamic/carrier) group. Selection
+ * state is owned by `useCheckout`; this component just renders + calls `onSelect`.
+ */
+function ShippingRateSelector({
+  groups,
+  selections,
+  onSelect,
+  formatCurrency,
+}: {
+  groups: ShippingGroup[];
+  selections: Record<string, SelectedShippingRate>;
+  onSelect: (group: ShippingGroup, rate: ShippingRate) => void;
+  formatCurrency: (amount: number, currencyCode?: string) => string;
+}) {
+  const theme = useForgeTheme();
+  if (groups.length === 0) return null;
+
+  return (
+    <div className="space-y-6">
+      {groups.map((group) => (
+        <div
+          key={group.id}
+          className="p-4 rounded-lg"
+          style={{ border: `1px solid ${theme.colors.primary}${alpha(0.15)}`, borderRadius: `${theme.cornerRadius}px` }}
+        >
+          <p className="font-medium mb-3" style={{ color: theme.colors.text }}>
+            {group.title}
+          </p>
+
+          {!group.selectable && group.rates.length > 0 ? (
+            // Flat / external — a single, auto-selected rate.
+            <div
+              className="flex items-center justify-between p-3 rounded-md"
+              style={{ backgroundColor: `${theme.colors.primary}${alpha(0.05)}`, borderRadius: `${theme.cornerRadius}px` }}
+            >
+              <div>
+                <span className="text-sm font-medium" style={{ color: theme.colors.text }}>
+                  {group.rates[0].carrier} — {group.rates[0].service}
+                </span>
+                {group.rates[0].estimatedDays != null && (
+                  <span className="text-xs ml-2" style={{ color: `${theme.colors.text}${alpha(0.6)}` }}>
+                    ({group.rates[0].estimatedDays} days)
+                  </span>
+                )}
+              </div>
+              <span className="text-sm font-semibold" style={{ color: theme.colors.primary }}>
+                {formatCurrency(group.rates[0].amount, group.rates[0].currency)}
+              </span>
+            </div>
+          ) : (
+            // Dynamic — buyer picks a carrier option.
+            <div className="space-y-2">
+              {group.rates.length === 0 && (
+                <p className="text-sm" style={{ color: `${theme.colors.text}${alpha(0.6)}` }}>
+                  No shipping options available for this address.
+                </p>
+              )}
+              {group.rates.map((rate) => {
+                const isSelected = selections[group.id]?.rateId === rate.rateId;
+                return (
+                  <label
+                    key={rate.rateId}
+                    className="flex items-center justify-between p-3 rounded-md cursor-pointer transition-colors"
+                    style={{
+                      backgroundColor: isSelected ? `${theme.colors.primary}${alpha(0.1)}` : "transparent",
+                      border: `1px solid ${isSelected ? theme.colors.primary : `${theme.colors.primary}${alpha(0.2)}`}`,
+                      borderRadius: `${theme.cornerRadius}px`,
+                    }}
+                  >
+                    <div className="flex items-center gap-3">
+                      <input
+                        type="radio"
+                        name={`shipping-rate-${group.id}`}
+                        checked={isSelected}
+                        onChange={() => onSelect(group, rate)}
+                        style={{ accentColor: theme.colors.primary }}
+                      />
+                      <div>
+                        <span className="text-sm font-medium" style={{ color: theme.colors.text }}>
+                          {rate.carrier} - {rate.service}
+                        </span>
+                        {rate.estimatedDays && (
+                          <p className="text-xs" style={{ color: `${theme.colors.text}${alpha(0.6)}` }}>
+                            Estimated {rate.estimatedDays} {rate.estimatedDays === 1 ? "day" : "days"}
+                          </p>
+                        )}
+                      </div>
+                    </div>
+                    <span className="text-sm font-semibold" style={{ color: theme.colors.primary }}>
+                      {formatCurrency(rate.amount, rate.currency)}
+                    </span>
+                  </label>
+                );
+              })}
+            </div>
+          )}
+        </div>
+      ))}
+    </div>
+  );
+}