@xpayeg/react 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @xpayeg/react
 
+## 2.2.0
+### Minor Changes
+
+
+
+- [#462](https://github.com/xpayeg/xpay/pull/462) [`f083704`](https://github.com/xpayeg/xpay/commit/f08370434ff93c52450cfaee17f249c11b5cd46c) Thanks [@Elmosh](https://github.com/Elmosh)! - Deferred-mount Payment Element: `xpay.elements({ mode: "payment", amount, currency })` renders the payment form with no checkout session — your server creates the session with the final total when the customer clicks Pay, and its clientSecret is passed to `confirmPayment({ elements, clientSecret })` (a plain string). The session's total must equal the amount the element displays, or the confirmation fails with `amount_reconfirmation_required` and nothing is charged. Adds `elements.update({ amount, currency })` for deferred display updates. `XPayProvider` accepts the new options form; deferred amount/currency prop changes flow through `elements.update()` without recreating the instance. The existing `{ clientSecret }` path is unchanged.
+  
+  Also in this release: the overlay scroll lock (3DS/action overlay and drop-in modal, now one shared implementation) pins the page at its measured geometry and preserves the scrollbar gutter, so centered boxed themes no longer shift when an overlay opens; `elements.fetchUpdates()` now genuinely re-fetches the session from the server (it previously answered from the iframe's local state; failures now resolve the error arm instead of returning stale data), and `CheckoutSession` gains optional `presentmentDetails` — the customer-facing amounts, present only when the merchant prices in a currency other than the processing currency. Read amounts presentment-first.
+
 ## 2.1.0
 ### Minor Changes
 

package/dist/index.cjs

@@ -64,10 +64,34 @@ function XPayProvider({ xpay: xpayProp, options, children }) {
 			cancelled = true;
 		};
 	}, [xpayProp]);
+	const clientSecretOpt = options && "clientSecret" in options ? options.clientSecret : void 0;
+	const modeOpt = options && "mode" in options ? options.mode : void 0;
 	const elements = (0, react.useMemo)(() => {
-		if (!resolvedXPay || !options?.clientSecret) return null;
+		if (!resolvedXPay || !options) return null;
+		if (!clientSecretOpt && !modeOpt) return null;
 		return resolvedXPay.elements(options);
-	}, [resolvedXPay, options?.clientSecret]);
+	}, [
+		resolvedXPay,
+		clientSecretOpt,
+		modeOpt
+	]);
+	const lastDeferredRef = (0, react.useRef)(null);
+	(0, react.useEffect)(() => {
+		if (!elements || !options || !("mode" in options) || !options.mode) {
+			lastDeferredRef.current = null;
+			return;
+		}
+		const prev = lastDeferredRef.current;
+		lastDeferredRef.current = {
+			amount: options.amount,
+			currency: options.currency
+		};
+		if (!prev) return;
+		const updates = {};
+		if (options.amount !== prev.amount) updates.amount = options.amount;
+		if (options.currency !== prev.currency) updates.currency = options.currency;
+		if (updates.amount !== void 0 || updates.currency !== void 0) elements.update(updates);
+	}, [elements, options]);
 	const [session, setSession] = (0, react.useState)(null);
 	const [sessionError, setSessionError] = (0, react.useState)(null);
 	(0, react.useEffect)(() => {

package/dist/index.d.cts

@@ -36,7 +36,13 @@ interface XPayProviderProps {
      * Use `loadXPay()` from `@xpayeg/sdk` — call it at module level, not inside a component.
      */
     xpay: XPayInstance | Promise<XPayInstance | null> | null;
-    /** Elements options. Must include `clientSecret`. */
+    /**
+     * Elements options — either `{ clientSecret }` (session-first) or
+     * `{ mode: "payment", amount, currency }` (deferred — the session is created
+     * by your server at confirm time). In deferred mode use `useElements()` +
+     * `<PaymentElement>`; `useCheckout()` session data reflects the display
+     * amount until a session is bound at confirm.
+     */
     options?: ElementsOptions;
     children: ReactNode;
 }

package/dist/index.d.mts

@@ -36,7 +36,13 @@ interface XPayProviderProps {
      * Use `loadXPay()` from `@xpayeg/sdk` — call it at module level, not inside a component.
      */
     xpay: XPayInstance | Promise<XPayInstance | null> | null;
-    /** Elements options. Must include `clientSecret`. */
+    /**
+     * Elements options — either `{ clientSecret }` (session-first) or
+     * `{ mode: "payment", amount, currency }` (deferred — the session is created
+     * by your server at confirm time). In deferred mode use `useElements()` +
+     * `<PaymentElement>`; `useCheckout()` session data reflects the display
+     * amount until a session is bound at confirm.
+     */
     options?: ElementsOptions;
     children: ReactNode;
 }

package/dist/index.mjs

@@ -63,10 +63,34 @@ function XPayProvider({ xpay: xpayProp, options, children }) {
 			cancelled = true;
 		};
 	}, [xpayProp]);
+	const clientSecretOpt = options && "clientSecret" in options ? options.clientSecret : void 0;
+	const modeOpt = options && "mode" in options ? options.mode : void 0;
 	const elements = useMemo(() => {
-		if (!resolvedXPay || !options?.clientSecret) return null;
+		if (!resolvedXPay || !options) return null;
+		if (!clientSecretOpt && !modeOpt) return null;
 		return resolvedXPay.elements(options);
-	}, [resolvedXPay, options?.clientSecret]);
+	}, [
+		resolvedXPay,
+		clientSecretOpt,
+		modeOpt
+	]);
+	const lastDeferredRef = useRef(null);
+	useEffect(() => {
+		if (!elements || !options || !("mode" in options) || !options.mode) {
+			lastDeferredRef.current = null;
+			return;
+		}
+		const prev = lastDeferredRef.current;
+		lastDeferredRef.current = {
+			amount: options.amount,
+			currency: options.currency
+		};
+		if (!prev) return;
+		const updates = {};
+		if (options.amount !== prev.amount) updates.amount = options.amount;
+		if (options.currency !== prev.currency) updates.currency = options.currency;
+		if (updates.amount !== void 0 || updates.currency !== void 0) elements.update(updates);
+	}, [elements, options]);
 	const [session, setSession] = useState(null);
 	const [sessionError, setSessionError] = useState(null);
 	useEffect(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpayeg/react",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "XPay React components — PaymentElement, CheckoutButton, and hooks",
   "license": "MIT",
   "type": "module",
@@ -50,7 +50,7 @@
     "tsdown": "^0.22.0",
     "typescript": "5.9.3",
     "@xpay/tsconfig": "0.0.0",
-    "@xpayeg/sdk": "2.1.0"
+    "@xpayeg/sdk": "2.2.0"
   },
   "repository": {
     "type": "git",