@moonbase.sh/storefront 3.5.0 → 3.6.1

package/README.md

@@ -169,6 +169,8 @@ five groups per request are applied, and IDs are matched lowercase.
 
 The two are unioned rather than overridden: `configure` names the lists everyone
 signing up through your site joins, the link adds whichever the campaign is for.
+A [sign-up form on your own page](#newsletter-sign-up-forms) adds to `subscribe` the
+same way, with a field named `groups`.
 `checkout` is configuration-only, because the cart outlives any one link.
 
 For somebody who already has an account, `join_group` does it as a request of its
@@ -341,6 +343,106 @@ 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`.
 
+## Newsletter sign-up forms
+
+A sign-up form on your own page, in your own design, can go straight to Moonbase. Mark it
+with `data-moonbase-form="subscribe"` and the widget sends it in the background instead of
+letting the browser load a new page:
+
+```html
+<form data-moonbase-form="subscribe">
+  <input name="name" placeholder="Name" maxlength="200">
+  <input name="email" type="email" placeholder="you@example.com" required>
+  <button>Subscribe</button>
+</form>
+```
+
+The widget reads the fields by name:
+
+| Field | |
+| --- | --- |
+| `email` | Required. |
+| `name` | Optional, up to 200 characters. |
+| `groups` | Optional group IDs, comma-separated in one field or repeated (checkboxes, say). Added to `groups.subscribe`, as `mb_groups` is on a link. |
+
+The emails signed up for are the ones `communicationPreferences.show` names, as for the
+drawer's own subscribe form, and whether the visitor has to confirm by email first is your
+account's double opt-in setting. The form is yours, so the consent wording is too: the drawer's
+form says "By subscribing you agree to receive newsletter and product update emails", and
+yours should say as much.
+
+### Showing the result
+
+By default the drawer opens on the outcome: "You're subscribed!", or "Check your email to
+finish" under double opt-in. If the server turns the email down, the drawer opens its own form,
+filled in from yours, with the reason under the button, so the visitor can correct it there.
+
+To keep everything on your page, add `data-moonbase-feedback="inline"`. The drawer then stays
+closed, and the widget reports progress on the form itself for you to style:
+
+```html
+<form class="newsletter" data-moonbase-form="subscribe" data-moonbase-feedback="inline">
+  <div class="fields">
+    <input name="email" type="email" required>
+    <button>Subscribe</button>
+  </div>
+  <p data-moonbase-message></p>
+</form>
+```
+
+| `data-moonbase-state` | When |
+| --- | --- |
+| `submitting` | The request is out. The form's submit buttons are disabled until it returns. |
+| `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. |
+
+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
+your own wording instead:
+
+```css
+.newsletter:is([data-moonbase-state="subscribed"], [data-moonbase-state="confirmation_sent"]) .fields {
+  display: none;
+}
+.newsletter[data-moonbase-state="error"] [data-moonbase-message] {
+  color: #c00;
+}
+```
+
+Style both success states. For a visitor who is not signed in, the status follows your double
+opt-in setting rather than whether the address was new, so the form cannot be used to find out
+who is subscribed already. With double opt-in on, nearly every sign-up ends in
+`confirmation_sent`.
+
+`data-moonbase-state` is set in the default mode as well, so a spinner can cover the moment
+before the drawer opens.
+
+### Reacting in code
+
+Every successful sign-up emits `subscribed`, from these forms and from the drawer's own:
+
+```ts
+Moonbase.on(MoonbaseEvent.Subscribed, ({ email, status, source }) => {
+  // source is 'form' for a data-moonbase-form form, 'drawer' for the drawer's own
+})
+```
+
+### Good to know
+
+- The attribute hands the form to Moonbase: the widget claims the submit before any other
+  script on the page sees it, so a site builder's own form handling does not post it somewhere
+  else as well. Your own submit listeners on that form do not run either; use the `subscribed`
+  event instead.
+- Loaded from the CDN, the widget holds a form submitted before it is ready and sends it once
+  `setup()` has run. Installed from npm, call `setup()` early: until then the browser submits
+  the form as a plain form.
+- A signed-in customer subscribes the address they type in, which is usually their own.
+- Forms inside a shadow root are not picked up.
+- An unknown `data-moonbase-form` value is not submitted, and logs a warning to the console.
+- To open the drawer's own form instead, filled in, call `Moonbase.subscribe({ email, name })`
+  or link to `?mb_intent=subscribe&mb_email=...&mb_name=...`.
+
 ## Events
 
 Subscribe to widget lifecycle events with `Moonbase.on(...)`.
@@ -350,6 +452,7 @@ Available events include:
 - `signed-in`
 - `signed-up`
 - `signed-out`
+- `subscribed`
 - `storefront-updated`
 - `promotion-shown`
 - `promotion-clicked`

package/dist/moonbase.d.ts

@@ -12,6 +12,7 @@ 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 { SubscribeResponse } from '@moonbase.sh/vue';
 import { TrailingZeros } from '@moonbase.sh/vue';
 import { User } from '@moonbase.sh/vue';
 import { Voucher } from '@moonbase.sh/vue';
@@ -75,6 +76,7 @@ export declare enum MoonbaseEvent {
     SignedIn = "signed-in",
     SignedUp = "signed-up",
     SignedOut = "signed-out",
+    Subscribed = "subscribed",
     RedeemedVoucher = "redeemed-voucher",
     JoinedGroup = "joined-group",
     StorefrontUpdated = "storefront-updated",
@@ -100,6 +102,23 @@ export declare interface MoonbaseEventArgs {
     [MoonbaseEvent.SignedOut]: {
         user: User;
     };
+    [MoonbaseEvent.Subscribed]: {
+        email: string;
+        name: string | null;
+        /**
+         * `confirmation_sent` when the account requires double opt-in: the visitor
+         * is only on the list once they click the link in the email that went out.
+         */
+        status: SubscribeResponse['status'];
+        /**
+         * The group IDs requested, normalized. Not necessarily the ones applied: the
+         * API skips unknown groups and groups closed to sign-ups without a word.
+         */
+        groupIds?: string[];
+        /** The drawer's own form, or a `data-moonbase-form` form on the host page. */
+        source: 'drawer' | 'form';
+        user?: User | null;
+    };
     [MoonbaseEvent.RedeemedVoucher]: {
         voucher: Voucher;
         user: User;
@@ -284,6 +303,8 @@ export declare interface MoonbaseIntentArgs {
     };
     [MoonbaseIntent.Subscribe]: {
         email?: string;
+        /** Prefills the name field. */
+        name?: string;
         /**
          * Comma-separated merchant-owned group IDs to join on subscribe, added to
          * whatever `options.groups.subscribe` already names.
@@ -393,7 +414,8 @@ export declare interface MoonbaseOptions {
      * `signUp` and `subscribe` can be added to per link with `mb_groups`, e.g.
      * `?mb_intent=sign_up&mb_groups=beta,vip`. The two are unioned: the options
      * say which lists everyone signing up through this site joins, the link adds
-     * whichever the campaign is for.
+     * whichever the campaign is for. A host-page `data-moonbase-form="subscribe"`
+     * form adds to `subscribe` the same way, with a field named `groups`.
      *
      * `checkout` is options-only. The cart outlives any one intent, and a buyer
      * pressing the drawer's own checkout button never went through a link, so a