@aglyn/plugins-commerce 1.0.0-beta.229 → 1.0.0-beta.231

package/src/lib/components/storefront-payment-appearance.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { Theme } from '@mui/material/styles';
+import type { Appearance, CssFontSource } from '@stripe/stripe-js';
+/** The families named in a CSS `font-family` value, unquoted, in order. */
+export declare function fontFamilies(fontFamily: string | undefined): string[];
+/**
+ * The stylesheet that puts the theme's own typeface inside Stripe's frames,
+ * or none when the theme uses only system fonts.
+ *
+ * The page itself self-hosts its theme fonts (AGL-3485), but those files are
+ * served from the site's origin for the site's document; Stripe's frames load
+ * fonts only from a `cssSrc` they fetch themselves. Google's CSS2 endpoint is
+ * where every theme font comes from in the first place, so the same family
+ * resolves to the same face.
+ */
+export declare function storefrontPaymentFonts(fontFamily: string | undefined): CssFontSource[];
+export declare function storefrontPaymentAppearance(theme: Theme): Appearance;

package/src/lib/components/storefront-payment-appearance.js

@@ -0,0 +1,114 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * The site theme, translated for Stripe's Appearance API (AGL-3606).
+ *
+ * Stripe draws the card, address and wallet fields in its own iframes, which
+ * inherit nothing from the page: not the palette, not the radius, not the
+ * font. Without this the in-page form is Stripe's default blue-and-grey on a
+ * storefront the merchant styled, which reads as a third party's widget
+ * rather than as their checkout.
+ *
+ * Read from the MUI theme the storefront already renders under — the site's
+ * own theme tokens — so a merchant's theme edit reaches the payment fields
+ * the same way it reaches every other block.
+ */ /**
+ * Stripe parses colors and lengths inside its iframe, where a CSS custom
+ * property from the page cannot resolve. A theme built in CSS-variables mode
+ * hands out `var(--…)` strings, and passing one through would have Stripe
+ * reject the whole appearance object; dropping that one variable keeps
+ * Stripe's default for it and everything else themed.
+ */ function usable(value) {
+    if (typeof value !== 'string') return undefined;
+    const trimmed = value.trim();
+    if (!trimmed || trimmed.includes('var(')) return undefined;
+    return trimmed;
+}
+function radius(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) return `${value}px`;
+    return usable(value);
+}
+/**
+ * Families a browser already has, or keywords that are not families at all.
+ * Asking Google Fonts for one of these is a 400 at best, so only the first
+ * family that is NOT one of them is loaded into Stripe's frames.
+ */ const LOCAL_FAMILIES = new Set([
+    'inherit',
+    'initial',
+    'sans-serif',
+    'serif',
+    'monospace',
+    'cursive',
+    'fantasy',
+    'system-ui',
+    '-apple-system',
+    'blinkmacsystemfont',
+    'segoe ui',
+    'helvetica',
+    'helvetica neue',
+    'arial',
+    'georgia',
+    'times',
+    'times new roman',
+    'courier',
+    'courier new',
+    'verdana',
+    'tahoma'
+].map((family)=>family.toLowerCase()));
+/** The families named in a CSS `font-family` value, unquoted, in order. */ export function fontFamilies(fontFamily) {
+    return String(fontFamily != null ? fontFamily : '').split(',').map((family)=>family.trim().replace(/^["']|["']$/g, '').trim()).filter(Boolean);
+}
+/**
+ * The stylesheet that puts the theme's own typeface inside Stripe's frames,
+ * or none when the theme uses only system fonts.
+ *
+ * The page itself self-hosts its theme fonts (AGL-3485), but those files are
+ * served from the site's origin for the site's document; Stripe's frames load
+ * fonts only from a `cssSrc` they fetch themselves. Google's CSS2 endpoint is
+ * where every theme font comes from in the first place, so the same family
+ * resolves to the same face.
+ */ export function storefrontPaymentFonts(fontFamily) {
+    const family = fontFamilies(fontFamily).find((name)=>!LOCAL_FAMILIES.has(name.toLowerCase()) && !name.toLowerCase().startsWith('ui-') && /^[A-Za-z0-9 ]+$/.test(name));
+    if (!family) return [];
+    return [
+        {
+            cssSrc: `https://fonts.googleapis.com/css2?family=${family.replace(/ +/g, '+')}:wght@400;500;600;700&display=swap`
+        }
+    ];
+}
+export function storefrontPaymentAppearance(theme) {
+    var _theme_palette_primary, _theme_palette, _theme_palette_background, _theme_palette1, _theme_palette_text, _theme_palette2, _theme_palette_text1, _theme_palette3, _theme_palette_error, _theme_palette4, _theme_typography, _theme_shape, _theme_palette5;
+    const variables = {};
+    const set = (key, value)=>{
+        if (value) variables[key] = value;
+    };
+    set('colorPrimary', usable((_theme_palette = theme.palette) == null ? void 0 : (_theme_palette_primary = _theme_palette.primary) == null ? void 0 : _theme_palette_primary.main));
+    set('colorBackground', usable((_theme_palette1 = theme.palette) == null ? void 0 : (_theme_palette_background = _theme_palette1.background) == null ? void 0 : _theme_palette_background.paper));
+    set('colorText', usable((_theme_palette2 = theme.palette) == null ? void 0 : (_theme_palette_text = _theme_palette2.text) == null ? void 0 : _theme_palette_text.primary));
+    set('colorTextSecondary', usable((_theme_palette3 = theme.palette) == null ? void 0 : (_theme_palette_text1 = _theme_palette3.text) == null ? void 0 : _theme_palette_text1.secondary));
+    set('colorDanger', usable((_theme_palette4 = theme.palette) == null ? void 0 : (_theme_palette_error = _theme_palette4.error) == null ? void 0 : _theme_palette_error.main));
+    set('fontFamily', usable((_theme_typography = theme.typography) == null ? void 0 : _theme_typography.fontFamily));
+    set('borderRadius', radius((_theme_shape = theme.shape) == null ? void 0 : _theme_shape.borderRadius));
+    return {
+        // `night` is Stripe's dark base. The variables above override its colors
+        // where the theme states one, so this only decides the fallbacks — the
+        // field borders and placeholder tones a theme has no token for.
+        theme: ((_theme_palette5 = theme.palette) == null ? void 0 : _theme_palette5.mode) === 'dark' ? 'night' : 'stripe',
+        variables
+    };
+}
+
+//# sourceMappingURL=storefront-payment-appearance.js.map

package/src/lib/components/storefront-payment-appearance.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/components/storefront-payment-appearance.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { Theme } from '@mui/material/styles'\nimport type { Appearance, CssFontSource } from '@stripe/stripe-js'\n\n/**\n * The site theme, translated for Stripe's Appearance API (AGL-3606).\n *\n * Stripe draws the card, address and wallet fields in its own iframes, which\n * inherit nothing from the page: not the palette, not the radius, not the\n * font. Without this the in-page form is Stripe's default blue-and-grey on a\n * storefront the merchant styled, which reads as a third party's widget\n * rather than as their checkout.\n *\n * Read from the MUI theme the storefront already renders under — the site's\n * own theme tokens — so a merchant's theme edit reaches the payment fields\n * the same way it reaches every other block.\n */\n\n/**\n * Stripe parses colors and lengths inside its iframe, where a CSS custom\n * property from the page cannot resolve. A theme built in CSS-variables mode\n * hands out `var(--…)` strings, and passing one through would have Stripe\n * reject the whole appearance object; dropping that one variable keeps\n * Stripe's default for it and everything else themed.\n */\nfunction usable(value: unknown): string | undefined {\n  if (typeof value !== 'string') return undefined\n  const trimmed = value.trim()\n  if (!trimmed || trimmed.includes('var(')) return undefined\n  return trimmed\n}\n\nfunction radius(value: unknown): string | undefined {\n  if (typeof value === 'number' && Number.isFinite(value)) return `${value}px`\n  return usable(value)\n}\n\n/**\n * Families a browser already has, or keywords that are not families at all.\n * Asking Google Fonts for one of these is a 400 at best, so only the first\n * family that is NOT one of them is loaded into Stripe's frames.\n */\nconst LOCAL_FAMILIES = new Set(\n  [\n    'inherit',\n    'initial',\n    'sans-serif',\n    'serif',\n    'monospace',\n    'cursive',\n    'fantasy',\n    'system-ui',\n    '-apple-system',\n    'blinkmacsystemfont',\n    'segoe ui',\n    'helvetica',\n    'helvetica neue',\n    'arial',\n    'georgia',\n    'times',\n    'times new roman',\n    'courier',\n    'courier new',\n    'verdana',\n    'tahoma',\n  ].map((family) => family.toLowerCase()),\n)\n\n/** The families named in a CSS `font-family` value, unquoted, in order. */\nexport function fontFamilies(fontFamily: string | undefined): string[] {\n  return String(fontFamily ?? '')\n    .split(',')\n    .map((family) => family.trim().replace(/^[\"']|[\"']$/g, '').trim())\n    .filter(Boolean)\n}\n\n/**\n * The stylesheet that puts the theme's own typeface inside Stripe's frames,\n * or none when the theme uses only system fonts.\n *\n * The page itself self-hosts its theme fonts (AGL-3485), but those files are\n * served from the site's origin for the site's document; Stripe's frames load\n * fonts only from a `cssSrc` they fetch themselves. Google's CSS2 endpoint is\n * where every theme font comes from in the first place, so the same family\n * resolves to the same face.\n */\nexport function storefrontPaymentFonts(\n  fontFamily: string | undefined,\n): CssFontSource[] {\n  const family = fontFamilies(fontFamily).find(\n    (name) =>\n      !LOCAL_FAMILIES.has(name.toLowerCase()) &&\n      !name.toLowerCase().startsWith('ui-') &&\n      /^[A-Za-z0-9 ]+$/.test(name),\n  )\n  if (!family) return []\n  return [\n    {\n      cssSrc: `https://fonts.googleapis.com/css2?family=${family.replace(/ +/g, '+')}:wght@400;500;600;700&display=swap`,\n    },\n  ]\n}\n\nexport function storefrontPaymentAppearance(theme: Theme): Appearance {\n  const variables: NonNullable<Appearance['variables']> = {}\n  const set = (key: keyof typeof variables, value: string | undefined) => {\n    if (value) (variables as Record<string, string>)[key] = value\n  }\n  set('colorPrimary', usable(theme.palette?.primary?.main))\n  set('colorBackground', usable(theme.palette?.background?.paper))\n  set('colorText', usable(theme.palette?.text?.primary))\n  set('colorTextSecondary', usable(theme.palette?.text?.secondary))\n  set('colorDanger', usable(theme.palette?.error?.main))\n  set('fontFamily', usable(theme.typography?.fontFamily))\n  set('borderRadius', radius(theme.shape?.borderRadius))\n  return {\n    // `night` is Stripe's dark base. The variables above override its colors\n    // where the theme states one, so this only decides the fallbacks — the\n    // field borders and placeholder tones a theme has no token for.\n    theme: theme.palette?.mode === 'dark' ? 'night' : 'stripe',\n    variables,\n  }\n}\n"],"names":["usable","value","undefined","trimmed","trim","includes","radius","Number","isFinite","LOCAL_FAMILIES","Set","map","family","toLowerCase","fontFamilies","fontFamily","String","split","replace","filter","Boolean","storefrontPaymentFonts","find","name","has","startsWith","test","cssSrc","storefrontPaymentAppearance","theme","variables","set","key","palette","primary","main","background","paper","text","secondary","error","typography","shape","borderRadius","mode"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAKD;;;;;;;;;;;;CAYC,GAED;;;;;;CAMC,GACD,SAASA,OAAOC,KAAc;IAC5B,IAAI,OAAOA,UAAU,UAAU,OAAOC;IACtC,MAAMC,UAAUF,MAAMG,IAAI;IAC1B,IAAI,CAACD,WAAWA,QAAQE,QAAQ,CAAC,SAAS,OAAOH;IACjD,OAAOC;AACT;AAEA,SAASG,OAAOL,KAAc;IAC5B,IAAI,OAAOA,UAAU,YAAYM,OAAOC,QAAQ,CAACP,QAAQ,OAAO,GAAGA,MAAM,EAAE,CAAC;IAC5E,OAAOD,OAAOC;AAChB;AAEA;;;;CAIC,GACD,MAAMQ,iBAAiB,IAAIC,IACzB;IACE;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;CACD,CAACC,GAAG,CAAC,CAACC,SAAWA,OAAOC,WAAW;AAGtC,yEAAyE,GACzE,OAAO,SAASC,aAAaC,UAA8B;IACzD,OAAOC,OAAOD,qBAAAA,aAAc,IACzBE,KAAK,CAAC,KACNN,GAAG,CAAC,CAACC,SAAWA,OAAOR,IAAI,GAAGc,OAAO,CAAC,gBAAgB,IAAId,IAAI,IAC9De,MAAM,CAACC;AACZ;AAEA;;;;;;;;;CASC,GACD,OAAO,SAASC,uBACdN,UAA8B;IAE9B,MAAMH,SAASE,aAAaC,YAAYO,IAAI,CAC1C,CAACC,OACC,CAACd,eAAee,GAAG,CAACD,KAAKV,WAAW,OACpC,CAACU,KAAKV,WAAW,GAAGY,UAAU,CAAC,UAC/B,kBAAkBC,IAAI,CAACH;IAE3B,IAAI,CAACX,QAAQ,OAAO,EAAE;IACtB,OAAO;QACL;YACEe,QAAQ,CAAC,yCAAyC,EAAEf,OAAOM,OAAO,CAAC,OAAO,KAAK,kCAAkC,CAAC;QACpH;KACD;AACH;AAEA,OAAO,SAASU,4BAA4BC,KAAY;QAK3BA,wBAAAA,gBACGA,2BAAAA,iBACNA,qBAAAA,iBACSA,sBAAAA,iBACPA,sBAAAA,iBACDA,mBACEA,cAKlBA;IAfT,MAAMC,YAAkD,CAAC;IACzD,MAAMC,MAAM,CAACC,KAA6B/B;QACxC,IAAIA,OAAO,AAAC6B,SAAoC,CAACE,IAAI,GAAG/B;IAC1D;IACA8B,IAAI,gBAAgB/B,QAAO6B,iBAAAA,MAAMI,OAAO,sBAAbJ,yBAAAA,eAAeK,OAAO,qBAAtBL,uBAAwBM,IAAI;IACvDJ,IAAI,mBAAmB/B,QAAO6B,kBAAAA,MAAMI,OAAO,sBAAbJ,4BAAAA,gBAAeO,UAAU,qBAAzBP,0BAA2BQ,KAAK;IAC9DN,IAAI,aAAa/B,QAAO6B,kBAAAA,MAAMI,OAAO,sBAAbJ,sBAAAA,gBAAeS,IAAI,qBAAnBT,oBAAqBK,OAAO;IACpDH,IAAI,sBAAsB/B,QAAO6B,kBAAAA,MAAMI,OAAO,sBAAbJ,uBAAAA,gBAAeS,IAAI,qBAAnBT,qBAAqBU,SAAS;IAC/DR,IAAI,eAAe/B,QAAO6B,kBAAAA,MAAMI,OAAO,sBAAbJ,uBAAAA,gBAAeW,KAAK,qBAApBX,qBAAsBM,IAAI;IACpDJ,IAAI,cAAc/B,QAAO6B,oBAAAA,MAAMY,UAAU,qBAAhBZ,kBAAkBd,UAAU;IACrDgB,IAAI,gBAAgBzB,QAAOuB,eAAAA,MAAMa,KAAK,qBAAXb,aAAac,YAAY;IACpD,OAAO;QACL,yEAAyE;QACzE,uEAAuE;QACvE,gEAAgE;QAChEd,OAAOA,EAAAA,kBAAAA,MAAMI,OAAO,qBAAbJ,gBAAee,IAAI,MAAK,SAAS,UAAU;QAClDd;IACF;AACF"}

package/src/lib/components/storefront-payment-element.d.ts

@@ -14,6 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import type { StorefrontCheckoutWallets } from '../model/commerce-payment-methods';
 /**
  * The storefront Payment Element (AGL-1944) — the shopper pays on the
  * merchant's own domain instead of being sent to `checkout.stripe.com`.
@@ -53,6 +54,43 @@
  * await, because a second `confirm()` during a challenge is exactly the
  * double-submit the server's idempotency claim exists to survive and there is
  * no reason to make it lean on that.
+ *
+ * ## Everything the hosted page collected, collected here (AGL-3606)
+ *
+ * The hosted page asked for an email, a shipping address and a shipping
+ * method, and showed a running total. A `ui_mode: 'elements'` session asks
+ * for none of that on its own — the Payment Element is only the payment
+ * method — so each is mounted here, read off the SESSION rather than off
+ * anything the storefront believes:
+ *
+ * - **Email.** A session created with `customer_email` (the cart's email
+ *   field) already has one and Stripe refuses `updateEmail` on it, so it is
+ *   shown read-only. Otherwise a required field, sent with `updateEmail`
+ *   before `confirm()` — the receipt and the order's customer both come from
+ *   it, and a sale without one is an order nobody can be told about.
+ * - **Shipping.** Only when the session carries shipping options, which the
+ *   server attaches only when the store ships to the destination. The
+ *   Shipping Address Element collects the address (and, under Stripe Tax,
+ *   is where the tax is computed from); the picker lists the session's own
+ *   options and selects through `updateShippingOption`.
+ * - **Tax address without shipping.** Left to the Payment Element, which
+ *   collects the country and postal code Stripe Tax needs when the session
+ *   has `automatic_tax` and no shipping address. A Billing Address Element
+ *   there would make `updateBillingAddress` conflict with it.
+ * - **The total.** Rendered from `session.total`, which Stripe recomputes on
+ *   every address and option change — tax and shipping included — so the
+ *   number on the button is the number charged.
+ * - **The look.** `elementsOptions.appearance` and `fonts` come from the site
+ *   theme (`storefront-payment-appearance.ts`), so Stripe's frames wear the
+ *   merchant's palette, radius and typeface.
+ *
+ * ## Expired and redirect-returned sessions
+ *
+ * A session that expired, or that cannot be loaded, offers a fresh one through
+ * `onRestart` (a NEW attempt key, so the server does not replay the dead
+ * session). A redirect-based method that fails comes back to `return_url`
+ * with the session still open; `use-checkout-return-notice.ts` reads that on
+ * the return page and says nothing was charged.
  */
 export interface StorefrontPaymentElementProps {
     /** Stripe's instruction to the browser. Not a claim that money moved. */
@@ -60,12 +98,30 @@ export interface StorefrontPaymentElementProps {
     publishableKey: string;
     /** Shown on the pay button, so the merchant's own total reads through. */
     payLabel?: string;
+    /**
+     * An email the storefront already knows but did not put on the session
+     * (it prefills the field; the shopper can still change it). A session the
+     * server created WITH an email shows that one read-only instead.
+     */
+    defaultEmail?: string;
     /** Abandon the in-page form and return to the store. */
     onCancel?: () => void;
+    /**
+     * Open a fresh session after this one expired or could not be loaded. The
+     * caller must mint a NEW attempt key first, or the server replays the dead
+     * session for the old one.
+     */
+    onRestart?: () => void;
+    /**
+     * The wallets the merchant hid (AGL-3629). Stripe cannot exclude Apple Pay,
+     * Google Pay or Link on the session, so the Payment Element is told instead.
+     * Absent means every wallet the device supports shows.
+     */
+    wallets?: StorefrontCheckoutWallets;
 }
 /** Test seam: `loadStripe` caches per key across a file's tests otherwise. */
 export declare function __resetStripePromises(): void;
-export declare function StorefrontPaymentElement({ clientSecret, publishableKey, payLabel, onCancel, }: StorefrontPaymentElementProps): import("react").JSX.Element;
+export declare function StorefrontPaymentElement({ clientSecret, publishableKey, payLabel, defaultEmail, onCancel, onRestart, wallets, }: StorefrontPaymentElementProps): import("react").JSX.Element;
 /**
  * Re-exported so the old import path still resolves, but the definition now
  * lives in its own module (AGL-2486): a fallback imported FROM the lazily