@moonbase.sh/storefront 2.7.0 → 2.9.0

package/README.md

@@ -99,6 +99,10 @@ Moonbase.configure({
   cart: {
     quantity: 'single',
   },
+  pricing: {
+    trailingZeros: 'always',
+    currencyDisplay: 'code',
+  },
   theme: {
     colors: {
       primary: '#E5A000',
@@ -112,8 +116,92 @@ Moonbase.configure({
 })
 ```
 
+`pricing.trailingZeros` controls how whole prices render. The default `'auto'`
+drops the decimals — a $10.00 product shows as `$10`. Set it to `'always'` to keep
+the currency's own fraction digits instead (`$10.00`, and still `¥1000` for
+zero-decimal currencies like JPY). It applies to the widget's own UI and to
+`data-moonbase-render` price elements on your page alike.
+
+`pricing.currencyDisplay` picks which marker identifies the currency. Taking $10 in
+USD read from a British locale, the default `'narrowSymbol'` renders the shortest
+symbol (`$10`), `'symbol'` the locale's usual one (`US$10`), `'code'` the ISO 4217
+code (`USD 10`), and `'name'` spells it out in the visitor's language
+(`10 US dollars`). The symbol and its placement still follow the visitor's own
+locale — this only chooses between the four forms.
+
+Both `pricing` options cover the widget's UI and your `data-moonbase-render` price
+elements. The checkout itself is rendered by Moonbase and formats its own prices.
+
+`cart.offers.cartWide` covers offers keyed off the cart as a whole, such as "10% off orders
+over $50", rather than off a single product. These apply themselves the moment the
+cart qualifies, so there is nothing for the buyer to press. While the cart is short
+of the threshold the widget shows a meter and how much further to go; once it
+qualifies, the saving appears as its own row above the total.
+
+```ts
+Moonbase.configure({
+  cart: {
+    offers: {
+      cartWide: {
+        showProgress: true,
+        savingLabel: 'You save',
+      },
+    },
+  },
+})
+```
+
+Set `showProgress` to `false` to let such an offer apply silently: the saving still
+shows in the totals, the nudge does not. With no cart-wide offer configured on your
+storefront, the meter never renders either way. `savingLabel` names the saving row
+in the cart totals.
+
 You can also control where the widget mounts by providing `target`.
 
+## Promotions
+
+When you run a sale across your catalogue, the widget surfaces it on its own — as a
+banner, a popup, or both, depending on what you asked for when you set the promotion
+up in Moonbase. Nothing to wire in: the sale appears while it is live and to the
+shoppers it applies to, and disappears when it ends.
+
+Once a shopper dismisses a promotion it stays dismissed in that browser, for as long
+as the promotion runs. Editing the campaign doesn't bring it back — a shopper who has
+turned a sale away isn't asked again. Start a new promotion to reach them again.
+
+The two surfaces are tracked separately, so closing the popup leaves the banner up as
+a reminder that the sale is still on. A popup also gets a single interaction: clicking
+through to the campaign retires it for good, the same as closing it would, since it
+interrupted the shopper to ask. A banner interrupted nobody, so clicking through leaves
+it standing — only an explicit dismissal takes it down.
+
+By default the banner pins itself to the top of the viewport. Give the widget a
+container and it renders inline in your own layout instead — anywhere on the page:
+
+```html
+<div data-moonbase-promotion></div>
+```
+
+```ts
+Moonbase.configure({
+  promotions: {
+    // Set to false to render sales yourself.
+    enabled: true,
+    // 'top' | 'bottom' — only used when the page offers no container.
+    location: 'top',
+    dismissLabel: 'Dismiss',
+  },
+})
+```
+
+Where a sale leads, and the wording on the link, both come from the promotion itself —
+only the merchant running the campaign knows what it is offering. A sale with no
+destination set shows the dismiss action as its only button.
+
+To render sales entirely yourself, turn the built-in surfaces off and listen for
+`promotion-shown`, or read them from the `usePromotions()` composable in
+`@moonbase.sh/vue`.
+
 ## Events
 
 Subscribe to widget lifecycle events with `Moonbase.on(...)`.
@@ -124,6 +212,9 @@ Available events include:
 - `signed-up`
 - `signed-out`
 - `storefront-updated`
+- `promotion-shown`
+- `promotion-clicked`
+- `promotion-dismissed`
 - `redeemed-voucher`
 - `downloaded-product`
 - `activated-product`

package/dist/moonbase.d.ts

@@ -9,9 +9,19 @@ import { Order } from '@moonbase.sh/vue';
 import { OwnedProduct } from '@moonbase.sh/vue';
 import { Storefront } from '@moonbase.sh/vue';
 import { StorefrontProduct } from '@moonbase.sh/vue';
+import { StorefrontPromotion } from '@moonbase.sh/vue';
 import { User } from '@moonbase.sh/vue';
 import { Voucher } from '@moonbase.sh/vue';
 
+/**
+ * Which marker identifies the currency, for `10` USD read in a British locale:
+ * - `'narrowSymbol'` (default) — the shortest symbol: `$10`.
+ * - `'symbol'` — the locale's usual symbol, disambiguated where it needs to be: `US$10`.
+ * - `'code'` — the ISO 4217 code: `USD 10`.
+ * - `'name'` — the currency spelled out in the visitor's language: `10 US dollars`.
+ */
+declare type CurrencyDisplay = 'narrowSymbol' | 'symbol' | 'code' | 'name';
+
 declare type DeepPartial<T> = T extends object ? {
     [P in keyof T]?: T[P] extends HTMLElement | undefined ? T[P] : DeepPartial<T[P]>;
 } : T;
@@ -57,6 +67,9 @@ export declare enum MoonbaseEvent {
     SignedOut = "signed-out",
     RedeemedVoucher = "redeemed-voucher",
     StorefrontUpdated = "storefront-updated",
+    PromotionShown = "promotion-shown",
+    PromotionClicked = "promotion-clicked",
+    PromotionDismissed = "promotion-dismissed",
     DownloadedProduct = "downloaded-product",
     ActivatedProduct = "activated-product",
     AddedToCart = "added-to-cart",
@@ -84,6 +97,23 @@ export declare interface MoonbaseEventArgs {
         storefront: Storefront;
         user?: User | null;
     };
+    [MoonbaseEvent.PromotionShown]: {
+        promotion: StorefrontPromotion;
+        surface: PromotionSurface;
+        user?: User | null;
+    };
+    [MoonbaseEvent.PromotionClicked]: {
+        promotion: StorefrontPromotion;
+        surface: PromotionSurface;
+        /** Where the shopper is being sent — the promotion's own call-to-action URL. */
+        url: string;
+        user?: User | null;
+    };
+    [MoonbaseEvent.PromotionDismissed]: {
+        promotion: StorefrontPromotion;
+        surface: PromotionSurface;
+        user?: User | null;
+    };
     [MoonbaseEvent.DownloadedProduct]: {
         product: OwnedProduct;
         download: Download;
@@ -326,6 +356,27 @@ export declare interface MoonbaseOptions {
         };
         offers: {
             label: string;
+            /**
+             * Offers keyed off the cart as a whole, such as "10% off orders over $50", rather than off a single
+             * product. They apply themselves the moment the cart qualifies; there is nothing for the buyer
+             * to press.
+             */
+            cartWide: {
+                /**
+                 * Show the eligibility meter in the cart: how close the cart is to the offer's threshold
+                 * while it is short, and the discount confirmed once it is not.
+                 *
+                 * Set to `false` to let the offer apply silently: the saving still shows in the totals, the
+                 * nudge does not. With no such offer configured the meter never renders either way.
+                 */
+                showProgress: boolean;
+                /**
+                 * Label for the saving row in the cart totals, above `Total`. Kept in the widget's own voice
+                 * rather than taking the offer's name, so the totals column can't be pushed around by
+                 * merchant-length copy.
+                 */
+                savingLabel: string;
+            };
         };
         leadMagnets: {
             quantity: 'selectable' | 'single';
@@ -339,6 +390,26 @@ export declare interface MoonbaseOptions {
             label: string;
         };
     };
+    promotions: {
+        /**
+         * Whether to render the sales a merchant is running. When a promotion is live, the widget
+         * surfaces it as a banner and/or a popup depending on what the merchant asked for. Turn this
+         * off to render the campaign yourself from `Moonbase.on('promotion-shown', …)` or the
+         * `usePromotions()` composable in `@moonbase.sh/vue`.
+         */
+        enabled: boolean;
+        /**
+         * Where the banner sits when the host page has no `[data-moonbase-promotion]` container for
+         * it. Ignored when one exists — then the banner renders inline, wherever you put it.
+         */
+        location: 'top' | 'bottom';
+        /**
+         * The label on the dismiss action, and the primary action when a sale has no destination. The
+         * wording for a sale that *does* lead somewhere comes from the promotion itself, since only
+         * the merchant knows what the campaign is offering.
+         */
+        dismissLabel: string;
+    };
     theme: {
         dark: boolean;
         colors: {
@@ -353,6 +424,29 @@ export declare interface MoonbaseOptions {
         buttons: 'outlined' | 'light';
         cards: 'outlined' | 'shadow' | 'white';
     };
+    pricing: {
+        /**
+         * How to render a price that lands on a whole number.
+         * - `'auto'` (default) drops the fraction entirely, so `10` renders `$10`.
+         * - `'always'` keeps the currency's own fraction digits, so `10` renders
+         *   `$10.00` — and still `¥1000` for zero-decimal currencies like JPY.
+         *
+         * Prices that aren't whole are unaffected; they always show their decimals.
+         */
+        trailingZeros: TrailingZeros;
+        /**
+         * Which marker identifies the currency. Taking `10` USD read in a British
+         * locale:
+         * - `'narrowSymbol'` (default) renders the shortest symbol, `$10`.
+         * - `'symbol'` renders the locale's usual symbol, `US$10`.
+         * - `'code'` renders the ISO 4217 code, `USD 10`.
+         * - `'name'` spells it out in the visitor's language, `10 US dollars`.
+         *
+         * The symbol and its placement always follow the visitor's own locale;
+         * this only picks which of the four forms to use.
+         */
+        currencyDisplay: CurrencyDisplay;
+    };
     target: HTMLElement | undefined;
     /**
      * When the host page declares a fixed-width mobile viewport (e.g. Wix's
@@ -373,10 +467,19 @@ export declare interface MoonbaseOptions {
     integrations: IntegrationsConfig;
 }
 
+/** Which surface a promotion was rendered on. */
+export declare type PromotionSurface = 'banner' | 'popup';
+
 export declare interface TikTokPixelConfig {
     pixelId: string;
 }
 
+/**
+ * How a whole-number price renders: `'auto'` drops the fraction (`$10`),
+ * `'always'` keeps the currency's own fraction digits (`$10.00`, `¥1000`).
+ */
+declare type TrailingZeros = 'auto' | 'always';
+
 export declare const urlKey: InjectionKey<string>;
 
 export { }