@moonbase.sh/storefront 3.13.0 → 3.15.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
@@ -643,6 +762,21 @@ onConsentGranted(() => Moonbase.configure({ integrations: { metaPixel: { pixelId
 Moonbase.configure({ integrations: { metaPixel: undefined } })
 ```
 
+### Attribution
+
+The widget reads how a visitor arrived: the UTM tags and the referring site, and the ad click IDs Google Ads, Meta, Microsoft Advertising and TikTok add to their links (`gclid`, `gbraid`, `wbraid`, `fbclid`, `msclkid`, `ttclid`). It sends them with the cart, checkout and sign-up, so campaign revenue, UTM-targeted prices and traffic types work.
+
+A click ID identifies the visitor's click, so the widget keeps one, and records the arrival on a cart as the page loads (so a visitor who comes back later to buy is still put down to it), only with the visitor's consent to marketing cookies. Without it, it keeps only which platform the click came from, and the arrival for the tab only.
+
+Until your page says anything, the widget follows the store's setting in Moonbase, Account settings > Storefront > "Features" > "Ad and campaign tracking": "Ask where the law requires it" tracks visitors outside the EEA, the United Kingdom and Switzerland (by where Moonbase locates the visit) and waits for consent elsewhere, "Only with cookie consent" always waits, and "Always" never asks. Whatever your cookie banner reports wins over the setting:
+
+```ts
+onConsentGranted(() => Moonbase.configure({ attribution: { consent: true } }))
+onConsentWithdrawn(() => Moonbase.configure({ attribution: { consent: false } }))
+```
+
+Whether a setting fits your business is for your own legal advice; a business based in the EU may owe consent to every visitor.
+
 ### Identity
 
 `signed-in` / `signed-up` forward an identify call when an email/id is available (Meta advanced match, GA4 `user_id`, Klaviyo identify, TikTok identify). On `signed-out`, Moonbase clears what each SDK supports (GA4 `user_id` is reset, GTM gets a `logout` push); Meta, TikTok, and Klaviyo expose no per-user logout, so their profiles persist for the session.

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`. */
@@ -598,6 +655,18 @@ export declare interface MoonbaseOptions {
      * `dataLayer`, `klaviyo`, `ttq`). Pass a provider's config to turn it on.
      */
     integrations: IntegrationsConfig;
+    attribution: {
+        /**
+         * Whether the visitor has agreed to marketing cookies, the category your cookie banner files
+         * ad tracking under. `true` keeps the ad click IDs (`gclid`, `fbclid` and the rest) and
+         * remembers the arrival beyond the visit; `false` records only the UTM tags, referring site
+         * and the ad platform a click came from, for the visit. Left out (the default), the widget
+         * follows the store's setting in Moonbase (Account settings > Storefront > "Features"):
+         * always, per country, or only with cookie consent. Set it with `Moonbase.configure()` when
+         * the banner reports the visitor's choice.
+         */
+        consent: boolean | undefined;
+    };
 }
 
 /** Which surface a promotion was rendered on. */