@economist/web-apple-pay 1.2.0 → 1.4.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.
@@ -142,3 +163,24 @@ Then in a consuming app:
 ```sh
 yalc add @economist/web-apple-pay
 ```
+
+## Storybook
+
+Run Storybook locally:
+
+```sh
+npm run storybook --workspace @economist/web-apple-pay
+```
+
+Build static Storybook output:
+
+```sh
+npm run build-storybook --workspace @economist/web-apple-pay
+```
+
+Story coverage matrix:
+
+- `ApplePayButton` docs page shows the stable default example.
+- `ApplePayButton` behavior and state variants are available as individual canvas stories in Storybook.
+- `ApplePayModal` docs page shows the stable default example.
+- `ApplePayModal` behavior and state variants are available as individual canvas stories in Storybook.

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) {

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

@@ -11,5 +11,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) {