@xpayeg/sdk 2.2.0 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @xpayeg/sdk
 
+## 2.4.0
+### Minor Changes
+
+
+
+- [#474](https://github.com/xpayeg/xpay/pull/474) [`c45243c`](https://github.com/xpayeg/xpay/commit/c45243c970b71944482352baea8e8047ba746d8b) Thanks [@Elmosh](https://github.com/Elmosh)! - The Payment Element's `layout` option now works: `elements.create("payment", { layout })`, or the `options` prop on `<PaymentElement />`. `"accordion"` (default) is the vertical list; `"tabs"` is a wrapping tile grid with the selected method's form below it. With exactly one payment method the chooser chrome collapses: the accordion shows a static logo-and-name header above the content (card keeps its bare form), and tabs render the content alone with no logo or title, for pages whose own UI already shows the method's identity, such as a per-gateway row paired with `paymentMethodTypes: ["<type>"]`. Layout is updatable after creation via `element.update({ layout })`, and every method's form stays mounted across switches so typed card details survive.
+
+## 2.3.0
+### Minor Changes
+
+
+
+- [#471](https://github.com/xpayeg/xpay/pull/471) [`e76a6c3`](https://github.com/xpayeg/xpay/commit/e76a6c3e5f73f4dcf1f108b6be0e1a63dce5d1b9) Thanks [@Elmosh](https://github.com/Elmosh)! - Deferred Elements accept `paymentMethodTypes` (e.g. `["card"]`) to restrict which payment methods the element renders. Narrow-only: the list is intersected with the methods enabled for your account, so a type you have not enabled is never rendered, and an empty intersection fails with `loaderror` instead of rendering an empty frame. Fixed for the element's lifetime; pass the same values when your server creates the session so display and acceptance match. One method per element is the pattern for per-method rows in your own selector.
+
 ## 2.2.0
 ### Minor Changes
 

package/dist/index.d.cts

@@ -3611,6 +3611,8 @@ interface ElementsOptionsClientSecret {
     amount?: never;
     /** Currency is only applicable in deferred mode (`mode: "payment"`). */
     currency?: never;
+    /** Only applicable in deferred mode. Session-first elements render the session's own payment method types, set when the session is created. */
+    paymentMethodTypes?: never;
     /** Appearance overrides for the checkout UI */
     appearance?: Appearance;
     /** Locale for the payment form — `"en"` (default) or `"ar"` */
@@ -3643,6 +3645,16 @@ interface ElementsOptionsMode {
     amount: number;
     /** Three-letter currency code (e.g. `"EGP"`). */
     currency: string;
+    /**
+     * Restrict which payment method types the element renders (e.g. `["card"]`).
+     * Narrow-only: the list is intersected with the payment methods enabled for
+     * your account, so a type that is not enabled is never rendered. If nothing
+     * survives the intersection the element fails to load with a `loaderror`.
+     * Fixed for the element's lifetime. Omit to render every enabled method.
+     * The same values are passed as `paymentMethodTypes` when your server
+     * creates the session at pay time, so display and acceptance match.
+     */
+    paymentMethodTypes?: string[];
     /** Either use mode or clientSecret when creating an Elements group. */
     clientSecret?: never;
     /** Appearance overrides for the checkout UI */
@@ -3739,7 +3751,23 @@ interface ElementsLoadErrorEvent {
 }
 /** Options for creating a PaymentElement */
 interface PaymentElementOptions {
-    /** Layout style for the payment method selector — `"accordion"` (default) or `"tabs"` */
+    /**
+     * How the element presents the payment method chooser.
+     *
+     * - `"accordion"` (default): a vertical list, one row per method, the
+     *   selected method's content expanding beneath its row. With exactly one
+     *   method the chooser disappears: a single non-card method shows a static
+     *   identity header (logo and name, no radio) above its content, while a
+     *   single card method renders the bare card form, since its fields
+     *   already identify it.
+     * - `"tabs"`: a grid of tiles that fills the row and wraps when the
+     *   methods no longer fit, with the selected method's content below it.
+     *   With exactly one method the tile grid disappears and
+     *   only the content renders, for pages whose own UI already shows the
+     *   method's logo and name (e.g. a per-gateway plugin row).
+     *
+     * Updatable after creation via `element.update({ layout })`.
+     */
     layout?: "accordion" | "tabs";
     /** Pre-select a specific payment method by type */
     defaultPaymentMethod?: string;
@@ -3796,12 +3824,19 @@ interface BaseElement {
     on(event: string, handler: (...args: unknown[]) => void): void;
     off(event: string, handler: (...args: unknown[]) => void): void;
 }
+/**
+ * The subset of `PaymentElementOptions` that can be updated after creation
+ * (Stripe's `StripePaymentElementUpdateOptions` pattern). Only `layout` is
+ * updatable; `defaultPaymentMethod` and `paymentMethodOrder` are set at
+ * creation.
+ */
+type PaymentElementUpdateOptions = Pick<PaymentElementOptions, "layout">;
 /** PaymentElement — full payment method selector with card form */
 interface PaymentElement extends BaseElement {
     /** Collapse the payment method selector (deselect all methods) */
     collapse(): void;
-    /** Update element options at runtime */
-    update(options: Partial<PaymentElementOptions>): void;
+    /** Update element options at runtime — see {@link PaymentElementUpdateOptions} */
+    update(options: PaymentElementUpdateOptions): void;
 }
 /**
  * Options for `confirmPayment()` or `checkout.confirm()`.

package/dist/index.d.mts

@@ -3611,6 +3611,8 @@ interface ElementsOptionsClientSecret {
     amount?: never;
     /** Currency is only applicable in deferred mode (`mode: "payment"`). */
     currency?: never;
+    /** Only applicable in deferred mode. Session-first elements render the session's own payment method types, set when the session is created. */
+    paymentMethodTypes?: never;
     /** Appearance overrides for the checkout UI */
     appearance?: Appearance;
     /** Locale for the payment form — `"en"` (default) or `"ar"` */
@@ -3643,6 +3645,16 @@ interface ElementsOptionsMode {
     amount: number;
     /** Three-letter currency code (e.g. `"EGP"`). */
     currency: string;
+    /**
+     * Restrict which payment method types the element renders (e.g. `["card"]`).
+     * Narrow-only: the list is intersected with the payment methods enabled for
+     * your account, so a type that is not enabled is never rendered. If nothing
+     * survives the intersection the element fails to load with a `loaderror`.
+     * Fixed for the element's lifetime. Omit to render every enabled method.
+     * The same values are passed as `paymentMethodTypes` when your server
+     * creates the session at pay time, so display and acceptance match.
+     */
+    paymentMethodTypes?: string[];
     /** Either use mode or clientSecret when creating an Elements group. */
     clientSecret?: never;
     /** Appearance overrides for the checkout UI */
@@ -3739,7 +3751,23 @@ interface ElementsLoadErrorEvent {
 }
 /** Options for creating a PaymentElement */
 interface PaymentElementOptions {
-    /** Layout style for the payment method selector — `"accordion"` (default) or `"tabs"` */
+    /**
+     * How the element presents the payment method chooser.
+     *
+     * - `"accordion"` (default): a vertical list, one row per method, the
+     *   selected method's content expanding beneath its row. With exactly one
+     *   method the chooser disappears: a single non-card method shows a static
+     *   identity header (logo and name, no radio) above its content, while a
+     *   single card method renders the bare card form, since its fields
+     *   already identify it.
+     * - `"tabs"`: a grid of tiles that fills the row and wraps when the
+     *   methods no longer fit, with the selected method's content below it.
+     *   With exactly one method the tile grid disappears and
+     *   only the content renders, for pages whose own UI already shows the
+     *   method's logo and name (e.g. a per-gateway plugin row).
+     *
+     * Updatable after creation via `element.update({ layout })`.
+     */
     layout?: "accordion" | "tabs";
     /** Pre-select a specific payment method by type */
     defaultPaymentMethod?: string;
@@ -3796,12 +3824,19 @@ interface BaseElement {
     on(event: string, handler: (...args: unknown[]) => void): void;
     off(event: string, handler: (...args: unknown[]) => void): void;
 }
+/**
+ * The subset of `PaymentElementOptions` that can be updated after creation
+ * (Stripe's `StripePaymentElementUpdateOptions` pattern). Only `layout` is
+ * updatable; `defaultPaymentMethod` and `paymentMethodOrder` are set at
+ * creation.
+ */
+type PaymentElementUpdateOptions = Pick<PaymentElementOptions, "layout">;
 /** PaymentElement — full payment method selector with card form */
 interface PaymentElement extends BaseElement {
     /** Collapse the payment method selector (deselect all methods) */
     collapse(): void;
-    /** Update element options at runtime */
-    update(options: Partial<PaymentElementOptions>): void;
+    /** Update element options at runtime — see {@link PaymentElementUpdateOptions} */
+    update(options: PaymentElementUpdateOptions): void;
 }
 /**
  * Options for `confirmPayment()` or `checkout.confirm()`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpayeg/sdk",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "XPay JavaScript SDK — loader and TypeScript types for embedding XPay payments",
   "license": "MIT",
   "type": "module",