@amos.com/amos-js 0.9.15 → 0.9.17

package/src/form-skeleton.ts

@@ -16,7 +16,7 @@ const SKELETON_THEME_DEFAULTS: Record<string, string> = {
   "--label-font-size": "0.875rem",
 };
 
-const SKELETON_STYLES = `
+export const SKELETON_STYLES = `
 .amos-js-form-skeleton {
   box-sizing: border-box;
   container-type: inline-size;
@@ -71,6 +71,10 @@ const SKELETON_STYLES = `
     gap: var(--control-gap);
   }
 }
+.amos-js-wallet-skeleton {
+  flex: none;
+  width: 100%;
+}
 @keyframes amos-js-skeleton-pulse {
   50% { opacity: 0.5; }
 }
@@ -81,7 +85,7 @@ const SKELETON_STYLES = `
 }
 `;
 
-function ensureSkeletonStyles(): void {
+export function ensureSkeletonStyles(): void {
   if (document.getElementById(STYLE_ID)) {
     return;
   }
@@ -242,3 +246,74 @@ export function createPaymentMethodFormSkeleton(
     update: render,
   };
 }
+
+export type WalletButtonSkeletonOptions = {
+  /** Painted height of the wallet button slot (CSS length). */
+  height: string;
+  /** Corner radius matching the iframe / native button. */
+  borderRadius?: string;
+};
+
+export type WalletButtonSkeleton = {
+  element: HTMLElement;
+  update: (options: WalletButtonSkeletonOptions) => void;
+};
+
+/**
+ * Host-page placeholder for Google Pay / Apple Pay: a pulsing bar at
+ * the button's height. Shown immediately while the iframe loads, then
+ * removed when appearance is ready.
+ */
+export function createWalletButtonSkeleton(
+  options: WalletButtonSkeletonOptions,
+): WalletButtonSkeleton {
+  ensureSkeletonStyles();
+  const element = div("amos-js-form-skeleton-input amos-js-wallet-skeleton");
+  element.setAttribute("aria-hidden", "true");
+
+  function render(next: WalletButtonSkeletonOptions): void {
+    applyTheme(element, undefined);
+    element.style.height = next.height;
+    element.style.borderRadius = next.borderRadius ?? "4px";
+  }
+
+  render(options);
+
+  return {
+    element,
+    update: render,
+  };
+}
+
+function cssLength(value: unknown): string | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return `${value}px`;
+  }
+  if (typeof value === "string" && value.trim() !== "") {
+    return value.trim();
+  }
+  return undefined;
+}
+
+/**
+ * Corner radius for a wallet-button skeleton. Prefers host iframe
+ * chrome, then native Google / Apple button radius, then 4px.
+ */
+export function resolveWalletButtonSkeletonBorderRadius({
+  iframeStyle,
+  buttonProps,
+}: {
+  iframeStyle?: { borderRadius?: string | number };
+  buttonProps?: {
+    buttonRadius?: number;
+    style?: Record<string, string | number | undefined>;
+  };
+}): string {
+  return (
+    cssLength(iframeStyle?.borderRadius) ??
+    cssLength(buttonProps?.buttonRadius) ??
+    cssLength(buttonProps?.style?.["borderRadius"]) ??
+    cssLength(buttonProps?.style?.["--apple-pay-button-border-radius"]) ??
+    "4px"
+  );
+}

package/src/google-pay.ts

@@ -34,7 +34,11 @@ export function getGooglePayButtonInitialHeight(): string {
  * Options accepted by {@link attachGooglePayButtonListeners}.
  */
 export type GooglePayButtonListenerOptions = {
-  /** The amount of the payment, in the same format passed in props. */
+  /**
+   * Major-currency decimal string shown in the Google Pay sheet
+   * (e.g. `"50.00"` for $50.00). Converted to cents in
+   * `paymentIntentCreateAttributes.amount`.
+   */
   amount: string;
   /** A user-visible merchant name. */
   merchantName: string;

package/src/index.ts

@@ -9,7 +9,20 @@ export {
   getApplePayButtonInitialHeight,
   getApplePayButtonSrc,
 } from "./apple-pay";
-
+export type {
+  PaymentMethodFormSkeleton,
+  PaymentMethodFormSkeletonKind,
+  PaymentMethodFormSkeletonOptions,
+  WalletButtonSkeleton,
+  WalletButtonSkeletonOptions,
+} from "./form-skeleton";
+export {
+  createPaymentMethodFormSkeleton,
+  createWalletButtonSkeleton,
+  ensureSkeletonStyles,
+  resolveWalletButtonSkeletonBorderRadius,
+  SKELETON_STYLES,
+} from "./form-skeleton";
 export type {
   FormattedGooglePayPaymentData,
   GooglePayButtonController,
@@ -21,7 +34,6 @@ export {
   getGooglePayButtonInitialHeight,
   getGooglePayButtonSrc,
 } from "./google-pay";
-
 export { decodeJwt, getEmbedOrigin } from "./jwt";
 
 export {

package/src/messaging.ts

@@ -114,7 +114,8 @@ export function updateGooglePayButton({
 }
 
 /**
- * Push the express-checkout amount into the embedded Google Pay iframe.
+ * Push the express-checkout amount into the embedded wallet iframe.
+ * `amount` is a major-currency decimal string (e.g. `"50.00"` for $50.00).
  */
 export function updateAmount({
   iframe,

package/src/mount.ts

@@ -7,7 +7,11 @@ import {
 } from "./apple-pay";
 import {
   createPaymentMethodFormSkeleton,
+  createWalletButtonSkeleton,
   type PaymentMethodFormSkeletonOptions,
+  resolveWalletButtonSkeletonBorderRadius,
+  type WalletButtonSkeleton,
+  type WalletButtonSkeletonOptions,
 } from "./form-skeleton";
 import {
   attachGooglePayButtonListeners,
@@ -59,6 +63,19 @@ const WALLET_IFRAME_STYLE: Partial<CSSStyleDeclaration> = {
   border: "0",
 };
 
+const WALLET_SKELETON_IFRAME_STYLE: Partial<CSSStyleDeclaration> = {
+  position: "absolute",
+  top: "0",
+  left: "0",
+  width: "100%",
+  height: "100%",
+  margin: "0",
+  opacity: "0",
+  // Do not interpolate opacity while the skeleton is showing.
+  transition: "none",
+  pointerEvents: "none",
+};
+
 const SKELETON_IFRAME_STYLE: Partial<CSSStyleDeclaration> = {
   position: "absolute",
   top: "0",
@@ -231,6 +248,141 @@ function mountPaymentMethodFormWithSkeleton({
   };
 }
 
+type WalletListenerOptions = {
+  height?: string;
+  onHeightChange?: (height: string) => void;
+  onAppearanceReady?: () => void;
+  buttonProps?: {
+    buttonRadius?: number;
+    style?: Record<string, string | number | undefined>;
+  };
+};
+
+type WalletListenerController<TOptions> = {
+  update: (patch: Partial<TOptions>) => void;
+  destroy: () => void;
+};
+
+function mountWalletButtonWithSkeleton<TOptions extends WalletListenerOptions>({
+  host,
+  iframe,
+  listenerOptions,
+  iframeStyle,
+  attachListeners,
+}: {
+  host: HTMLElement;
+  iframe: HTMLIFrameElement;
+  listenerOptions: TOptions;
+  iframeStyle?: Partial<CSSStyleDeclaration>;
+  attachListeners: (
+    iframe: HTMLIFrameElement,
+    options: TOptions,
+  ) => WalletListenerController<TOptions>;
+}): {
+  iframe: HTMLIFrameElement;
+  update: (patch: Partial<TOptions>) => void;
+  destroy: () => void;
+} {
+  const initialHeight = listenerOptions.height ?? "48px";
+  let skeletonOptions: WalletButtonSkeletonOptions = {
+    height: initialHeight,
+    borderRadius: resolveWalletButtonSkeletonBorderRadius({
+      iframeStyle,
+      buttonProps: listenerOptions.buttonProps,
+    }),
+  };
+  const skeleton: WalletButtonSkeleton =
+    createWalletButtonSkeleton(skeletonOptions);
+
+  const wrapper = document.createElement("div");
+  wrapper.style.position = "relative";
+  wrapper.style.width = "100%";
+  wrapper.style.height = skeletonOptions.height;
+  wrapper.style.overflow = "hidden";
+  wrapper.setAttribute("aria-busy", "true");
+
+  Object.assign(iframe.style, WALLET_SKELETON_IFRAME_STYLE);
+  iframe.style.height = "100%";
+
+  wrapper.append(skeleton.element, iframe);
+  host.appendChild(wrapper);
+
+  let revealed = false;
+  let appearanceReady = false;
+  let fallbackRevealTimer: ReturnType<typeof setTimeout> | undefined;
+  let currentOptions = listenerOptions;
+
+  function reveal(): void {
+    if (revealed) {
+      return;
+    }
+    revealed = true;
+    if (fallbackRevealTimer !== undefined) {
+      clearTimeout(fallbackRevealTimer);
+      fallbackRevealTimer = undefined;
+    }
+
+    iframe.style.opacity = "1";
+    iframe.style.pointerEvents = "";
+    skeleton.element.remove();
+    wrapper.removeAttribute("aria-busy");
+  }
+
+  function tryReveal(): void {
+    if (revealed || !appearanceReady) {
+      return;
+    }
+    reveal();
+  }
+
+  const controller = attachListeners(iframe, {
+    ...listenerOptions,
+    onHeightChange: (height) => {
+      currentOptions.onHeightChange?.(height);
+    },
+    onAppearanceReady: () => {
+      appearanceReady = true;
+      tryReveal();
+      currentOptions.onAppearanceReady?.();
+    },
+  } as TOptions);
+
+  fallbackRevealTimer = setTimeout(() => {
+    reveal();
+  }, 1500);
+
+  return {
+    iframe,
+    update(patch) {
+      currentOptions = { ...currentOptions, ...patch };
+      // Keep the wrapped reveal listeners. Forwarding these would replace
+      // them and leave the iframe at opacity 0.
+      const rest = { ...patch };
+      delete rest.onAppearanceReady;
+      delete rest.onHeightChange;
+      controller.update(rest);
+      skeletonOptions = {
+        height: currentOptions.height ?? skeletonOptions.height,
+        borderRadius: resolveWalletButtonSkeletonBorderRadius({
+          iframeStyle,
+          buttonProps: currentOptions.buttonProps,
+        }),
+      };
+      wrapper.style.height = skeletonOptions.height;
+      if (!revealed) {
+        skeleton.update(skeletonOptions);
+      }
+    },
+    destroy() {
+      if (fallbackRevealTimer !== undefined) {
+        clearTimeout(fallbackRevealTimer);
+      }
+      controller.destroy();
+      wrapper.remove();
+    },
+  };
+}
+
 /**
  * Options accepted by {@link mountAmosCreditCardPaymentMethodForm}.
  */
@@ -420,6 +572,9 @@ export type AmosGooglePayButtonMountController = GooglePayButtonController & {
  * Mount the secure Google Pay button (express checkout) into a
  * container element. Returns a controller exposing the underlying
  * iframe, an `update()` method, and a `destroy()` method.
+ *
+ * A button-shaped skeleton is shown immediately and replaced by the
+ * iframe once appearance is applied.
  */
 export function mountAmosGooglePayButton(
   container: Container,
@@ -439,28 +594,14 @@ export function mountAmosGooglePayButton(
     style: WALLET_IFRAME_STYLE,
   });
   Object.assign(iframe.style, iframeStyle);
-  host.appendChild(iframe);
 
-  const controller = attachGooglePayButtonListeners(iframe, {
-    ...listenerOptions,
-    onHeightChange: (height) => {
-      iframe.style.height = height;
-      listenerOptions.onHeightChange?.(height);
-    },
-    onAppearanceReady: () => {
-      iframe.style.opacity = "1";
-      listenerOptions.onAppearanceReady?.();
-    },
-  });
-
-  return {
+  return mountWalletButtonWithSkeleton({
+    host,
     iframe,
-    update: controller.update,
-    destroy() {
-      controller.destroy();
-      iframe.remove();
-    },
-  };
+    listenerOptions,
+    iframeStyle,
+    attachListeners: attachGooglePayButtonListeners,
+  });
 }
 
 /**
@@ -497,6 +638,9 @@ export type AmosApplePayButtonMountController = ApplePayButtonController & {
  * Mount the secure Apple Pay button (express checkout) into a
  * container element. Returns a controller exposing the underlying
  * iframe, an `update()` method, and a `destroy()` method.
+ *
+ * A button-shaped skeleton is shown immediately and replaced by the
+ * iframe once appearance is applied.
  */
 export function mountAmosApplePayButton(
   container: Container,
@@ -516,26 +660,12 @@ export function mountAmosApplePayButton(
     style: WALLET_IFRAME_STYLE,
   });
   Object.assign(iframe.style, iframeStyle);
-  host.appendChild(iframe);
-
-  const controller = attachApplePayButtonListeners(iframe, {
-    ...listenerOptions,
-    onHeightChange: (height) => {
-      iframe.style.height = height;
-      listenerOptions.onHeightChange?.(height);
-    },
-    onAppearanceReady: () => {
-      iframe.style.opacity = "1";
-      listenerOptions.onAppearanceReady?.();
-    },
-  });
 
-  return {
+  return mountWalletButtonWithSkeleton({
+    host,
     iframe,
-    update: controller.update,
-    destroy() {
-      controller.destroy();
-      iframe.remove();
-    },
-  };
+    listenerOptions,
+    iframeStyle,
+    attachListeners: attachApplePayButtonListeners,
+  });
 }

package/src/types.ts

@@ -406,7 +406,10 @@ export type Message =
       height: string;
     }
   | {
-      /** Parent → embed: express-checkout amount changed. */
+      /**
+       * Parent → embed: express-checkout amount changed. Major-currency
+       * decimal string (e.g. `"50.00"` for $50.00).
+       */
       type: "UPDATE_AMOUNT";
       amount: string;
     }