@economist/web-apple-pay 1.3.0 → 1.5.0

package/README.md

@@ -78,6 +78,26 @@ If `merchantId` is not configured, Apple Pay availability checks return `false`
 - Skips rendering for excluded variants (`bundle`, `insider_print`).
 - Forwards `data-logged-in` from button to modal (`modal.dataset.loggedIn`).
 
+#### Awaiting render completion — `whenReady()`
+
+Use `whenReady()` to await the component's render lifecycle after appending it
+to the DOM. This is the supported, stable way to know whether Apple Pay is
+available without touching lifecycle internals.
+
+```ts
+container.appendChild(btn);   // spec-compliant — browser fires connectedCallback naturally
+await btn.whenReady();        // resolves when rendering is complete
+if (btn.style.display !== 'none') {
+  // Apple Pay rendered successfully
+} else {
+  btn.remove(); // unavailable or suppressed
+}
+```
+
+> **Important:** calling `whenReady()` _before_ `appendChild` resolves
+> immediately to `undefined` — it does not wait for a future connection.
+> Always call it after appending the element.
+
 ### `ApplePayModal`
 
 - Opened by `ApplePayButton` click.
@@ -100,6 +120,7 @@ Consumers should listen for this event and continue payment orchestration.
 - `defineApplePayElements()`: registers both custom elements.
 - `configureApplePay(config)`: sets required runtime config (merchant ID and wallet API base URL, with optional debug bypass).
 - `ApplePayButton`: button component class.
+  - `whenReady(): Promise<void>` — resolves when the current render lifecycle completes (available or hidden). Resolves immediately if called before the element is connected.
 - `ApplePayModal`: modal component class.
 - `ensureApplePayLogoSymbol()`: logo symbol injection helper.
 - `Offer`: offer contract type used by component props.

package/dist/index.js

@@ -881,6 +881,7 @@ var ApplePayButton = class _ApplePayButton extends HTMLElement {
   #offer = null;
   #country = "";
   #rendering = false;
+  #readyPromise = null;
   get offer() {
     return this.#offer;
   }
@@ -894,11 +895,34 @@ var ApplePayButton = class _ApplePayButton extends HTMLElement {
   set country(value) {
     this.#country = value;
   }
+  /**
+   * Awaitable contract for the component's current render lifecycle.
+   *
+   * - If called **after** the element has been appended to the DOM, resolves
+   *   once `connectedCallback` finishes — whether Apple Pay rendered
+   *   successfully or was hidden (unavailable / suppressed by session).
+   * - If called **before** the element is appended (or if it has never been
+   *   connected), resolves immediately to `undefined`. It does **not** wait
+   *   for a future connection, so always `await whenReady()` after `appendChild`:
+   *
+   * ```ts
+   * container.appendChild(btn);  // browser fires connectedCallback
+   * await btn.whenReady();       // waits for render to finish
+   * if (btn.style.display !== 'none') { /* available *\/ }
+   * ```
+   */
+  whenReady() {
+    return this.#readyPromise ?? Promise.resolve();
+  }
   async connectedCallback() {
     if (this.#rendering || this.querySelector(".apple-pay-container")) {
       return;
     }
     this.#rendering = true;
+    this.#readyPromise = this.#run();
+    await this.#readyPromise;
+  }
+  async #run() {
     try {
       const available = await isApplePayAvailable();
       if (!available) {
@@ -967,6 +991,7 @@ function defineApplePayElements() {
   ApplePayModal.define();
 }
 export {
+  APPLE_PAY_EXCLUDED_VARIANTS,
   ApplePayButton,
   ApplePayModal,
   configureApplePay,

package/dist/src/apple-pay-button.d.ts

@@ -1,4 +1,5 @@
-import type { Offer } from './types/offer.types';
+import type { Offer, ProductVariant } from './types/offer.types';
+export declare const APPLE_PAY_EXCLUDED_VARIANTS: readonly ProductVariant[];
 export declare class ApplePayButton extends HTMLElement {
     #private;
     static readonly tag = "teg-apple-pay-button";
@@ -11,5 +12,22 @@ export declare class ApplePayButton extends HTMLElement {
     set offer(value: Offer | null);
     get country(): string;
     set country(value: string);
+    /**
+     * Awaitable contract for the component's current render lifecycle.
+     *
+     * - If called **after** the element has been appended to the DOM, resolves
+     *   once `connectedCallback` finishes — whether Apple Pay rendered
+     *   successfully or was hidden (unavailable / suppressed by session).
+     * - If called **before** the element is appended (or if it has never been
+     *   connected), resolves immediately to `undefined`. It does **not** wait
+     *   for a future connection, so always `await whenReady()` after `appendChild`:
+     *
+     * ```ts
+     * container.appendChild(btn);  // browser fires connectedCallback
+     * await btn.whenReady();       // waits for render to finish
+     * if (btn.style.display !== 'none') { /* available *\/ }
+     * ```
+     */
+    whenReady(): Promise<void>;
     connectedCallback(): Promise<void>;
 }

package/dist/src/apple-pay-button.js

@@ -876,6 +876,7 @@ var ApplePayButton = class _ApplePayButton extends HTMLElement {
   #offer = null;
   #country = "";
   #rendering = false;
+  #readyPromise = null;
   get offer() {
     return this.#offer;
   }
@@ -889,11 +890,34 @@ var ApplePayButton = class _ApplePayButton extends HTMLElement {
   set country(value) {
     this.#country = value;
   }
+  /**
+   * Awaitable contract for the component's current render lifecycle.
+   *
+   * - If called **after** the element has been appended to the DOM, resolves
+   *   once `connectedCallback` finishes — whether Apple Pay rendered
+   *   successfully or was hidden (unavailable / suppressed by session).
+   * - If called **before** the element is appended (or if it has never been
+   *   connected), resolves immediately to `undefined`. It does **not** wait
+   *   for a future connection, so always `await whenReady()` after `appendChild`:
+   *
+   * ```ts
+   * container.appendChild(btn);  // browser fires connectedCallback
+   * await btn.whenReady();       // waits for render to finish
+   * if (btn.style.display !== 'none') { /* available *\/ }
+   * ```
+   */
+  whenReady() {
+    return this.#readyPromise ?? Promise.resolve();
+  }
   async connectedCallback() {
     if (this.#rendering || this.querySelector(".apple-pay-container")) {
       return;
     }
     this.#rendering = true;
+    this.#readyPromise = this.#run();
+    await this.#readyPromise;
+  }
+  async #run() {
     try {
       const available = await isApplePayAvailable();
       if (!available) {
@@ -956,5 +980,6 @@ var ApplePayButton = class _ApplePayButton extends HTMLElement {
   }
 };
 export {
+  APPLE_PAY_EXCLUDED_VARIANTS,
   ApplePayButton
 };

package/dist/src/apple-pay-button.stories.js

@@ -884,6 +884,7 @@ var ApplePayButton = class _ApplePayButton extends HTMLElement {
   #offer = null;
   #country = "";
   #rendering = false;
+  #readyPromise = null;
   get offer() {
     return this.#offer;
   }
@@ -897,11 +898,34 @@ var ApplePayButton = class _ApplePayButton extends HTMLElement {
   set country(value) {
     this.#country = value;
   }
+  /**
+   * Awaitable contract for the component's current render lifecycle.
+   *
+   * - If called **after** the element has been appended to the DOM, resolves
+   *   once `connectedCallback` finishes — whether Apple Pay rendered
+   *   successfully or was hidden (unavailable / suppressed by session).
+   * - If called **before** the element is appended (or if it has never been
+   *   connected), resolves immediately to `undefined`. It does **not** wait
+   *   for a future connection, so always `await whenReady()` after `appendChild`:
+   *
+   * ```ts
+   * container.appendChild(btn);  // browser fires connectedCallback
+   * await btn.whenReady();       // waits for render to finish
+   * if (btn.style.display !== 'none') { /* available *\/ }
+   * ```
+   */
+  whenReady() {
+    return this.#readyPromise ?? Promise.resolve();
+  }
   async connectedCallback() {
     if (this.#rendering || this.querySelector(".apple-pay-container")) {
       return;
     }
     this.#rendering = true;
+    this.#readyPromise = this.#run();
+    await this.#readyPromise;
+  }
+  async #run() {
     try {
       const available = await isApplePayAvailable();
       if (!available) {

package/dist/src/apple-pay-modal.stories.js

@@ -876,6 +876,7 @@ var ApplePayButton = class _ApplePayButton extends HTMLElement {
   #offer = null;
   #country = "";
   #rendering = false;
+  #readyPromise = null;
   get offer() {
     return this.#offer;
   }
@@ -889,11 +890,34 @@ var ApplePayButton = class _ApplePayButton extends HTMLElement {
   set country(value) {
     this.#country = value;
   }
+  /**
+   * Awaitable contract for the component's current render lifecycle.
+   *
+   * - If called **after** the element has been appended to the DOM, resolves
+   *   once `connectedCallback` finishes — whether Apple Pay rendered
+   *   successfully or was hidden (unavailable / suppressed by session).
+   * - If called **before** the element is appended (or if it has never been
+   *   connected), resolves immediately to `undefined`. It does **not** wait
+   *   for a future connection, so always `await whenReady()` after `appendChild`:
+   *
+   * ```ts
+   * container.appendChild(btn);  // browser fires connectedCallback
+   * await btn.whenReady();       // waits for render to finish
+   * if (btn.style.display !== 'none') { /* available *\/ }
+   * ```
+   */
+  whenReady() {
+    return this.#readyPromise ?? Promise.resolve();
+  }
   async connectedCallback() {
     if (this.#rendering || this.querySelector(".apple-pay-container")) {
       return;
     }
     this.#rendering = true;
+    this.#readyPromise = this.#run();
+    await this.#readyPromise;
+  }
+  async #run() {
     try {
       const available = await isApplePayAvailable();
       if (!available) {

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
-export { ApplePayButton } from './apple-pay-button';
+export { ApplePayButton, APPLE_PAY_EXCLUDED_VARIANTS } from './apple-pay-button';
 export { ApplePayModal } from './apple-pay-modal';
 export { ensureApplePayLogoSymbol } from './apple-pay-logo';
 export { configureApplePay } from './clients/payment-checkout/config';

package/dist/src/index.js

@@ -881,6 +881,7 @@ var ApplePayButton = class _ApplePayButton extends HTMLElement {
   #offer = null;
   #country = "";
   #rendering = false;
+  #readyPromise = null;
   get offer() {
     return this.#offer;
   }
@@ -894,11 +895,34 @@ var ApplePayButton = class _ApplePayButton extends HTMLElement {
   set country(value) {
     this.#country = value;
   }
+  /**
+   * Awaitable contract for the component's current render lifecycle.
+   *
+   * - If called **after** the element has been appended to the DOM, resolves
+   *   once `connectedCallback` finishes — whether Apple Pay rendered
+   *   successfully or was hidden (unavailable / suppressed by session).
+   * - If called **before** the element is appended (or if it has never been
+   *   connected), resolves immediately to `undefined`. It does **not** wait
+   *   for a future connection, so always `await whenReady()` after `appendChild`:
+   *
+   * ```ts
+   * container.appendChild(btn);  // browser fires connectedCallback
+   * await btn.whenReady();       // waits for render to finish
+   * if (btn.style.display !== 'none') { /* available *\/ }
+   * ```
+   */
+  whenReady() {
+    return this.#readyPromise ?? Promise.resolve();
+  }
   async connectedCallback() {
     if (this.#rendering || this.querySelector(".apple-pay-container")) {
       return;
     }
     this.#rendering = true;
+    this.#readyPromise = this.#run();
+    await this.#readyPromise;
+  }
+  async #run() {
     try {
       const available = await isApplePayAvailable();
       if (!available) {
@@ -967,6 +991,7 @@ function defineApplePayElements() {
   ApplePayModal.define();
 }
 export {
+  APPLE_PAY_EXCLUDED_VARIANTS,
   ApplePayButton,
   ApplePayModal,
   configureApplePay,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@economist/web-apple-pay",
   "description": "Web component package for Apple Pay checkout UI",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",