@moonbase.sh/storefront 3.13.0 → 3.14.0

package/README.md

@@ -155,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,
@@ -211,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.
@@ -336,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

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 {
     /**
@@ -508,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';
@@ -570,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: {
             /**
@@ -583,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`. */