@moonbase.sh/storefront 3.12.0 → 3.14.0

package/README.md

@@ -68,15 +68,18 @@ Hosts that ship a fixed-width legacy mobile viewport (for example Wix's classic
 
 ### Captchas
 
-A merchant can ask customers to solve a captcha before they sign up. With that turned on, the
-widget's sign-up form shows one, drawn in a frame from the store's own
-`https://<account-id>.moonbase.sh`. A site with a Content-Security-Policy only has to allow that
-address in `frame-src`, which it already needs for the checkout overlay, and nothing for the
-captcha provider itself.
+A merchant can ask customers to solve a captcha before they sign up or subscribe to the
+newsletter. With that turned on, the widget's sign-up and subscribe forms show one, drawn in a
+frame from the store's own `https://<account-id>.moonbase.sh`. A site with a
+Content-Security-Policy only has to allow that address in `frame-src`, which it already needs for
+the checkout overlay, and nothing for the captcha provider itself. A newsletter form of your own
+cannot hold the frame, so the widget draws it in the drawer instead (see
+[On a store that asks for a captcha](#on-a-store-that-asks-for-a-captcha)).
 
 Widget versions from before captchas (3.7 and earlier) cannot show one, so while captchas are on,
-signing up from a site pinned to one of those fails. Checkout is unaffected by the widget version:
-it runs in Moonbase's own checkout, which shows its own captcha.
+signing up from a site pinned to one of those fails. The same goes for newsletter sign-ups from a
+site pinned to 3.12 or earlier, which predate the captcha on them. Checkout is unaffected by the
+widget version: it runs in Moonbase's own checkout, which shows its own captcha.
 
 ## Trigger intents
 
@@ -152,6 +155,35 @@ A redirected buyer is always brought back to your page once they've paid, so
 The hosted checkout stays anonymous for the trip — it prefills from the order rather
 than signing the buyer into a Moonbase account, matching the overlay's behavior.
 
+`checkout.backdrop` sets what the overlay draws behind the checkout:
+
+```ts
+Moonbase.configure({
+  checkout: {
+    backdrop: { color: 'brand', opacity: 'strong', blur: true },
+  },
+})
+```
+
+| Part | Values |
+| --- | --- |
+| `color` | `'dark'`, `'light'`, or `'brand'`, a dark shade of your brand color. |
+| `opacity` | `'subtle'`, `'standard'` or `'strong'`: how much of your page it covers. |
+| `blur` | `true` blurs your page behind the checkout. |
+
+Leave the option out, or any part of it, and that part follows the theme in your
+Moonbase account, which draws a dark backdrop at standard opacity with no blur until
+you change it there. A later `configure` changes only the parts it names; pass
+`backdrop: null` to hand all of it back to the account's theme.
+
+The blur happens on your page itself. The checkout runs in a frame of its own and can't
+reach outside it, so the widget blurs the page behind the frame and clears it again as
+the checkout closes. The loading state shown while the checkout opens draws the same
+backdrop, taking `'brand'` from the 900 shade of `theme.colors.primary`.
+
+The popup for updating a subscription's payment method draws the same color and opacity,
+but never blurs your page.
+
 ### Customer groups
 
 If you keep customer lists in Moonbase and have opened one to public sign-ups,
@@ -208,7 +240,7 @@ success. Joining a list twice is not an error.
 | `{ family, stylesheet }` | The stylesheet you name, from wherever you host it. |
 
 The built-in families are `Inter`, `Roboto`, `EB Garamond`, `Merriweather`, `Poppins`,
-`PT Serif`, `Montserrat` and `Aleo`. Either slot accepts any of them.
+`PT Serif`, `Montserrat`, `Aleo` and `Space Mono`. Either slot accepts any of them.
 
 They are served from Moonbase's own asset host — the same origin that serves the widget
 itself, and the same payload the hosted checkout uses, so the two share a cache entry.
@@ -333,6 +365,96 @@ you pass replaces the previous one; pass `{}` to remove it. No minimum by defaul
 
 You can also control where the widget mounts by providing `target`.
 
+### Typography, spacing and buttons
+
+A few more `theme` options tune how the widget reads. Each takes one of a fixed set of
+values, and the first of each is the default, which is how the widget has always looked:
+
+| Option | Values | What it does |
+| --- | --- | --- |
+| `headingWeight` | `'standard'`, `'light'`, `'regular'`, `'medium'`, `'semibold'`, `'bold'`, `'extrabold'` | One weight for every heading, from 300 to 800. `'standard'` keeps each heading's own. |
+| `bodyWeight` | `'regular'`, `'light'` | Running text at 400 or at 300. Bold text stays bold. |
+| `headingLetterSpacing` | `'standard'`, `'tight'`, `'wide'` | Letter spacing for headings only, `-0.02em` or `0.04em`. |
+| `spacing` | `'standard'`, `'compact'`, `'relaxed'` | The room around and between blocks in the drawer, at 0.75 or 1.25 times the standard. |
+| `buttonLabels` | `'normal'`, `'uppercase'` | Button labels in capitals, a size smaller and spaced out. |
+| `colors.button` | `{ background, text, hover? }` | The fill, label and hover of primary buttons, as CSS colors. |
+
+```ts
+Moonbase.configure({
+  theme: {
+    headingWeight: 'semibold',
+    spacing: 'relaxed',
+    buttonLabels: 'uppercase',
+    colors: {
+      button: { background: '#E5A000', text: '#000000' },
+    },
+  },
+})
+```
+
+`spacing` never reaches inside a control: buttons and fields keep their height, and icons
+and text keep their size. `'relaxed'` only applies from 640px wide, so a phone keeps its
+width. Uppercase labels keep the button's height too, and subtle buttons, which read as
+links, keep their case.
+
+Without `colors.button`, primary buttons are drawn from `colors.primary` as before. Leave
+out `hover` and the widget works one out, moving the fill a tenth of the way towards white
+under a dark label or towards black under a light one, so the label never loses contrast.
+A `colors.button` you pass replaces the previous one as a whole, so give `background` and
+`text` together; pass `null` to go back to `colors.primary`.
+
+### Match your Moonbase theme
+
+The theme in your Moonbase account styles the hosted storefront and the checkout. The
+widget is styled from your own code instead, so to make it match, open Account settings >
+Storefront > Theme in Moonbase and copy the ready-made `Moonbase.configure` snippet under
+"Match your storefront widget". It is generated from your account's theme, and looks
+like this:
+
+```js
+Moonbase.configure({
+  theme: {
+    colors: {
+      primary: { 50: '#EEF2FF', 100: '#E0E7FF', /* ... */ 900: '#312E81' },
+      button: { background: '#4F46E5', text: '#FFFFFF', hover: '#4338CA' },
+    },
+    fonts: { heading: 'Montserrat', body: 'Inter' },
+    corners: 'soft',
+    buttons: 'light',
+    cards: 'outlined',
+    buttonLabels: 'normal',
+    headingWeight: 'standard',
+    bodyWeight: 'regular',
+    headingLetterSpacing: 'standard',
+    spacing: 'standard',
+  },
+  checkout: {
+    backdrop: { color: 'dark', opacity: 'standard', blur: false },
+  },
+})
+```
+
+Paste it as is, or keep only the parts you want. Each theme setting maps onto one widget
+option:
+
+| Theme setting | Widget option |
+| --- | --- |
+| Brand color, as its shades | `theme.colors.primary` |
+| Brand and contrast color, as checkout draws primary buttons | `theme.colors.button` |
+| Heading font, body font | `theme.fonts.heading`, `theme.fonts.body` |
+| Corner style | `theme.corners` |
+| Button style | `theme.buttons` |
+| Button labels | `theme.buttonLabels` |
+| Heading weight | `theme.headingWeight` |
+| Body weight | `theme.bodyWeight` |
+| Heading letter spacing | `theme.headingLetterSpacing` |
+| Spacing | `theme.spacing` |
+| Overlay checkout backdrop | `checkout.backdrop` |
+
+Change the theme later and the snippet changes with it, so copy it again. The snippet
+spells out the backdrop too, which the overlay checkout then keeps over the account's
+theme; leave `checkout.backdrop` out if you would rather it followed the theme on its own.
+
 ## Promotions
 
 When you run a sale across your catalogue, the widget surfaces it on its own — as a
@@ -426,10 +548,10 @@ closed, and the widget reports progress on the form itself for you to style:
 
 | `data-moonbase-state` | When |
 | --- | --- |
-| `submitting` | The request is out. The form's submit buttons are disabled until it returns. |
+| `submitting` | The request is out. The form's submit buttons are disabled until it returns, and on a store that asks for a captcha until the visitor has solved it. |
 | `subscribed` | The visitor is on the list. |
 | `confirmation_sent` | Double opt-in: a confirmation email went out, and the visitor is on the list once they click it. |
-| `error` | The server turned the email down, or the request failed. |
+| `error` | The server turned the email down, the request failed, or the visitor closed the captcha unsolved. |
 
 A `[data-moonbase-message]` element inside the form gets the outcome as text, worded as the
 drawer words it, and is made a live region so screen readers announce it. Leave it out to show
@@ -452,6 +574,18 @@ who is subscribed already. With double opt-in on, nearly every sign-up ends in
 `data-moonbase-state` is set in the default mode as well, so a spinner can cover the moment
 before the drawer opens.
 
+### On a store that asks for a captcha
+
+With the captcha on, the store refuses a newsletter sign-up until the visitor has solved it, and
+your form has no room for the challenge. So the drawer opens with the challenge alone, "Confirm
+you're not a robot to finish subscribing", in either mode. It usually solves itself within a
+second or two. Once it is solved, the widget sends the form again: the drawer then shows the
+outcome, or with `data-moonbase-feedback="inline"` closes, and the outcome goes on your form as
+above.
+
+If the visitor closes the drawer without solving it, nothing is sent, and the form ends in
+`error` with "Please confirm you're not a robot." Sending it again opens the challenge again.
+
 ### Reacting in code
 
 Every successful sign-up emits `subscribed`, from these forms and from the drawer's own:

package/dist/moonbase.d.ts

@@ -1,5 +1,7 @@
 import { ActivationRequestFulfillmentType } from '@moonbase.sh/vue';
 import { CartItem } from '@moonbase.sh/vue';
+import { CheckoutBackdropColor } from '@moonbase.sh/vue';
+import { CheckoutBackdropOpacity } from '@moonbase.sh/vue';
 import { CheckoutPaymentFailure } from '@moonbase.sh/vue';
 import { CheckoutRedirectMode } from '@moonbase.sh/vue';
 import { CurrencyDisplay } from '@moonbase.sh/vue';
@@ -55,7 +57,29 @@ declare const Moonbase_2: MoonbaseImpl;
 export default Moonbase_2;
 
 /** Families the widget ships with, served from Moonbase's own asset host. */
-export declare type MoonbaseBuiltInFont = 'Inter' | 'Roboto' | 'EB Garamond' | 'Merriweather' | 'Poppins' | 'PT Serif' | 'Montserrat' | 'Aleo';
+export declare type MoonbaseBuiltInFont = 'Inter' | 'Roboto' | 'EB Garamond' | 'Merriweather' | 'Poppins' | 'PT Serif' | 'Montserrat' | 'Aleo' | 'Space Mono';
+
+/** Primary button colours, as any CSS colour. */
+export declare interface MoonbaseButtonColors {
+    background: string;
+    /** The label, on `background`. */
+    text: string;
+    /**
+     * The fill on hover. Left out, it is `background` moved 10% towards white under a dark label, or
+     * towards black under a light one, so the label never loses contrast.
+     */
+    hover?: string;
+}
+
+/** What the popup checkout draws behind it. A part left out follows the account's theme in Moonbase. */
+export declare interface MoonbaseCheckoutBackdrop {
+    /** `'dark'`, `'light'`, or `'brand'`: a tint of the darkest shade of the brand colour. */
+    color?: CheckoutBackdropColor;
+    /** How much of the page shows through: `'subtle'` (50% cover), `'standard'` (75%) or `'strong'` (90%). */
+    opacity?: CheckoutBackdropOpacity;
+    /** Blur the page behind the checkout. */
+    blur?: boolean;
+}
 
 export declare interface MoonbaseCustomFont {
     /**
@@ -429,6 +453,13 @@ export declare interface MoonbaseIntentArgs {
         quantity?: number;
         offer_id?: string;
         show_cart?: boolean;
+        /**
+         * The customer's license this purchase upgrades or renews, for a product whose licenses cover
+         * only some releases. Buying it extends that license instead of issuing another, at the price
+         * the storefront quotes for that license. Each license is a cart line of its own, always one
+         * unit. Products only. Left out, the purchase issues a new license.
+         */
+        license_id?: string;
     };
     [MoonbaseIntent.Purchase]: {
         product_id?: string;
@@ -436,12 +467,16 @@ export declare interface MoonbaseIntentArgs {
         variation_id?: string;
         quantity?: number;
         coupon_code?: string;
+        /** The customer's license this purchase upgrades or renews, always one unit. Products only. */
+        license_id?: string;
     } | {
         product_id?: string;
         bundle_id?: string;
         variation_id?: string;
         quantity?: number;
         coupon_code?: string;
+        /** The customer's license this purchase upgrades or renews, always one unit. Products only. */
+        license_id?: string;
     }[];
     [MoonbaseIntent.Checkout]: {
         complete?: boolean;
@@ -497,6 +532,12 @@ export declare interface MoonbaseOptions {
          * - `'never'` / `false`: always the overlay, which can't offer Apple Pay or Google Pay.
          */
         redirect: boolean | CheckoutRedirectMode;
+        /**
+         * What the popup checkout draws behind it, e.g. `{ color: 'brand', opacity: 'strong', blur: true }`.
+         * Left out, and for any part left out, the account's theme in Moonbase decides. Parts merge one at
+         * a time across `configure()` calls; pass `null` to hand all of it back to the theme.
+         */
+        backdrop?: MoonbaseCheckoutBackdrop | null;
     };
     cart: {
         quantity: 'selectable' | 'single';
@@ -559,6 +600,12 @@ export declare interface MoonbaseOptions {
         colors: {
             primary: Record<number, string> | string;
             background: 'white' | 'gray';
+            /**
+             * The fill, label and hover of primary buttons, e.g. `{ background: '#E5A000', text: '#000000' }`.
+             * Left out, primary buttons are drawn from `primary` as before. Replaced as a whole by each
+             * `configure()` that names it; pass `null` to go back to `primary`.
+             */
+            button?: MoonbaseButtonColors | null;
         };
         fonts: {
             /**
@@ -572,6 +619,27 @@ export declare interface MoonbaseOptions {
         corners: 'sharp' | 'soft' | 'round';
         buttons: 'outlined' | 'light';
         cards: 'outlined' | 'shadow' | 'white';
+        /**
+         * `'uppercase'` sets button labels in capitals: a size smaller, bold and spaced out, at the same
+         * button height. Subtle, link-like buttons keep their case. `'normal'` (default) leaves them as
+         * written.
+         */
+        buttonLabels: 'normal' | 'uppercase';
+        /**
+         * One weight for every heading: 300, 400, 500, 600, 700 or 800. `'standard'` (default) keeps each
+         * heading's own, which differ by level.
+         */
+        headingWeight: 'standard' | 'light' | 'regular' | 'medium' | 'semibold' | 'bold' | 'extrabold';
+        /** `'light'` sets running text at 300 rather than the default `'regular'` 400. Bold text stays bold. */
+        bodyWeight: 'regular' | 'light';
+        /** Letter spacing for headings: `'tight'` `-0.02em`, `'wide'` `0.04em`. `'standard'` (default) keeps each heading's own. */
+        headingLetterSpacing: 'standard' | 'tight' | 'wide';
+        /**
+         * The room around and between blocks in the drawer: `'compact'` is three quarters of the
+         * default, `'relaxed'` a quarter more from 640px wide (and the default below, so a phone keeps its
+         * width). Buttons, fields, icons and text keep their size either way.
+         */
+        spacing: 'standard' | 'compact' | 'relaxed';
     };
     pricing: {
         /** Whole prices: `'auto'` (default) shows `$10`, `'always'` shows `$10.00`. */