@amos.com/amos-js 0.9.10 → 0.9.12

package/README.md

@@ -14,7 +14,7 @@ npm install @amos.com/amos-js
 
 - **Types** for the `postMessage` protocol used between your page and the Amos iframe (`Message`, `Appearance`, `ThemeVariable`). OpenAPI schema types (for example `components["schemas"]["PaymentIntent"]`) come from `@amos.com/node`.
 - **Iframe-targeted helpers** to validate the form, confirm a payment intent, confirm a setup intent, update appearance, etc.
-- **Mount functions** (`mountAmosCreditCardPaymentMethodForm`, `mountAmosBankAccountPaymentMethodForm`, `mountAmosGooglePayButton`, `mountAmosApplePayButton`) that create the iframe, wire up its message protocol, manage its height/opacity, and return a small controller for updating options and tearing it down.
+- **Mount functions** (`mountAmosCreditCardPaymentMethodForm`, `mountAmosBankAccountPaymentMethodForm`, `mountAmosGooglePayButton`, `mountAmosApplePayButton`) that create the iframe, wire up its message protocol, manage its height/opacity, show a field-shaped loading skeleton for card/bank forms, and return a small controller for updating options and tearing it down.
 - **Lower-level building blocks** (`getCreditCardFormSrc`, `attachPaymentMethodFormListeners`, `attachGooglePayButtonListeners`, `attachApplePayButtonListeners`, ...) for integrators (such as `@amos.com/react-amos-js`) that want to render the iframe element themselves.
 
 > **Note:** A server-side SDK (for example `@amos.com/node`) must be used alongside `@amos.com/amos-js` for end-to-end payment processing. `@amos.com/amos-js` is the client-side half.
@@ -63,6 +63,9 @@ const form = mountAmosCreditCardPaymentMethodForm(
         console.log("Recoverable:", result.reason);
       }
     },
+    onValidityChange: ({ isValid }) => {
+      document.querySelector("#pay-now")!.disabled = !isValid;
+    },
   },
 );
 
@@ -93,7 +96,7 @@ form.destroy();
 The following flow is for credit card and bank account payment method types only.
 
 1. **Set up prerequisites**: create a `renderToken` (safe for client), and keep `apiKey` and `accountId` server-side only.
-2. **Render your checkout UI** by calling `mountAmosCreditCardPaymentMethodForm(container, options)` (or `mountAmosBankAccountPaymentMethodForm(...)`) along with the required `onResult` callback. The iframe height is auto-managed by the SDK.
+2. **Render your checkout UI** by calling `mountAmosCreditCardPaymentMethodForm(container, options)` (or `mountAmosBankAccountPaymentMethodForm(...)`) along with the required `onResult` callback. The SDK shows a field-shaped skeleton immediately (sized from `appearance`, `additionalFields`, and `billingAddressRequirement`) and auto-manages iframe height.
 3. **User clicks "Pay now" button**: call `validateForm({ iframe: form.iframe })`, which returns `Promise<true>` if the embedded form is valid, and `Promise<false>` otherwise.
 4. **Create payment intent on your server**: use your server-side Amos client to call `POST /payment_intents`. You may also associate this payment intent with a new or existing customer via `POST /customers`. This must be server-side because it uses your private API key.
 5. **Return the payment intent token to the browser**: your backend responds with the embed token (`components["schemas"]["EmbedToken"]`) needed for confirmation.
@@ -264,13 +267,14 @@ Mount the secure credit-card payment method form into a container element (an `H
 - `billingAddressRequirement` (`"country" | "full"`, defaults to `"country"`) — how much billing address the iframe collects. `country` collects country / region and, for CA / PR / GB / US, a postal code (labeled ZIP for the United States). `full` shows a full street address form with Smarty autocomplete.
 
 
-- `onHeightChange`, `onAppearanceReady` (advanced — override the default iframe styling logic)
+- `onValidityChange` (`(event: { isValid: boolean }) => void`) — called when form validity changes. `isValid` is true when all required fields are present and valid. Does not include PCI data. Use this to enable or disable your checkout button.
+- `onHeightChange`, `onAppearanceReady` (advanced — override the default iframe styling logic). The skeleton is removed and the iframe faded in when `onAppearanceReady` fires.
 
 **Returns** `AmosPaymentMethodFormMountController`:
 
 - `iframe` — the underlying `<iframe>` element.
 - `update(patch)` — patch any of the options listed above.
-- `destroy()` — remove the iframe and detach listeners.
+- `destroy()` — remove the iframe (and any loading skeleton) and detach listeners.
 
 ### `mountAmosBankAccountPaymentMethodForm(container, options)`
 
@@ -363,7 +367,7 @@ Advanced helpers exposed for integrators that need to construct or inspect the m
 
 ### Exported types
 
-`Message`, `Appearance`, `ThemeVariable`, `FormattedGooglePayPaymentData`, plus the per-form `*Options` and `*Controller` types. For OpenAPI schema types, import `components` from `@amos.com/node`.
+`Message`, `Appearance`, `ThemeVariable`, `FormattedGooglePayPaymentData`, `PaymentMethodFormValidityChangeEvent`, plus the per-form `*Options` and `*Controller` types. For OpenAPI schema types, import `components` from `@amos.com/node`.
 
 ## Notes and potential gotchas
 

package/dist/form-skeleton.d.ts

@@ -0,0 +1,20 @@
+import { BillingAddressRequirement, CreditCardAdditionalFields } from './payment-method-form';
+import { Appearance } from './types';
+export type PaymentMethodFormSkeletonKind = "card" | "bank";
+export type PaymentMethodFormSkeletonOptions = {
+    kind: PaymentMethodFormSkeletonKind;
+    appearance?: Appearance;
+    additionalFields?: CreditCardAdditionalFields;
+    billingAddressRequirement?: BillingAddressRequirement;
+};
+export type PaymentMethodFormSkeleton = {
+    element: HTMLElement;
+    update: (options: PaymentMethodFormSkeletonOptions) => void;
+};
+/**
+ * Host-page placeholder that mirrors card/bank field layout using the
+ * same appearance variables the iframe will apply. Shown immediately
+ * while the iframe document loads, then removed when appearance is
+ * ready.
+ */
+export declare function createPaymentMethodFormSkeleton(options: PaymentMethodFormSkeletonOptions): PaymentMethodFormSkeleton;

package/dist/index.d.ts

@@ -9,5 +9,5 @@ export type { AmosApplePayButtonMountController, AmosApplePayButtonOptions, Amos
 export { mountAmosApplePayButton, mountAmosBankAccountPaymentMethodForm, mountAmosCreditCardPaymentMethodForm, mountAmosGooglePayButton, } from './mount';
 export type { BillingAddressRequirement, CreditCardAdditionalFields, PaymentMethodFormController, PaymentMethodFormListenerOptions, } from './payment-method-form';
 export { attachPaymentMethodFormListeners, getBankAccountFormInitialHeight, getBankAccountFormSrc, getCreditCardFormInitialHeight, getCreditCardFormSrc, } from './payment-method-form';
-export type { Appearance, AppearanceLabels, ApplePayButtonElementProps, ApplePayButtonStyle, ApplePayButtonType, ConfirmationIncompleteReason, ConfirmationResult, GooglePayButtonElementProps, Message, ThemeVariable, WalletButtonStyle, } from './types';
+export type { Appearance, AppearanceLabels, ApplePayButtonElementProps, ApplePayButtonStyle, ApplePayButtonType, ConfirmationIncompleteReason, ConfirmationResult, GooglePayButtonElementProps, Message, PaymentMethodFormValidityChangeEvent, ThemeVariable, WalletButtonStyle, } from './types';
 export { createMessage, pickApplePayButtonElementProps, pickGooglePayButtonElementProps, serializeWalletButtonStyle, } from './types';

package/dist/index.js

@@ -1 +1,64 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=`data-amos-apple-pay-waiting`;function t({onCancel:t}){let n=document.querySelector(`[${e}]`);if(n)return n;let r=document.createElement(`div`);r.setAttribute(e,`true`),r.setAttribute(`role`,`dialog`),r.setAttribute(`aria-modal`,`true`),r.setAttribute(`aria-labelledby`,`amos-apple-pay-waiting-title`),Object.assign(r.style,{position:`fixed`,inset:`0`,zIndex:`2147483646`,display:`flex`,alignItems:`center`,justifyContent:`center`,padding:`24px`,boxSizing:`border-box`,background:`rgba(0, 0, 0, 0.55)`,fontFamily:`-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif`});let i=document.createElement(`div`);Object.assign(i.style,{width:`100%`,maxWidth:`360px`,borderRadius:`12px`,background:`#fff`,padding:`28px 24px 20px`,boxSizing:`border-box`,textAlign:`center`,boxShadow:`0 12px 40px rgba(0, 0, 0, 0.25)`});let a=document.createElement(`div`);a.setAttribute(`aria-hidden`,`true`),Object.assign(a.style,{display:`inline-flex`,alignItems:`center`,justifyContent:`center`,gap:`6px`,marginBottom:`16px`,fontSize:`28px`,fontWeight:`600`,letterSpacing:`-0.02em`,color:`#000`,lineHeight:`1`}),a.innerHTML=`<svg width="22" height="26" viewBox="0 0 814 1000" fill="currentColor" xmlns="http://www.w3.org/2000/svg"><path d="M788.1 340.9c-5.8 4.5-108.2 62.2-108.2 190.5 0 148.4 130.3 200.9 134.2 202.2-.6 3.2-20.7 71.9-68.7 141.9-42.8 61.6-87.5 123.1-155.5 123.1s-85.5-39.5-164-39.5c-76.5 0-103.7 40.8-165.9 40.8s-105.6-57-155.5-127C46.7 790.7 0 663 0 541.8c0-194.4 126.4-297.5 250.8-297.5 66.1 0 121.2 43.4 162.7 43.4 39.5 0 101.1-46 176.3-46 28.5 0 130.9 2.6 198.3 99.2zm-234-181.5c31.1-36.9 53.1-88.1 53.1-139.3 0-7.1-.6-14.3-1.9-20.1-50.6 1.9-110.8 33.7-147.1 75.8-28.5 32.4-55.1 83.6-55.1 135.5 0 7.8 1.3 15.6 1.9 18.1 3.2.6 8.4 1.3 13.6 1.3 45.4 0 102.5-30.4 135.5-71.3z"/></svg><span>Pay</span>`;let o=document.createElement(`p`);o.id=`amos-apple-pay-waiting-title`,Object.assign(o.style,{margin:`0 0 20px`,fontSize:`15px`,lineHeight:`1.45`,color:`#1a1a1a`}),o.textContent=`Complete your payment in the open Apple Pay window, or close Apple Pay to continue paying another way.`;let s=document.createElement(`button`);return s.type=`button`,s.textContent=`Cancel payment`,Object.assign(s.style,{display:`block`,width:`100%`,border:`none`,borderRadius:`8px`,padding:`12px 16px`,background:`#2c2c2e`,color:`#fff`,fontSize:`15px`,fontWeight:`500`,cursor:`pointer`}),s.addEventListener(`click`,t),i.append(a,o,s),r.append(i),document.body.append(r),r}function n(){document.querySelector(`[${e}]`)?.remove()}function r(e){let[t=``,n=``,r=``]=e?.split(`.`)??[],i=typeof atob==`function`?atob:e=>Buffer.from(e,`base64`).toString(`utf8`);return{header:JSON.parse(i(t)),payload:JSON.parse(i(n)),signature:r}}function i(e){let{env:t=`sandbox`}=r(e).payload;switch(t){case`production`:return`https://embed.amos.com`;case`sandbox`:return`https://embed-sandbox.amos.com`;default:return`https://embed-sandbox.amos.com`}}function a(e){if(!e||typeof e!=`object`)return;let t={};for(let[n,r]of Object.entries(e)){if(typeof r==`string`){if(r.length===0)continue;t[n]=r;continue}typeof r==`number`&&Number.isFinite(r)&&(t[n]=r)}return Object.keys(t).length>0?t:void 0}function o(e){let t={};if(e.buttonstyle!==void 0&&(t.buttonstyle=e.buttonstyle),e.type!==void 0&&(t.type=e.type),e.locale!==void 0&&(t.locale=e.locale),e.style!==void 0){let n=a(e.style);n&&(t.style=n)}return t}function s(e){let t={};if(e.buttonType!==void 0&&(t.buttonType=e.buttonType),e.buttonColor!==void 0&&(t.buttonColor=e.buttonColor),e.buttonRadius!==void 0&&(t.buttonRadius=e.buttonRadius),e.buttonSizeMode!==void 0&&(t.buttonSizeMode=e.buttonSizeMode),e.buttonLocale!==void 0&&(t.buttonLocale=e.buttonLocale),e.buttonBorderType!==void 0&&(t.buttonBorderType=e.buttonBorderType),e.style!==void 0){let n=a(e.style);n&&(t.style=n)}return t}function c(e){return e}function l(e){return new URL(e.src).origin}function u(e){e?.contentWindow&&e.contentWindow.postMessage(c({type:`PARENT_ACKNOWLEDGED_IFRAME_READY`}),l(e))}function d({iframe:e,appearance:t={}}){e?.contentWindow&&e.contentWindow.postMessage(c({type:`UPDATE_APPEARANCE`,appearance:t}),l(e))}function f({iframe:e,props:t}){e?.contentWindow&&e.contentWindow.postMessage(c({type:`UPDATE_APPLE_PAY_BUTTON`,props:o(t)}),l(e))}function p({iframe:e,props:t}){e?.contentWindow&&e.contentWindow.postMessage(c({type:`UPDATE_GOOGLE_PAY_BUTTON`,props:s(t)}),l(e))}function m({iframe:e,amount:t}){e?.contentWindow&&e.contentWindow.postMessage(c({type:`UPDATE_AMOUNT`,amount:t}),l(e))}function h({iframe:e,merchantName:t}){e?.contentWindow&&e.contentWindow.postMessage(c({type:`UPDATE_MERCHANT_NAME`,merchantName:t}),l(e))}function g({iframe:e}){let t=crypto.randomUUID();return new Promise(n=>{e?.contentWindow&&e.contentWindow.postMessage(c({type:`VALIDATE_FORM`,requestId:t}),l(e));let r=setTimeout(()=>{window.removeEventListener(`message`,i),n(!1)},5e3);function i(e){e.data.type===`VALIDATE_FORM`&&e.data.requestId===t&&(window.removeEventListener(`message`,i),clearTimeout(r),n(e.data.isValid??!1))}window.addEventListener(`message`,i)})}function _({iframe:e}){e?.contentWindow&&e.contentWindow.postMessage(c({type:`RESET_FORM`}),l(e))}function v({iframe:e,token:t}){if(!e?.contentWindow)return;let{payment_intent_id:n}=r(t).payload;e.contentWindow.postMessage(c({type:`CONFIRM_PAYMENT_INTENT`,token:t,id:n??void 0}),l(e))}function y({iframe:e,token:t}){if(!e?.contentWindow)return;let{setup_intent_id:n}=r(t).payload;e.contentWindow.postMessage(c({type:`CONFIRM_SETUP_INTENT`,token:t,id:n??void 0}),l(e))}function b({iframe:e,result:t}){e?.contentWindow&&e.contentWindow.postMessage(c({type:`CONFIRMATION_RESULT`,result:t}),l(e))}function x(e){return`${i(e)}/iframe/apple-pay?token=${e}`}function S(){return`40px`}function C(e){e.contentWindow?.postMessage(c({type:`APPLE_PAY_CANCEL`}),l(e))}function w(e,r){let i={...r};function a(){m({iframe:e,amount:i.amount})}function o(){h({iframe:e,merchantName:i.merchantName})}function s(){f({iframe:e,props:i})}function c(r){if(r.source===e.contentWindow)switch(r.data.type){case`IFRAME_READY`:u(e),d({iframe:e,appearance:i.appearance}),a(),o(),s();break;case`UPDATE_HEIGHT`:i.onHeightChange?.(r.data.height);break;case`UPDATE_APPEARANCE`:d({iframe:e,appearance:r.data.appearance});break;case`UPDATED_APPEARANCE`:i.onAppearanceReady?.();break;case`APPLE_PAY_WINDOW_OPEN`:t({onCancel:()=>{C(e),n()}});break;case`APPLE_PAY_WINDOW_CLOSE`:n();break;case`CREATE_PAYMENT_INTENT`:i.onInitiatePaymentIntentRequest({paymentIntentCreateAttributes:r.data.paymentIntentCreateAttributes,customerCreateAttributes:r.data.customerCreateAttributes}).then(t=>{v({iframe:e,token:t})}).catch(e=>{n(),i.onResult({status:`failed`,errorMessage:e instanceof Error?e.message:`Unknown error`})});break;case`CONFIRMATION_RESULT`:n(),i.onResult(r.data.result)}}return window.addEventListener(`message`,c),{update(t){let n=`appearance`in t,r=`amount`in t,c=`merchantName`in t,l=`buttonstyle`in t||`type`in t||`locale`in t||`style`in t;i={...i,...t},n&&d({iframe:e,appearance:i.appearance}),r&&a(),c&&o(),l&&s()},destroy(){window.removeEventListener(`message`,c),n()}}}function T(e){return`${i(e)}/iframe/google-pay?token=${e}`}function E(){return`40px`}function D(e,t){let n={...t};function r(){m({iframe:e,amount:n.amount})}function i(){h({iframe:e,merchantName:n.merchantName})}function a(){p({iframe:e,props:n})}function o(t){if(t.source===e.contentWindow)switch(t.data.type){case`IFRAME_READY`:u(e),d({iframe:e,appearance:n.appearance}),r(),i(),a();break;case`UPDATE_HEIGHT`:n.onHeightChange?.(t.data.height);break;case`UPDATE_APPEARANCE`:d({iframe:e,appearance:t.data.appearance});break;case`UPDATED_APPEARANCE`:n.onAppearanceReady?.();break;case`CREATE_PAYMENT_INTENT`:n.onInitiatePaymentIntentRequest({paymentIntentCreateAttributes:t.data.paymentIntentCreateAttributes,customerCreateAttributes:t.data.customerCreateAttributes}).then(t=>{v({iframe:e,token:t})}).catch(e=>{n.onResult({status:`failed`,errorMessage:e instanceof Error?e.message:`Unknown error`})});break;case`CONFIRMATION_RESULT`:n.onResult(t.data.result)}}return window.addEventListener(`message`,o),{update(t){let o=`appearance`in t,s=`amount`in t,c=`merchantName`in t,l=`buttonType`in t||`buttonColor`in t||`buttonRadius`in t||`buttonSizeMode`in t||`buttonLocale`in t||`buttonBorderType`in t||`style`in t;n={...n,...t},o&&d({iframe:e,appearance:n.appearance}),s&&r(),c&&i(),l&&a()},destroy(){window.removeEventListener(`message`,o)}}}function O({paymentData:e}){return{paymentMethod:{type:`googlepay`,billing_address_attributes:{name:e.shippingAddress?.name,address_line1:e.shippingAddress?.address1,address_line2:e.shippingAddress?.address2,city:e.shippingAddress?.locality,state:e.shippingAddress?.administrativeArea,postal_code:e.shippingAddress?.postalCode,country:e.shippingAddress?.countryCode,email:e.email,phone:e.shippingAddress?.phoneNumber},card_profile_attributes:{wallet_payload:e.paymentMethodData.tokenizationData.token}}}}var k={country:212,full:452},A=80,j={country:400,full:640};function M(e,t={cardholderName:!1},n=`country`){let r=Object.entries(t).filter(([,e])=>e).map(([e])=>e).join(`,`),a=new URLSearchParams({token:e,additionalFields:r,billingAddressRequirement:n});return`${i(e)}/iframe/card?${a}`}function N(e,t=`country`){let n=new URLSearchParams({token:e,billingAddressRequirement:t});return`${i(e)}/iframe/bank?${n}`}function P(e={cardholderName:!1},t=`country`){return`${(k[t]??k.country)+(e.cardholderName?A:0)}px`}function F(e=`country`){return`${j[e]??j.country}px`}function I(e,t){let n={...t};function r(t){if(t.source===e.contentWindow)switch(t.data.type){case`IFRAME_READY`:u(e),d({iframe:e,appearance:n.appearance});break;case`UPDATE_HEIGHT`:n.onHeightChange?.(t.data.height);break;case`UPDATE_APPEARANCE`:d({iframe:e,appearance:t.data.appearance});break;case`UPDATED_APPEARANCE`:n.onAppearanceReady?.();break;case`CONFIRMATION_RESULT`:n.onResult(t.data.result)}}return window.addEventListener(`message`,r),{update(t){let r=`appearance`in t;n={...n,...t},r&&d({iframe:e,appearance:n.appearance})},destroy(){window.removeEventListener(`message`,r)}}}function L(e){if(typeof e==`string`){let t=document.querySelector(e);if(!(t instanceof HTMLElement))throw Error(`[amos-js] Container "${e}" did not match any HTMLElement.`);return t}return e}var R={width:`calc(100% + 8px)`,transition:`opacity 150ms ease-in, height 200ms ease-in-out`,margin:`0 -4px`,opacity:`0`,border:`0`};function z({src:e,title:t,name:n,height:r,allow:i}){let a=document.createElement(`iframe`);return a.src=e,a.title=t,a.name=n,a.setAttribute(`role`,`presentation`),a.scrolling=`no`,i&&(a.allow=i),Object.assign(a.style,R,{height:r}),a}function B(e,t){let n=L(e),{renderToken:r,additionalFields:i={cardholderName:!1},billingAddressRequirement:a=`country`,...o}=t,s=z({src:M(r,i,a),title:`Secure credit card payment method form powered by Amos`,name:`amos-credit-card-payment-method-form`,height:P(i,a)});n.appendChild(s);let c=I(s,{...o,onHeightChange:e=>{s.style.height=e,o.onHeightChange?.(e)},onAppearanceReady:()=>{s.style.opacity=`1`,o.onAppearanceReady?.()}});return{iframe:s,update:c.update,destroy(){c.destroy(),s.remove()}}}function V(e,t){let n=L(e),{renderToken:r,billingAddressRequirement:i=`country`,...a}=t,o=z({src:N(r,i),title:`Secure bank account payment method form powered by Amos`,name:`amos-bank-account-payment-method-form`,height:F(i)});n.appendChild(o);let s=I(o,{...a,onHeightChange:e=>{o.style.height=e,a.onHeightChange?.(e)},onAppearanceReady:()=>{o.style.opacity=`1`,a.onAppearanceReady?.()}});return{iframe:o,update:s.update,destroy(){s.destroy(),o.remove()}}}function H(e,t){let n=L(e),{renderToken:r,...i}=t,a=z({src:T(r),title:`Secure Google Pay button powered by Amos`,name:`amos-google-pay-button`,height:E(),allow:`payment`});n.appendChild(a);let o=D(a,{...i,onHeightChange:e=>{a.style.height=e,i.onHeightChange?.(e)},onAppearanceReady:()=>{a.style.opacity=`1`,i.onAppearanceReady?.()}});return{iframe:a,update:o.update,destroy(){o.destroy(),a.remove()}}}function U(e,t){let n=L(e),{renderToken:r,...i}=t,a=z({src:x(r),title:`Secure Apple Pay button powered by Amos`,name:`amos-apple-pay-button`,height:S(),allow:`payment`});n.appendChild(a);let o=w(a,{...i,onHeightChange:e=>{a.style.height=e,i.onHeightChange?.(e)},onAppearanceReady:()=>{a.style.opacity=`1`,i.onAppearanceReady?.()}});return{iframe:a,update:o.update,destroy(){o.destroy(),a.remove()}}}exports.attachApplePayButtonListeners=w,exports.attachGooglePayButtonListeners=D,exports.attachPaymentMethodFormListeners=I,exports.confirmPaymentIntent=v,exports.confirmSetupIntent=y,exports.createMessage=c,exports.decodeJwt=r,exports.formatGooglePayPaymentData=O,exports.getApplePayButtonInitialHeight=S,exports.getApplePayButtonSrc=x,exports.getBankAccountFormInitialHeight=F,exports.getBankAccountFormSrc=N,exports.getCreditCardFormInitialHeight=P,exports.getCreditCardFormSrc=M,exports.getEmbedOrigin=i,exports.getGooglePayButtonInitialHeight=E,exports.getGooglePayButtonSrc=T,exports.mountAmosApplePayButton=U,exports.mountAmosBankAccountPaymentMethodForm=V,exports.mountAmosCreditCardPaymentMethodForm=B,exports.mountAmosGooglePayButton=H,exports.pickApplePayButtonElementProps=o,exports.pickGooglePayButtonElementProps=s,exports.resetForm=_,exports.sendConfirmationResult=b,exports.sendParentReadyMessage=u,exports.serializeWalletButtonStyle=a,exports.updateAmount=m,exports.updateAppearance=d,exports.updateApplePayButton=f,exports.updateGooglePayButton=p,exports.updateMerchantName=h,exports.validateForm=g;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=`data-amos-apple-pay-waiting`;function t({onCancel:t}){let n=document.querySelector(`[${e}]`);if(n)return n;let r=document.createElement(`div`);r.setAttribute(e,`true`),r.setAttribute(`role`,`dialog`),r.setAttribute(`aria-modal`,`true`),r.setAttribute(`aria-labelledby`,`amos-apple-pay-waiting-title`),Object.assign(r.style,{position:`fixed`,inset:`0`,zIndex:`2147483646`,display:`flex`,alignItems:`center`,justifyContent:`center`,padding:`24px`,boxSizing:`border-box`,background:`rgba(0, 0, 0, 0.55)`,fontFamily:`-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif`});let i=document.createElement(`div`);Object.assign(i.style,{width:`100%`,maxWidth:`360px`,borderRadius:`12px`,background:`#fff`,padding:`28px 24px 20px`,boxSizing:`border-box`,textAlign:`center`,boxShadow:`0 12px 40px rgba(0, 0, 0, 0.25)`});let a=document.createElement(`div`);a.setAttribute(`aria-hidden`,`true`),Object.assign(a.style,{display:`inline-flex`,alignItems:`center`,justifyContent:`center`,gap:`6px`,marginBottom:`16px`,fontSize:`28px`,fontWeight:`600`,letterSpacing:`-0.02em`,color:`#000`,lineHeight:`1`}),a.innerHTML=`<svg width="22" height="26" viewBox="0 0 814 1000" fill="currentColor" xmlns="http://www.w3.org/2000/svg"><path d="M788.1 340.9c-5.8 4.5-108.2 62.2-108.2 190.5 0 148.4 130.3 200.9 134.2 202.2-.6 3.2-20.7 71.9-68.7 141.9-42.8 61.6-87.5 123.1-155.5 123.1s-85.5-39.5-164-39.5c-76.5 0-103.7 40.8-165.9 40.8s-105.6-57-155.5-127C46.7 790.7 0 663 0 541.8c0-194.4 126.4-297.5 250.8-297.5 66.1 0 121.2 43.4 162.7 43.4 39.5 0 101.1-46 176.3-46 28.5 0 130.9 2.6 198.3 99.2zm-234-181.5c31.1-36.9 53.1-88.1 53.1-139.3 0-7.1-.6-14.3-1.9-20.1-50.6 1.9-110.8 33.7-147.1 75.8-28.5 32.4-55.1 83.6-55.1 135.5 0 7.8 1.3 15.6 1.9 18.1 3.2.6 8.4 1.3 13.6 1.3 45.4 0 102.5-30.4 135.5-71.3z"/></svg><span>Pay</span>`;let o=document.createElement(`p`);o.id=`amos-apple-pay-waiting-title`,Object.assign(o.style,{margin:`0 0 20px`,fontSize:`15px`,lineHeight:`1.45`,color:`#1a1a1a`}),o.textContent=`Complete your payment in the open Apple Pay window, or close Apple Pay to continue paying another way.`;let s=document.createElement(`button`);return s.type=`button`,s.textContent=`Cancel payment`,Object.assign(s.style,{display:`block`,width:`100%`,border:`none`,borderRadius:`8px`,padding:`12px 16px`,background:`#2c2c2e`,color:`#fff`,fontSize:`15px`,fontWeight:`500`,cursor:`pointer`}),s.addEventListener(`click`,t),i.append(a,o,s),r.append(i),document.body.append(r),r}function n(){document.querySelector(`[${e}]`)?.remove()}function r(e){let[t=``,n=``,r=``]=e?.split(`.`)??[],i=typeof atob==`function`?atob:e=>Buffer.from(e,`base64`).toString(`utf8`);return{header:JSON.parse(i(t)),payload:JSON.parse(i(n)),signature:r}}function i(e){let{env:t=`sandbox`}=r(e).payload;switch(t){case`production`:return`https://embed.amos.com`;case`sandbox`:return`https://embed-sandbox.amos.com`;default:return`https://embed-sandbox.amos.com`}}function a(e){if(!e||typeof e!=`object`)return;let t={};for(let[n,r]of Object.entries(e)){if(typeof r==`string`){if(r.length===0)continue;t[n]=r;continue}typeof r==`number`&&Number.isFinite(r)&&(t[n]=r)}return Object.keys(t).length>0?t:void 0}function o(e){let t={};if(e.buttonstyle!==void 0&&(t.buttonstyle=e.buttonstyle),e.type!==void 0&&(t.type=e.type),e.locale!==void 0&&(t.locale=e.locale),e.style!==void 0){let n=a(e.style);n&&(t.style=n)}return t}function s(e){let t={};if(e.buttonType!==void 0&&(t.buttonType=e.buttonType),e.buttonColor!==void 0&&(t.buttonColor=e.buttonColor),e.buttonRadius!==void 0&&(t.buttonRadius=e.buttonRadius),e.buttonSizeMode!==void 0&&(t.buttonSizeMode=e.buttonSizeMode),e.buttonLocale!==void 0&&(t.buttonLocale=e.buttonLocale),e.buttonBorderType!==void 0&&(t.buttonBorderType=e.buttonBorderType),e.style!==void 0){let n=a(e.style);n&&(t.style=n)}return t}function c(e){return e}function l(e){return new URL(e.src).origin}function u(e){e?.contentWindow&&e.contentWindow.postMessage(c({type:`PARENT_ACKNOWLEDGED_IFRAME_READY`}),l(e))}function d({iframe:e,appearance:t={}}){e?.contentWindow&&e.contentWindow.postMessage(c({type:`UPDATE_APPEARANCE`,appearance:t}),l(e))}function f({iframe:e,props:t}){e?.contentWindow&&e.contentWindow.postMessage(c({type:`UPDATE_APPLE_PAY_BUTTON`,props:o(t)}),l(e))}function p({iframe:e,props:t}){e?.contentWindow&&e.contentWindow.postMessage(c({type:`UPDATE_GOOGLE_PAY_BUTTON`,props:s(t)}),l(e))}function m({iframe:e,amount:t}){e?.contentWindow&&e.contentWindow.postMessage(c({type:`UPDATE_AMOUNT`,amount:t}),l(e))}function h({iframe:e,merchantName:t}){e?.contentWindow&&e.contentWindow.postMessage(c({type:`UPDATE_MERCHANT_NAME`,merchantName:t}),l(e))}function g({iframe:e}){let t=crypto.randomUUID();return new Promise(n=>{e?.contentWindow&&e.contentWindow.postMessage(c({type:`VALIDATE_FORM`,requestId:t}),l(e));let r=setTimeout(()=>{window.removeEventListener(`message`,i),n(!1)},5e3);function i(e){e.data.type===`VALIDATE_FORM`&&e.data.requestId===t&&(window.removeEventListener(`message`,i),clearTimeout(r),n(e.data.isValid??!1))}window.addEventListener(`message`,i)})}function _({iframe:e}){e?.contentWindow&&e.contentWindow.postMessage(c({type:`RESET_FORM`}),l(e))}function v({iframe:e,token:t}){if(!e?.contentWindow)return;let{payment_intent_id:n}=r(t).payload;e.contentWindow.postMessage(c({type:`CONFIRM_PAYMENT_INTENT`,token:t,id:n??void 0}),l(e))}function y({iframe:e,token:t}){if(!e?.contentWindow)return;let{setup_intent_id:n}=r(t).payload;e.contentWindow.postMessage(c({type:`CONFIRM_SETUP_INTENT`,token:t,id:n??void 0}),l(e))}function b({iframe:e,result:t}){e?.contentWindow&&e.contentWindow.postMessage(c({type:`CONFIRMATION_RESULT`,result:t}),l(e))}function x(e){return`${i(e)}/iframe/apple-pay?token=${e}`}function S(){return`40px`}function C(e){e.contentWindow?.postMessage(c({type:`APPLE_PAY_CANCEL`}),l(e))}function w(e,r){let i={...r};function a(){m({iframe:e,amount:i.amount})}function o(){h({iframe:e,merchantName:i.merchantName})}function s(){f({iframe:e,props:i})}function c(r){if(r.source===e.contentWindow)switch(r.data.type){case`IFRAME_READY`:u(e),d({iframe:e,appearance:i.appearance}),a(),o(),s();break;case`UPDATE_HEIGHT`:i.onHeightChange?.(r.data.height);break;case`UPDATE_APPEARANCE`:d({iframe:e,appearance:r.data.appearance});break;case`UPDATED_APPEARANCE`:i.onAppearanceReady?.();break;case`APPLE_PAY_WINDOW_OPEN`:t({onCancel:()=>{C(e),n()}});break;case`APPLE_PAY_WINDOW_CLOSE`:n();break;case`CREATE_PAYMENT_INTENT`:i.onInitiatePaymentIntentRequest({paymentIntentCreateAttributes:r.data.paymentIntentCreateAttributes,customerCreateAttributes:r.data.customerCreateAttributes}).then(t=>{v({iframe:e,token:t})}).catch(e=>{n(),i.onResult({status:`failed`,errorMessage:e instanceof Error?e.message:`Unknown error`})});break;case`CONFIRMATION_RESULT`:n(),i.onResult(r.data.result)}}return window.addEventListener(`message`,c),{update(t){let n=`appearance`in t,r=`amount`in t,c=`merchantName`in t,l=`buttonstyle`in t||`type`in t||`locale`in t||`style`in t;i={...i,...t},n&&d({iframe:e,appearance:i.appearance}),r&&a(),c&&o(),l&&s()},destroy(){window.removeEventListener(`message`,c),n()}}}function T(e){return`${i(e)}/iframe/google-pay?token=${e}`}function E(){return`40px`}function D(e,t){let n={...t};function r(){m({iframe:e,amount:n.amount})}function i(){h({iframe:e,merchantName:n.merchantName})}function a(){p({iframe:e,props:n})}function o(t){if(t.source===e.contentWindow)switch(t.data.type){case`IFRAME_READY`:u(e),d({iframe:e,appearance:n.appearance}),r(),i(),a();break;case`UPDATE_HEIGHT`:n.onHeightChange?.(t.data.height);break;case`UPDATE_APPEARANCE`:d({iframe:e,appearance:t.data.appearance});break;case`UPDATED_APPEARANCE`:n.onAppearanceReady?.();break;case`CREATE_PAYMENT_INTENT`:n.onInitiatePaymentIntentRequest({paymentIntentCreateAttributes:t.data.paymentIntentCreateAttributes,customerCreateAttributes:t.data.customerCreateAttributes}).then(t=>{v({iframe:e,token:t})}).catch(e=>{n.onResult({status:`failed`,errorMessage:e instanceof Error?e.message:`Unknown error`})});break;case`CONFIRMATION_RESULT`:n.onResult(t.data.result)}}return window.addEventListener(`message`,o),{update(t){let o=`appearance`in t,s=`amount`in t,c=`merchantName`in t,l=`buttonType`in t||`buttonColor`in t||`buttonRadius`in t||`buttonSizeMode`in t||`buttonLocale`in t||`buttonBorderType`in t||`style`in t;n={...n,...t},o&&d({iframe:e,appearance:n.appearance}),s&&r(),c&&i(),l&&a()},destroy(){window.removeEventListener(`message`,o)}}}function O({paymentData:e}){return{paymentMethod:{type:`googlepay`,billing_address_attributes:{name:e.shippingAddress?.name,address_line1:e.shippingAddress?.address1,address_line2:e.shippingAddress?.address2,city:e.shippingAddress?.locality,state:e.shippingAddress?.administrativeArea,postal_code:e.shippingAddress?.postalCode,country:e.shippingAddress?.countryCode,email:e.email,phone:e.shippingAddress?.phoneNumber},card_profile_attributes:{wallet_payload:e.paymentMethodData.tokenizationData.token}}}}var k=`amos-js-form-skeleton-styles`,A={"--accent":`oklch(0.97 0 0)`,"--radius":`0.625rem`,"--input-height":`2.25rem`,"--floating-input-height":`3.25rem`,"--field-gap":`1rem`,"--control-gap":`0.5rem`,"--label-font-size":`0.875rem`},j=`
+.amos-js-form-skeleton {
+  box-sizing: border-box;
+  container-type: inline-size;
+  display: flex;
+  flex-direction: column;
+  gap: var(--field-gap);
+  margin: 0 -4px;
+  padding-block: 0.25rem;
+  pointer-events: none;
+  width: calc(100% + 8px);
+}
+.amos-js-form-skeleton-field {
+  display: flex;
+  flex: 1 1 0;
+  flex-direction: column;
+  min-width: 0;
+  width: 100%;
+}
+.amos-js-form-skeleton-label {
+  flex-shrink: 0;
+  font-size: var(--label-font-size);
+  height: 1.75rem;
+  line-height: 1.75rem;
+}
+.amos-js-form-skeleton-input {
+  animation: amos-js-skeleton-pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+  background: var(--accent);
+  border-radius: calc(var(--radius) * 0.8);
+  box-sizing: border-box;
+  height: var(--input-height);
+  width: 100%;
+}
+.amos-js-form-skeleton-input-floating {
+  height: var(--floating-input-height);
+}
+.amos-js-form-skeleton-row {
+  align-items: flex-start;
+  display: flex;
+  gap: var(--control-gap);
+  width: 100%;
+}
+.amos-js-form-skeleton-row-stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--field-gap);
+  width: 100%;
+}
+@container (min-width: 24rem) {
+  .amos-js-form-skeleton-row-stack {
+    align-items: flex-start;
+    flex-direction: row;
+    gap: var(--control-gap);
+  }
+}
+@keyframes amos-js-skeleton-pulse {
+  50% { opacity: 0.5; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .amos-js-form-skeleton-input {
+    animation: none;
+  }
+}
+`;function M(){if(document.getElementById(k))return;let e=document.createElement(`style`);e.id=k,e.textContent=j,document.head.appendChild(e)}function N(e,t){for(let[t,n]of Object.entries(A))e.style.setProperty(t,n);let n=t?.themeVariables;if(n)for(let[t,r]of Object.entries(n))typeof r==`string`&&r.trim()!==``&&e.style.setProperty(t,r.trim())}function P(e,t){let n=document.createElement(`div`);if(n.className=e,t)for(let e of t)n.appendChild(e);return n}function F(e,t){let n=P(`amos-js-form-skeleton-field`);t!==void 0&&(n.style.flexGrow=String(t)),e===`above`&&n.appendChild(P(`amos-js-form-skeleton-label`));let r=P(`amos-js-form-skeleton-input`);return e===`floating`&&r.classList.add(`amos-js-form-skeleton-input-floating`),n.appendChild(r),n}function I(e,t){return P(t?`amos-js-form-skeleton-row-stack`:`amos-js-form-skeleton-row`,e)}function L({labels:e,requirement:t,wrapCountryZip:n}){return t===`full`?[F(e),F(e),I([F(e,1.4),F(e,.7),F(e,.8)],!1),F(e)]:[I([F(e),F(e)],n)]}function R(e){let t=e.appearance?.labels??`above`,n=e.billingAddressRequirement??`country`;if(e.kind===`card`){let r=[F(t),I([F(t),F(t)],!1)];return e.additionalFields?.cardholderName&&r.push(F(t)),r.push(...L({labels:t,requirement:n,wrapCountryZip:!1})),r}return[F(t),I([F(t),F(t)],!0),F(t),I([F(`above`),F(`above`)],!0),...L({labels:t,requirement:n,wrapCountryZip:!0})]}function z(e){M();let t=P(`amos-js-form-skeleton`);t.setAttribute(`aria-hidden`,`true`);function n(e){N(t,e.appearance),t.replaceChildren(...R(e))}return n(e),{element:t,update:n}}var B={country:212,full:452},V=80,H={country:400,full:640};function U(e,t={cardholderName:!1},n=`country`){let r=Object.entries(t).filter(([,e])=>e).map(([e])=>e).join(`,`),a=new URLSearchParams({token:e,additionalFields:r,billingAddressRequirement:n});return`${i(e)}/iframe/card?${a}`}function W(e,t=`country`){let n=new URLSearchParams({token:e,billingAddressRequirement:t});return`${i(e)}/iframe/bank?${n}`}function G(e={cardholderName:!1},t=`country`){return`${(B[t]??B.country)+(e.cardholderName?V:0)}px`}function K(e=`country`){return`${H[e]??H.country}px`}function q(e,t){let n={...t};function r(t){if(t.source===e.contentWindow)switch(t.data.type){case`IFRAME_READY`:u(e),d({iframe:e,appearance:n.appearance});break;case`UPDATE_HEIGHT`:n.onHeightChange?.(t.data.height);break;case`UPDATE_APPEARANCE`:d({iframe:e,appearance:t.data.appearance});break;case`UPDATED_APPEARANCE`:n.onAppearanceReady?.();break;case`FORM_VALIDITY_CHANGE`:n.onValidityChange?.({isValid:t.data.isValid});break;case`CONFIRMATION_RESULT`:n.onResult(t.data.result)}}return window.addEventListener(`message`,r),{update(t){let r=`appearance`in t;n={...n,...t},r&&d({iframe:e,appearance:n.appearance})},destroy(){window.removeEventListener(`message`,r)}}}function J(e){if(typeof e==`string`){let t=document.querySelector(e);if(!(t instanceof HTMLElement))throw Error(`[amos-js] Container "${e}" did not match any HTMLElement.`);return t}return e}var Y={width:`calc(100% + 8px)`,transition:`opacity 150ms ease-in, height 200ms ease-in-out`,margin:`0 -4px`,opacity:`0`,border:`0`},X={position:`absolute`,top:`0`,left:`-4px`,width:`calc(100% + 8px)`,height:`100%`,margin:`0`,transition:`none`,pointerEvents:`none`};function Z({src:e,title:t,name:n,height:r,allow:i}){let a=document.createElement(`iframe`);return a.src=e,a.title=t,a.name=n,a.setAttribute(`role`,`presentation`),a.scrolling=`no`,i&&(a.allow=i),Object.assign(a.style,Y,{height:r}),a}function Q({host:e,iframe:t,listenerOptions:n,skeletonOptions:r}){let i=document.createElement(`div`);i.style.position=`relative`,i.style.width=`100%`,i.setAttribute(`aria-busy`,`true`);let a=z(r);Object.assign(t.style,X),i.append(a.element,t),e.appendChild(i);let o=!1,s=!1,c,l=r.appearance,u,d;function f(){return i.getBoundingClientRect().height}function p(){return c?Number.parseFloat(c):NaN}function m(){if(o)return;o=!0,d!==void 0&&(clearTimeout(d),d=void 0);let e=f(),n=p(),r=Number.isFinite(n)?Math.max(n,e):e;t.style.transition=`none`,t.style.position=``,t.style.top=``,t.style.left=``,t.style.margin=Y.margin??``,t.style.height=`${r}px`,t.style.opacity=`1`,t.style.pointerEvents=``,a.element.remove(),i.removeAttribute(`aria-busy`),u=setTimeout(()=>{t.style.transition=`height 200ms ease-in-out`},400)}function h(){if(o||!s)return;let e=p(),t=f();Number.isFinite(e)&&e>=t-2&&m()}let g=q(t,{...n,onHeightChange:e=>{c=e,o?t.style.height=e:h(),n.onHeightChange?.(e)},onAppearanceReady:()=>{s=!0,h(),!o&&d===void 0&&(d=setTimeout(()=>{m()},1500)),n.onAppearanceReady?.()}});return{iframe:t,update(e){g.update(e),!o&&`appearance`in e&&(l=e.appearance,a.update({...r,appearance:l}))},destroy(){u!==void 0&&clearTimeout(u),d!==void 0&&clearTimeout(d),g.destroy(),i.remove()}}}function $(e,t){let n=J(e),{renderToken:r,additionalFields:i={cardholderName:!1},billingAddressRequirement:a=`country`,...o}=t;return Q({host:n,iframe:Z({src:U(r,i,a),title:`Secure credit card payment method form powered by Amos`,name:`amos-credit-card-payment-method-form`,height:G(i,a)}),listenerOptions:o,skeletonOptions:{kind:`card`,appearance:o.appearance,additionalFields:i,billingAddressRequirement:a}})}function ee(e,t){let n=J(e),{renderToken:r,billingAddressRequirement:i=`country`,...a}=t;return Q({host:n,iframe:Z({src:W(r,i),title:`Secure bank account payment method form powered by Amos`,name:`amos-bank-account-payment-method-form`,height:K(i)}),listenerOptions:a,skeletonOptions:{kind:`bank`,appearance:a.appearance,billingAddressRequirement:i}})}function te(e,t){let n=J(e),{renderToken:r,...i}=t,a=Z({src:T(r),title:`Secure Google Pay button powered by Amos`,name:`amos-google-pay-button`,height:E(),allow:`payment`});n.appendChild(a);let o=D(a,{...i,onHeightChange:e=>{a.style.height=e,i.onHeightChange?.(e)},onAppearanceReady:()=>{a.style.opacity=`1`,i.onAppearanceReady?.()}});return{iframe:a,update:o.update,destroy(){o.destroy(),a.remove()}}}function ne(e,t){let n=J(e),{renderToken:r,...i}=t,a=Z({src:x(r),title:`Secure Apple Pay button powered by Amos`,name:`amos-apple-pay-button`,height:S(),allow:`payment`});n.appendChild(a);let o=w(a,{...i,onHeightChange:e=>{a.style.height=e,i.onHeightChange?.(e)},onAppearanceReady:()=>{a.style.opacity=`1`,i.onAppearanceReady?.()}});return{iframe:a,update:o.update,destroy(){o.destroy(),a.remove()}}}exports.attachApplePayButtonListeners=w,exports.attachGooglePayButtonListeners=D,exports.attachPaymentMethodFormListeners=q,exports.confirmPaymentIntent=v,exports.confirmSetupIntent=y,exports.createMessage=c,exports.decodeJwt=r,exports.formatGooglePayPaymentData=O,exports.getApplePayButtonInitialHeight=S,exports.getApplePayButtonSrc=x,exports.getBankAccountFormInitialHeight=K,exports.getBankAccountFormSrc=W,exports.getCreditCardFormInitialHeight=G,exports.getCreditCardFormSrc=U,exports.getEmbedOrigin=i,exports.getGooglePayButtonInitialHeight=E,exports.getGooglePayButtonSrc=T,exports.mountAmosApplePayButton=ne,exports.mountAmosBankAccountPaymentMethodForm=ee,exports.mountAmosCreditCardPaymentMethodForm=$,exports.mountAmosGooglePayButton=te,exports.pickApplePayButtonElementProps=o,exports.pickGooglePayButtonElementProps=s,exports.resetForm=_,exports.sendConfirmationResult=b,exports.sendParentReadyMessage=u,exports.serializeWalletButtonStyle=a,exports.updateAmount=m,exports.updateAppearance=d,exports.updateApplePayButton=f,exports.updateGooglePayButton=p,exports.updateMerchantName=h,exports.validateForm=g;

package/dist/index.mjs

@@ -392,15 +392,96 @@ function O({ paymentData: e }) {
 	} };
 }
 //#endregion
+//#region src/form-skeleton.ts
+var k = "amos-js-form-skeleton-styles", A = {
+	"--accent": "oklch(0.97 0 0)",
+	"--radius": "0.625rem",
+	"--input-height": "2.25rem",
+	"--floating-input-height": "3.25rem",
+	"--field-gap": "1rem",
+	"--control-gap": "0.5rem",
+	"--label-font-size": "0.875rem"
+}, j = "\n.amos-js-form-skeleton {\n  box-sizing: border-box;\n  container-type: inline-size;\n  display: flex;\n  flex-direction: column;\n  gap: var(--field-gap);\n  margin: 0 -4px;\n  padding-block: 0.25rem;\n  pointer-events: none;\n  width: calc(100% + 8px);\n}\n.amos-js-form-skeleton-field {\n  display: flex;\n  flex: 1 1 0;\n  flex-direction: column;\n  min-width: 0;\n  width: 100%;\n}\n.amos-js-form-skeleton-label {\n  flex-shrink: 0;\n  font-size: var(--label-font-size);\n  height: 1.75rem;\n  line-height: 1.75rem;\n}\n.amos-js-form-skeleton-input {\n  animation: amos-js-skeleton-pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;\n  background: var(--accent);\n  border-radius: calc(var(--radius) * 0.8);\n  box-sizing: border-box;\n  height: var(--input-height);\n  width: 100%;\n}\n.amos-js-form-skeleton-input-floating {\n  height: var(--floating-input-height);\n}\n.amos-js-form-skeleton-row {\n  align-items: flex-start;\n  display: flex;\n  gap: var(--control-gap);\n  width: 100%;\n}\n.amos-js-form-skeleton-row-stack {\n  display: flex;\n  flex-direction: column;\n  gap: var(--field-gap);\n  width: 100%;\n}\n@container (min-width: 24rem) {\n  .amos-js-form-skeleton-row-stack {\n    align-items: flex-start;\n    flex-direction: row;\n    gap: var(--control-gap);\n  }\n}\n@keyframes amos-js-skeleton-pulse {\n  50% { opacity: 0.5; }\n}\n@media (prefers-reduced-motion: reduce) {\n  .amos-js-form-skeleton-input {\n    animation: none;\n  }\n}\n";
+function M() {
+	if (document.getElementById(k)) return;
+	let e = document.createElement("style");
+	e.id = k, e.textContent = j, document.head.appendChild(e);
+}
+function N(e, t) {
+	for (let [t, n] of Object.entries(A)) e.style.setProperty(t, n);
+	let n = t?.themeVariables;
+	if (n) for (let [t, r] of Object.entries(n)) typeof r == "string" && r.trim() !== "" && e.style.setProperty(t, r.trim());
+}
+function P(e, t) {
+	let n = document.createElement("div");
+	if (n.className = e, t) for (let e of t) n.appendChild(e);
+	return n;
+}
+function F(e, t) {
+	let n = P("amos-js-form-skeleton-field");
+	t !== void 0 && (n.style.flexGrow = String(t)), e === "above" && n.appendChild(P("amos-js-form-skeleton-label"));
+	let r = P("amos-js-form-skeleton-input");
+	return e === "floating" && r.classList.add("amos-js-form-skeleton-input-floating"), n.appendChild(r), n;
+}
+function I(e, t) {
+	return P(t ? "amos-js-form-skeleton-row-stack" : "amos-js-form-skeleton-row", e);
+}
+function L({ labels: e, requirement: t, wrapCountryZip: n }) {
+	return t === "full" ? [
+		F(e),
+		F(e),
+		I([
+			F(e, 1.4),
+			F(e, .7),
+			F(e, .8)
+		], !1),
+		F(e)
+	] : [I([F(e), F(e)], n)];
+}
+function R(e) {
+	let t = e.appearance?.labels ?? "above", n = e.billingAddressRequirement ?? "country";
+	if (e.kind === "card") {
+		let r = [F(t), I([F(t), F(t)], !1)];
+		return e.additionalFields?.cardholderName && r.push(F(t)), r.push(...L({
+			labels: t,
+			requirement: n,
+			wrapCountryZip: !1
+		})), r;
+	}
+	return [
+		F(t),
+		I([F(t), F(t)], !0),
+		F(t),
+		I([F("above"), F("above")], !0),
+		...L({
+			labels: t,
+			requirement: n,
+			wrapCountryZip: !0
+		})
+	];
+}
+function z(e) {
+	M();
+	let t = P("amos-js-form-skeleton");
+	t.setAttribute("aria-hidden", "true");
+	function n(e) {
+		N(t, e.appearance), t.replaceChildren(...R(e));
+	}
+	return n(e), {
+		element: t,
+		update: n
+	};
+}
+//#endregion
 //#region src/payment-method-form.ts
-var k = {
+var B = {
 	country: 212,
 	full: 452
-}, A = 80, j = {
+}, V = 80, H = {
 	country: 400,
 	full: 640
 };
-function M(e, t = { cardholderName: !1 }, n = "country") {
+function U(e, t = { cardholderName: !1 }, n = "country") {
 	let r = Object.entries(t).filter(([, e]) => e).map(([e]) => e).join(","), a = new URLSearchParams({
 		token: e,
 		additionalFields: r,
@@ -408,20 +489,20 @@ function M(e, t = { cardholderName: !1 }, n = "country") {
 	});
 	return `${i(e)}/iframe/card?${a}`;
 }
-function N(e, t = "country") {
+function W(e, t = "country") {
 	let n = new URLSearchParams({
 		token: e,
 		billingAddressRequirement: t
 	});
 	return `${i(e)}/iframe/bank?${n}`;
 }
-function P(e = { cardholderName: !1 }, t = "country") {
-	return `${(k[t] ?? k.country) + (e.cardholderName ? A : 0)}px`;
+function G(e = { cardholderName: !1 }, t = "country") {
+	return `${(B[t] ?? B.country) + (e.cardholderName ? V : 0)}px`;
 }
-function F(e = "country") {
-	return `${j[e] ?? j.country}px`;
+function K(e = "country") {
+	return `${H[e] ?? H.country}px`;
 }
-function I(e, t) {
+function q(e, t) {
 	let n = { ...t };
 	function r(t) {
 		if (t.source === e.contentWindow) switch (t.data.type) {
@@ -443,6 +524,9 @@ function I(e, t) {
 			case "UPDATED_APPEARANCE":
 				n.onAppearanceReady?.();
 				break;
+			case "FORM_VALIDITY_CHANGE":
+				n.onValidityChange?.({ isValid: t.data.isValid });
+				break;
 			case "CONFIRMATION_RESULT": n.onResult(t.data.result);
 		}
 	}
@@ -464,7 +548,7 @@ function I(e, t) {
 }
 //#endregion
 //#region src/mount.ts
-function L(e) {
+function J(e) {
 	if (typeof e == "string") {
 		let t = document.querySelector(e);
 		if (!(t instanceof HTMLElement)) throw Error(`[amos-js] Container "${e}" did not match any HTMLElement.`);
@@ -472,69 +556,114 @@ function L(e) {
 	}
 	return e;
 }
-var R = {
+var Y = {
 	width: "calc(100% + 8px)",
 	transition: "opacity 150ms ease-in, height 200ms ease-in-out",
 	margin: "0 -4px",
 	opacity: "0",
 	border: "0"
+}, X = {
+	position: "absolute",
+	top: "0",
+	left: "-4px",
+	width: "calc(100% + 8px)",
+	height: "100%",
+	margin: "0",
+	transition: "none",
+	pointerEvents: "none"
 };
-function z({ src: e, title: t, name: n, height: r, allow: i }) {
+function Z({ src: e, title: t, name: n, height: r, allow: i }) {
 	let a = document.createElement("iframe");
-	return a.src = e, a.title = t, a.name = n, a.setAttribute("role", "presentation"), a.scrolling = "no", i && (a.allow = i), Object.assign(a.style, R, { height: r }), a;
-}
-function B(e, t) {
-	let n = L(e), { renderToken: r, additionalFields: i = { cardholderName: !1 }, billingAddressRequirement: a = "country", ...o } = t, s = z({
-		src: M(r, i, a),
-		title: "Secure credit card payment method form powered by Amos",
-		name: "amos-credit-card-payment-method-form",
-		height: P(i, a)
-	});
-	n.appendChild(s);
-	let c = I(s, {
-		...o,
+	return a.src = e, a.title = t, a.name = n, a.setAttribute("role", "presentation"), a.scrolling = "no", i && (a.allow = i), Object.assign(a.style, Y, { height: r }), a;
+}
+function Q({ host: e, iframe: t, listenerOptions: n, skeletonOptions: r }) {
+	let i = document.createElement("div");
+	i.style.position = "relative", i.style.width = "100%", i.setAttribute("aria-busy", "true");
+	let a = z(r);
+	Object.assign(t.style, X), i.append(a.element, t), e.appendChild(i);
+	let o = !1, s = !1, c, l = r.appearance, u, d;
+	function f() {
+		return i.getBoundingClientRect().height;
+	}
+	function p() {
+		return c ? Number.parseFloat(c) : NaN;
+	}
+	function m() {
+		if (o) return;
+		o = !0, d !== void 0 && (clearTimeout(d), d = void 0);
+		let e = f(), n = p(), r = Number.isFinite(n) ? Math.max(n, e) : e;
+		t.style.transition = "none", t.style.position = "", t.style.top = "", t.style.left = "", t.style.margin = Y.margin ?? "", t.style.height = `${r}px`, t.style.opacity = "1", t.style.pointerEvents = "", a.element.remove(), i.removeAttribute("aria-busy"), u = setTimeout(() => {
+			t.style.transition = "height 200ms ease-in-out";
+		}, 400);
+	}
+	function h() {
+		if (o || !s) return;
+		let e = p(), t = f();
+		Number.isFinite(e) && e >= t - 2 && m();
+	}
+	let g = q(t, {
+		...n,
 		onHeightChange: (e) => {
-			s.style.height = e, o.onHeightChange?.(e);
+			c = e, o ? t.style.height = e : h(), n.onHeightChange?.(e);
 		},
 		onAppearanceReady: () => {
-			s.style.opacity = "1", o.onAppearanceReady?.();
+			s = !0, h(), !o && d === void 0 && (d = setTimeout(() => {
+				m();
+			}, 1500)), n.onAppearanceReady?.();
 		}
 	});
 	return {
-		iframe: s,
-		update: c.update,
+		iframe: t,
+		update(e) {
+			g.update(e), !o && "appearance" in e && (l = e.appearance, a.update({
+				...r,
+				appearance: l
+			}));
+		},
 		destroy() {
-			c.destroy(), s.remove();
+			u !== void 0 && clearTimeout(u), d !== void 0 && clearTimeout(d), g.destroy(), i.remove();
 		}
 	};
 }
-function V(e, t) {
-	let n = L(e), { renderToken: r, billingAddressRequirement: i = "country", ...a } = t, o = z({
-		src: N(r, i),
-		title: "Secure bank account payment method form powered by Amos",
-		name: "amos-bank-account-payment-method-form",
-		height: F(i)
-	});
-	n.appendChild(o);
-	let s = I(o, {
-		...a,
-		onHeightChange: (e) => {
-			o.style.height = e, a.onHeightChange?.(e);
-		},
-		onAppearanceReady: () => {
-			o.style.opacity = "1", a.onAppearanceReady?.();
+function $(e, t) {
+	let n = J(e), { renderToken: r, additionalFields: i = { cardholderName: !1 }, billingAddressRequirement: a = "country", ...o } = t;
+	return Q({
+		host: n,
+		iframe: Z({
+			src: U(r, i, a),
+			title: "Secure credit card payment method form powered by Amos",
+			name: "amos-credit-card-payment-method-form",
+			height: G(i, a)
+		}),
+		listenerOptions: o,
+		skeletonOptions: {
+			kind: "card",
+			appearance: o.appearance,
+			additionalFields: i,
+			billingAddressRequirement: a
 		}
 	});
-	return {
-		iframe: o,
-		update: s.update,
-		destroy() {
-			s.destroy(), o.remove();
+}
+function ee(e, t) {
+	let n = J(e), { renderToken: r, billingAddressRequirement: i = "country", ...a } = t;
+	return Q({
+		host: n,
+		iframe: Z({
+			src: W(r, i),
+			title: "Secure bank account payment method form powered by Amos",
+			name: "amos-bank-account-payment-method-form",
+			height: K(i)
+		}),
+		listenerOptions: a,
+		skeletonOptions: {
+			kind: "bank",
+			appearance: a.appearance,
+			billingAddressRequirement: i
 		}
-	};
+	});
 }
-function H(e, t) {
-	let n = L(e), { renderToken: r, ...i } = t, a = z({
+function te(e, t) {
+	let n = J(e), { renderToken: r, ...i } = t, a = Z({
 		src: T(r),
 		title: "Secure Google Pay button powered by Amos",
 		name: "amos-google-pay-button",
@@ -559,8 +688,8 @@ function H(e, t) {
 		}
 	};
 }
-function U(e, t) {
-	let n = L(e), { renderToken: r, ...i } = t, a = z({
+function ne(e, t) {
+	let n = J(e), { renderToken: r, ...i } = t, a = Z({
 		src: x(r),
 		title: "Secure Apple Pay button powered by Amos",
 		name: "amos-apple-pay-button",
@@ -586,4 +715,4 @@ function U(e, t) {
 	};
 }
 //#endregion
-export { w as attachApplePayButtonListeners, D as attachGooglePayButtonListeners, I as attachPaymentMethodFormListeners, v as confirmPaymentIntent, y as confirmSetupIntent, c as createMessage, r as decodeJwt, O as formatGooglePayPaymentData, S as getApplePayButtonInitialHeight, x as getApplePayButtonSrc, F as getBankAccountFormInitialHeight, N as getBankAccountFormSrc, P as getCreditCardFormInitialHeight, M as getCreditCardFormSrc, i as getEmbedOrigin, E as getGooglePayButtonInitialHeight, T as getGooglePayButtonSrc, U as mountAmosApplePayButton, V as mountAmosBankAccountPaymentMethodForm, B as mountAmosCreditCardPaymentMethodForm, H as mountAmosGooglePayButton, o as pickApplePayButtonElementProps, s as pickGooglePayButtonElementProps, _ as resetForm, b as sendConfirmationResult, u as sendParentReadyMessage, a as serializeWalletButtonStyle, m as updateAmount, d as updateAppearance, f as updateApplePayButton, p as updateGooglePayButton, h as updateMerchantName, g as validateForm };
+export { w as attachApplePayButtonListeners, D as attachGooglePayButtonListeners, q as attachPaymentMethodFormListeners, v as confirmPaymentIntent, y as confirmSetupIntent, c as createMessage, r as decodeJwt, O as formatGooglePayPaymentData, S as getApplePayButtonInitialHeight, x as getApplePayButtonSrc, K as getBankAccountFormInitialHeight, W as getBankAccountFormSrc, G as getCreditCardFormInitialHeight, U as getCreditCardFormSrc, i as getEmbedOrigin, E as getGooglePayButtonInitialHeight, T as getGooglePayButtonSrc, ne as mountAmosApplePayButton, ee as mountAmosBankAccountPaymentMethodForm, $ as mountAmosCreditCardPaymentMethodForm, te as mountAmosGooglePayButton, o as pickApplePayButtonElementProps, s as pickGooglePayButtonElementProps, _ as resetForm, b as sendConfirmationResult, u as sendParentReadyMessage, a as serializeWalletButtonStyle, m as updateAmount, d as updateAppearance, f as updateApplePayButton, p as updateGooglePayButton, h as updateMerchantName, g as validateForm };

package/dist/mount.d.ts

@@ -45,6 +45,9 @@ export type AmosPaymentMethodFormMountController = PaymentMethodFormController &
  * element. Returns a controller exposing the underlying iframe, an
  * `update()` method, and a `destroy()` method.
  *
+ * A field-shaped skeleton is shown immediately and replaced by the
+ * iframe once appearance is applied.
+ *
  * Use the returned `controller.iframe` when calling
  * {@link validateForm}, {@link confirmPaymentIntent}, or
  * {@link confirmSetupIntent}.
@@ -73,6 +76,9 @@ export type AmosBankAccountPaymentMethodFormOptions = PaymentMethodFormListenerO
  * element. Returns a controller exposing the underlying iframe, an
  * `update()` method, and a `destroy()` method.
  *
+ * A field-shaped skeleton is shown immediately and replaced by the
+ * iframe once appearance is applied.
+ *
  * Use the returned `controller.iframe` when calling
  * {@link validateForm}, {@link confirmPaymentIntent}, or
  * {@link confirmSetupIntent}.

package/dist/payment-method-form.d.ts

@@ -1,4 +1,4 @@
-import { Appearance, ConfirmationResult } from './types';
+import { Appearance, ConfirmationResult, PaymentMethodFormValidityChangeEvent } from './types';
 /**
  * The additional fields beyond the standard card number, expiration
  * date, CVV, and billing address fields that are required to be filled
@@ -59,6 +59,12 @@ export type PaymentMethodFormListenerOptions = {
      * iframe's opacity from `0` to `1` to fade it in.
      */
     onAppearanceReady?: () => void;
+    /**
+     * Called when card/bank form validity changes. `isValid` is true
+     * when all required fields are present and valid. Does not include
+     * PCI data. Use this to enable or disable a host checkout button.
+     */
+    onValidityChange?: (event: PaymentMethodFormValidityChangeEvent) => void;
     /**
      * Called when the interactive confirmation flow finishes (success or
      * terminal failure). Not settlement proof — verify via webhooks.

package/dist/types.d.ts

@@ -1,4 +1,12 @@
 import { components } from '@amos.com/node';
+/**
+ * PCI-safe snapshot of card/bank form validity, posted when HTML
+ * constraint validation changes. Use this to enable or disable a host
+ * checkout button.
+ */
+export type PaymentMethodFormValidityChangeEvent = {
+    isValid: boolean;
+};
 /**
  * Why an interactive confirmation attempt ended with `status: "incomplete"`.
  *
@@ -243,6 +251,14 @@ export type Message = {
 } | {
     /** Parent → embed: clear all form field values and API errors. */
     type: "RESET_FORM";
+} | {
+    /**
+     * Embed → parent: card/bank form validity changed.
+     * `isValid` is true when all required fields are present and
+     * valid. Does not include PCI data.
+     */
+    type: "FORM_VALIDITY_CHANGE";
+    isValid: boolean;
 };
 /**
  * Identity helper that brands an object as a typed `Message`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amos.com/amos-js",
-  "version": "0.9.10",
+  "version": "0.9.12",
   "main": "dist/index.js",
   "repository": {
     "type": "git",

package/src/form-skeleton.ts

@@ -0,0 +1,244 @@
+import type {
+  BillingAddressRequirement,
+  CreditCardAdditionalFields,
+} from "./payment-method-form";
+import type { Appearance, AppearanceLabels, ThemeVariable } from "./types";
+
+const STYLE_ID = "amos-js-form-skeleton-styles";
+
+const SKELETON_THEME_DEFAULTS: Record<string, string> = {
+  "--accent": "oklch(0.97 0 0)",
+  "--radius": "0.625rem",
+  "--input-height": "2.25rem",
+  "--floating-input-height": "3.25rem",
+  "--field-gap": "1rem",
+  "--control-gap": "0.5rem",
+  "--label-font-size": "0.875rem",
+};
+
+const SKELETON_STYLES = `
+.amos-js-form-skeleton {
+  box-sizing: border-box;
+  container-type: inline-size;
+  display: flex;
+  flex-direction: column;
+  gap: var(--field-gap);
+  margin: 0 -4px;
+  padding-block: 0.25rem;
+  pointer-events: none;
+  width: calc(100% + 8px);
+}
+.amos-js-form-skeleton-field {
+  display: flex;
+  flex: 1 1 0;
+  flex-direction: column;
+  min-width: 0;
+  width: 100%;
+}
+.amos-js-form-skeleton-label {
+  flex-shrink: 0;
+  font-size: var(--label-font-size);
+  height: 1.75rem;
+  line-height: 1.75rem;
+}
+.amos-js-form-skeleton-input {
+  animation: amos-js-skeleton-pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+  background: var(--accent);
+  border-radius: calc(var(--radius) * 0.8);
+  box-sizing: border-box;
+  height: var(--input-height);
+  width: 100%;
+}
+.amos-js-form-skeleton-input-floating {
+  height: var(--floating-input-height);
+}
+.amos-js-form-skeleton-row {
+  align-items: flex-start;
+  display: flex;
+  gap: var(--control-gap);
+  width: 100%;
+}
+.amos-js-form-skeleton-row-stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--field-gap);
+  width: 100%;
+}
+@container (min-width: 24rem) {
+  .amos-js-form-skeleton-row-stack {
+    align-items: flex-start;
+    flex-direction: row;
+    gap: var(--control-gap);
+  }
+}
+@keyframes amos-js-skeleton-pulse {
+  50% { opacity: 0.5; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .amos-js-form-skeleton-input {
+    animation: none;
+  }
+}
+`;
+
+function ensureSkeletonStyles(): void {
+  if (document.getElementById(STYLE_ID)) {
+    return;
+  }
+  const style = document.createElement("style");
+  style.id = STYLE_ID;
+  style.textContent = SKELETON_STYLES;
+  document.head.appendChild(style);
+}
+
+function applyTheme(
+  element: HTMLElement,
+  appearance: Appearance | undefined,
+): void {
+  for (const [property, value] of Object.entries(SKELETON_THEME_DEFAULTS)) {
+    element.style.setProperty(property, value);
+  }
+  const themeVariables = appearance?.themeVariables;
+  if (!themeVariables) {
+    return;
+  }
+  for (const [property, value] of Object.entries(themeVariables) as Array<
+    [ThemeVariable, string | undefined]
+  >) {
+    if (typeof value === "string" && value.trim() !== "") {
+      element.style.setProperty(property, value.trim());
+    }
+  }
+}
+
+function div(className: string, children?: Array<HTMLElement>): HTMLDivElement {
+  const node = document.createElement("div");
+  node.className = className;
+  if (children) {
+    for (const child of children) {
+      node.appendChild(child);
+    }
+  }
+  return node;
+}
+
+function field(labels: AppearanceLabels, grow?: number): HTMLDivElement {
+  const wrap = div("amos-js-form-skeleton-field");
+  if (grow !== undefined) {
+    wrap.style.flexGrow = String(grow);
+  }
+  if (labels === "above") {
+    wrap.appendChild(div("amos-js-form-skeleton-label"));
+  }
+  const input = div("amos-js-form-skeleton-input");
+  if (labels === "floating") {
+    input.classList.add("amos-js-form-skeleton-input-floating");
+  }
+  wrap.appendChild(input);
+  return wrap;
+}
+
+function row(children: Array<HTMLElement>, wrapAtSm: boolean): HTMLDivElement {
+  return div(
+    wrapAtSm ? "amos-js-form-skeleton-row-stack" : "amos-js-form-skeleton-row",
+    children,
+  );
+}
+
+function billingFields({
+  labels,
+  requirement,
+  wrapCountryZip,
+}: {
+  labels: AppearanceLabels;
+  requirement: BillingAddressRequirement;
+  wrapCountryZip: boolean;
+}): Array<HTMLElement> {
+  if (requirement === "full") {
+    return [
+      field(labels),
+      field(labels),
+      row([field(labels, 1.4), field(labels, 0.7), field(labels, 0.8)], false),
+      field(labels),
+    ];
+  }
+  return [row([field(labels), field(labels)], wrapCountryZip)];
+}
+
+export type PaymentMethodFormSkeletonKind = "card" | "bank";
+
+export type PaymentMethodFormSkeletonOptions = {
+  kind: PaymentMethodFormSkeletonKind;
+  appearance?: Appearance;
+  additionalFields?: CreditCardAdditionalFields;
+  billingAddressRequirement?: BillingAddressRequirement;
+};
+
+function buildChildren(
+  options: PaymentMethodFormSkeletonOptions,
+): Array<HTMLElement> {
+  const labels = options.appearance?.labels ?? "above";
+  const billingAddressRequirement =
+    options.billingAddressRequirement ?? "country";
+
+  if (options.kind === "card") {
+    const children: Array<HTMLElement> = [
+      field(labels),
+      row([field(labels), field(labels)], false),
+    ];
+    if (options.additionalFields?.cardholderName) {
+      children.push(field(labels));
+    }
+    children.push(
+      ...billingFields({
+        labels,
+        requirement: billingAddressRequirement,
+        wrapCountryZip: false,
+      }),
+    );
+    return children;
+  }
+
+  return [
+    field(labels),
+    row([field(labels), field(labels)], true),
+    field(labels),
+    row([field("above"), field("above")], true),
+    ...billingFields({
+      labels,
+      requirement: billingAddressRequirement,
+      wrapCountryZip: true,
+    }),
+  ];
+}
+
+export type PaymentMethodFormSkeleton = {
+  element: HTMLElement;
+  update: (options: PaymentMethodFormSkeletonOptions) => void;
+};
+
+/**
+ * Host-page placeholder that mirrors card/bank field layout using the
+ * same appearance variables the iframe will apply. Shown immediately
+ * while the iframe document loads, then removed when appearance is
+ * ready.
+ */
+export function createPaymentMethodFormSkeleton(
+  options: PaymentMethodFormSkeletonOptions,
+): PaymentMethodFormSkeleton {
+  ensureSkeletonStyles();
+  const element = div("amos-js-form-skeleton");
+  element.setAttribute("aria-hidden", "true");
+
+  function render(next: PaymentMethodFormSkeletonOptions): void {
+    applyTheme(element, next.appearance);
+    element.replaceChildren(...buildChildren(next));
+  }
+
+  render(options);
+
+  return {
+    element,
+    update: render,
+  };
+}

package/src/index.ts

@@ -75,6 +75,7 @@ export type {
   ConfirmationResult,
   GooglePayButtonElementProps,
   Message,
+  PaymentMethodFormValidityChangeEvent,
   ThemeVariable,
   WalletButtonStyle,
 } from "./types";

package/src/mount.ts

@@ -5,6 +5,10 @@ import {
   getApplePayButtonInitialHeight,
   getApplePayButtonSrc,
 } from "./apple-pay";
+import {
+  createPaymentMethodFormSkeleton,
+  type PaymentMethodFormSkeletonOptions,
+} from "./form-skeleton";
 import {
   attachGooglePayButtonListeners,
   type GooglePayButtonController,
@@ -47,6 +51,18 @@ const SHARED_IFRAME_STYLE: Partial<CSSStyleDeclaration> = {
   border: "0",
 };
 
+const SKELETON_IFRAME_STYLE: Partial<CSSStyleDeclaration> = {
+  position: "absolute",
+  top: "0",
+  left: "-4px",
+  width: "calc(100% + 8px)",
+  height: "100%",
+  margin: "0",
+  // Do not interpolate opacity while the skeleton is showing.
+  transition: "none",
+  pointerEvents: "none",
+};
+
 function createIframe({
   src,
   title,
@@ -73,6 +89,133 @@ function createIframe({
   return iframe;
 }
 
+function mountPaymentMethodFormWithSkeleton({
+  host,
+  iframe,
+  listenerOptions,
+  skeletonOptions,
+}: {
+  host: HTMLElement;
+  iframe: HTMLIFrameElement;
+  listenerOptions: PaymentMethodFormListenerOptions;
+  skeletonOptions: PaymentMethodFormSkeletonOptions;
+}): AmosPaymentMethodFormMountController {
+  const wrapper = document.createElement("div");
+  wrapper.style.position = "relative";
+  wrapper.style.width = "100%";
+  wrapper.setAttribute("aria-busy", "true");
+
+  const skeleton = createPaymentMethodFormSkeleton(skeletonOptions);
+  Object.assign(iframe.style, SKELETON_IFRAME_STYLE);
+
+  wrapper.append(skeleton.element, iframe);
+  host.appendChild(wrapper);
+
+  let revealed = false;
+  let appearanceReady = false;
+  let lastHeight: string | undefined;
+  let appearance = skeletonOptions.appearance;
+  let heightTransitionTimer: ReturnType<typeof setTimeout> | undefined;
+  let fallbackRevealTimer: ReturnType<typeof setTimeout> | undefined;
+
+  function skeletonHeightPx(): number {
+    return wrapper.getBoundingClientRect().height;
+  }
+
+  function reportedHeightPx(): number {
+    return lastHeight ? Number.parseFloat(lastHeight) : Number.NaN;
+  }
+
+  function reveal(): void {
+    if (revealed) {
+      return;
+    }
+    revealed = true;
+    if (fallbackRevealTimer !== undefined) {
+      clearTimeout(fallbackRevealTimer);
+      fallbackRevealTimer = undefined;
+    }
+
+    const skeletonPx = skeletonHeightPx();
+    const reportedPx = reportedHeightPx();
+    const revealPx = Number.isFinite(reportedPx)
+      ? Math.max(reportedPx, skeletonPx)
+      : skeletonPx;
+
+    iframe.style.transition = "none";
+    iframe.style.position = "";
+    iframe.style.top = "";
+    iframe.style.left = "";
+    iframe.style.margin = SHARED_IFRAME_STYLE.margin ?? "";
+    iframe.style.height = `${revealPx}px`;
+    iframe.style.opacity = "1";
+    iframe.style.pointerEvents = "";
+    skeleton.element.remove();
+    wrapper.removeAttribute("aria-busy");
+
+    // Height easing is for later layout changes (ZIP show/hide, errors),
+    // not the first paint — that would animate the last row into place.
+    heightTransitionTimer = setTimeout(() => {
+      iframe.style.transition = "height 200ms ease-in-out";
+    }, 400);
+  }
+
+  function tryReveal(): void {
+    if (revealed || !appearanceReady) {
+      return;
+    }
+    const reportedPx = reportedHeightPx();
+    const skeletonPx = skeletonHeightPx();
+    if (Number.isFinite(reportedPx) && reportedPx >= skeletonPx - 2) {
+      reveal();
+    }
+  }
+
+  const controller = attachPaymentMethodFormListeners(iframe, {
+    ...listenerOptions,
+    onHeightChange: (height) => {
+      lastHeight = height;
+      if (revealed) {
+        iframe.style.height = height;
+      } else {
+        tryReveal();
+      }
+      listenerOptions.onHeightChange?.(height);
+    },
+    onAppearanceReady: () => {
+      appearanceReady = true;
+      tryReveal();
+      if (!revealed && fallbackRevealTimer === undefined) {
+        fallbackRevealTimer = setTimeout(() => {
+          reveal();
+        }, 1500);
+      }
+      listenerOptions.onAppearanceReady?.();
+    },
+  });
+
+  return {
+    iframe,
+    update(patch) {
+      controller.update(patch);
+      if (!revealed && "appearance" in patch) {
+        appearance = patch.appearance;
+        skeleton.update({ ...skeletonOptions, appearance });
+      }
+    },
+    destroy() {
+      if (heightTransitionTimer !== undefined) {
+        clearTimeout(heightTransitionTimer);
+      }
+      if (fallbackRevealTimer !== undefined) {
+        clearTimeout(fallbackRevealTimer);
+      }
+      controller.destroy();
+      wrapper.remove();
+    },
+  };
+}
+
 /**
  * Options accepted by {@link mountAmosCreditCardPaymentMethodForm}.
  */
@@ -120,6 +263,9 @@ export type AmosPaymentMethodFormMountController =
  * element. Returns a controller exposing the underlying iframe, an
  * `update()` method, and a `destroy()` method.
  *
+ * A field-shaped skeleton is shown immediately and replaced by the
+ * iframe once appearance is applied.
+ *
  * Use the returned `controller.iframe` when calling
  * {@link validateForm}, {@link confirmPaymentIntent}, or
  * {@link confirmSetupIntent}.
@@ -149,28 +295,18 @@ export function mountAmosCreditCardPaymentMethodForm(
       billingAddressRequirement,
     ),
   });
-  host.appendChild(iframe);
-
-  const controller = attachPaymentMethodFormListeners(iframe, {
-    ...listenerOptions,
-    onHeightChange: (height) => {
-      iframe.style.height = height;
-      listenerOptions.onHeightChange?.(height);
-    },
-    onAppearanceReady: () => {
-      iframe.style.opacity = "1";
-      listenerOptions.onAppearanceReady?.();
-    },
-  });
 
-  return {
+  return mountPaymentMethodFormWithSkeleton({
+    host,
     iframe,
-    update: controller.update,
-    destroy() {
-      controller.destroy();
-      iframe.remove();
+    listenerOptions,
+    skeletonOptions: {
+      kind: "card",
+      appearance: listenerOptions.appearance,
+      additionalFields,
+      billingAddressRequirement,
     },
-  };
+  });
 }
 
 /**
@@ -198,6 +334,9 @@ export type AmosBankAccountPaymentMethodFormOptions =
  * element. Returns a controller exposing the underlying iframe, an
  * `update()` method, and a `destroy()` method.
  *
+ * A field-shaped skeleton is shown immediately and replaced by the
+ * iframe once appearance is applied.
+ *
  * Use the returned `controller.iframe` when calling
  * {@link validateForm}, {@link confirmPaymentIntent}, or
  * {@link confirmSetupIntent}.
@@ -219,28 +358,17 @@ export function mountAmosBankAccountPaymentMethodForm(
     name: "amos-bank-account-payment-method-form",
     height: getBankAccountFormInitialHeight(billingAddressRequirement),
   });
-  host.appendChild(iframe);
-
-  const controller = attachPaymentMethodFormListeners(iframe, {
-    ...listenerOptions,
-    onHeightChange: (height) => {
-      iframe.style.height = height;
-      listenerOptions.onHeightChange?.(height);
-    },
-    onAppearanceReady: () => {
-      iframe.style.opacity = "1";
-      listenerOptions.onAppearanceReady?.();
-    },
-  });
 
-  return {
+  return mountPaymentMethodFormWithSkeleton({
+    host,
     iframe,
-    update: controller.update,
-    destroy() {
-      controller.destroy();
-      iframe.remove();
+    listenerOptions,
+    skeletonOptions: {
+      kind: "bank",
+      appearance: listenerOptions.appearance,
+      billingAddressRequirement,
     },
-  };
+  });
 }
 
 /**

package/src/payment-method-form.ts

@@ -3,7 +3,12 @@ import {
   sendParentReadyMessage,
   updateAppearance as sendUpdateAppearance,
 } from "./messaging";
-import type { Appearance, ConfirmationResult, Message } from "./types";
+import type {
+  Appearance,
+  ConfirmationResult,
+  Message,
+  PaymentMethodFormValidityChangeEvent,
+} from "./types";
 
 /**
  * The additional fields beyond the standard card number, expiration
@@ -126,6 +131,12 @@ export type PaymentMethodFormListenerOptions = {
    * iframe's opacity from `0` to `1` to fade it in.
    */
   onAppearanceReady?: () => void;
+  /**
+   * Called when card/bank form validity changes. `isValid` is true
+   * when all required fields are present and valid. Does not include
+   * PCI data. Use this to enable or disable a host checkout button.
+   */
+  onValidityChange?: (event: PaymentMethodFormValidityChangeEvent) => void;
   /**
    * Called when the interactive confirmation flow finishes (success or
    * terminal failure). Not settlement proof — verify via webhooks.
@@ -191,6 +202,10 @@ export function attachPaymentMethodFormListeners(
         current.onAppearanceReady?.();
         break;
 
+      case "FORM_VALIDITY_CHANGE":
+        current.onValidityChange?.({ isValid: event.data.isValid });
+        break;
+
       case "CONFIRMATION_RESULT":
         current.onResult(event.data.result);
         break;

package/src/types.ts

@@ -2,6 +2,15 @@
 
 import type { components } from "@amos.com/node";
 
+/**
+ * PCI-safe snapshot of card/bank form validity, posted when HTML
+ * constraint validation changes. Use this to enable or disable a host
+ * checkout button.
+ */
+export type PaymentMethodFormValidityChangeEvent = {
+  isValid: boolean;
+};
+
 /**
  * Why an interactive confirmation attempt ended with `status: "incomplete"`.
  *
@@ -593,6 +602,15 @@ export type Message =
   | {
       /** Parent → embed: clear all form field values and API errors. */
       type: "RESET_FORM";
+    }
+  | {
+      /**
+       * Embed → parent: card/bank form validity changed.
+       * `isValid` is true when all required fields are present and
+       * valid. Does not include PCI data.
+       */
+      type: "FORM_VALIDITY_CHANGE";
+      isValid: boolean;
     };
 
 /**