Refactor payment methods: standalone components without deprecated containers

.github/workflows/pgk-pr-new.yaml

@@ -37,7 +37,7 @@ jobs:
         run: pnpm install --frozen-lockfile
 
       - name: Build elements 🛠
-        run: pnpm build
+        run: pnpm --filter @commercelayer/core --filter @commercelayer/hooks --filter @commercelayer/react-components build
 
       - name: Publish 🚀 pkg.pr.new
         run: |

CONTEXT.md

@@ -0,0 +1,36 @@
+# React Components — Payment
+
+This context covers the React components and state that let a storefront select a payment method and attach a payment source to an order during checkout.
+
+## Language
+
+**Payment Method**:
+A selectable payment option on an order (a configured gateway option, e.g. "Stripe"). Backed by the `payment_method` resource.
+_Avoid_: gateway (as a synonym), payment type
+
+**Payment Source**:
+The concrete payment instrument record attached to a single order (e.g. `stripe_payment`, `adyen_payment`, `wire_transfer`). Created per order from the selected Payment Method.
+_Avoid_: payment, card, token
+
+**Customer Payment Source**:
+A Payment Source saved to a Customer for reuse across orders (a stored card). Selected via the order's `_customer_payment_source_id`.
+_Avoid_: saved card (informal), wallet
+
+**Payment Gateway**:
+In this codebase, the React component that wires a specific gateway's UI/SDK and drives Payment Source creation for that gateway (e.g. `StripeGateway`, `AdyenGateway`).
+_Avoid_: using "gateway" to mean the Payment Method
+
+## Relationships
+
+- An **Order** has at most one **Payment Method** and one **Payment Source**
+- A **Payment Source** is created from the selected **Payment Method**
+- A **Customer Payment Source** belongs to a **Customer**; selecting one sets the **Order**'s Payment Source
+
+## Example dialogue
+
+> **Dev:** "When the shopper picks Stripe, do we create the **Payment Source** in the `StripePayment` component?"
+> **Domain expert:** "No — Stripe has no dedicated creation component. The `StripeGateway`/`PaymentGateway` effect creates the **Payment Source** once the **Payment Method** is selected. Adyen and Braintree, by contrast, create it inside their own components."
+
+## Flagged ambiguities
+
+- "set payment source" was used to mean both the async operation that creates/attaches a Payment Source *and* the reducer action that stores it in state — resolved: the operation is `setPaymentSource(...)`, the reducer action is `dispatch({ type: "setPaymentSource" })`.

docs/adr/0001-coalesce-payment-source-requests.md

@@ -0,0 +1,19 @@
+# Coalesce concurrent payment-source requests
+
+## Context
+
+`setPaymentSource` (in `PaymentMethodReducer.ts`) is a plain async function driven by React effects — notably the `PaymentGateway` effect, which fires it fire-and-forget from a 23-dependency effect. Before the first `create`/`update`/`updateOrder` request resolves, both `paymentSource` (context state) and `order.payment_source` are still null, so any dependency change re-runs the effect and fires a **second** request. On the Stripe / single-payment-method / new-source flow this produced two `stripe_payments.create` calls and two payment source records.
+
+## Decision
+
+De-duplicate genuinely-concurrent calls with a module-level `Map<string, Promise>` keyed by `` `${order.id}:${paymentResource}:${customerPaymentSourceId ?? paymentSourceId ?? 'create'}` ``. The first call stores its in-flight promise; concurrent calls with the same key return that same promise; the entry is deleted in a `finally` once it settles. This coalesces duplicates within a burst without permanently memoizing, so a later legitimate re-create still runs. It backs up the narrower in-flight `useRef` guard in the `PaymentGateway` effect and protects every gateway, not just Stripe.
+
+## Considered options
+
+- **Effect-only `useRef` guard** — kept as the first line of defense, but too narrow: only protects the `PaymentGateway` caller, not other gateways or future callers.
+- **Idempotency check against `order.payment_source`** — unreliable: the order is stale until `getOrder` refreshes after the first request.
+- **Hashing `attributes` into the key** — rejected as fragile; attributes are effectively constant for a given order + resource + path within a burst.
+
+## Consequences
+
+The reducer module now holds mutable global state, which reads as surprising for an otherwise-stateless function — this ADR is the "why." The key deliberately separates the create, update/retrieve, and saved-source (`updateOrder`) paths so coalescing never merges semantically different operations.