@akinon/pz-theme 2.0.95-rc.0 → 2.0.95

package/src/blocks/auth-success-block.tsx

@@ -0,0 +1,85 @@
+'use client';
+
+import React from 'react';
+
+import { useAuthFormSuccess } from '../auth/form-success-context';
+import { getResponsiveValue, partAttrs } from '../utils';
+import { BlockRendererProps } from './block-renderer-registry';
+import { DesignerPlaceholder } from './product-block-utils';
+
+/**
+ * The confirmation the form around this block finished with.
+ *
+ * The success twin of the Form Error block, and the reason it exists is the
+ * same complaint: "the success message is not something I can manage". It was
+ * a node the form drew itself, reachable only as a style part — a brand could
+ * recolour "a reset link is on its way" and could not put an icon beside it, a
+ * heading above it, or the sentence anywhere other than where the form chose.
+ *
+ * As a block it is ordinary content, so everything a design wants AROUND the
+ * confirmation is an ordinary sibling. Placing it also keeps the composition on
+ * screen in the forms whose success state would otherwise replace it — which is
+ * the point: a block inside a form that has been swapped out draws nothing.
+ * When the whole screen should change instead, the form's Step After Success is
+ * still the tool for that, and it needs no block at all.
+ *
+ * Empty until the form has finished, so a shopper never sees a reserved gap. In
+ * the canvas it draws `previewMessage` instead, so the state can be dressed
+ * without having to reach it for real.
+ *
+ * Properties: previewMessage.
+ * Parts: root.
+ */
+const AuthSuccessBlock = ({
+  block,
+  isDesigner = false,
+  currentBreakpoint = 'desktop'
+}: BlockRendererProps) => {
+  const message = useAuthFormSuccess();
+
+  const previewMessage = String(
+    getResponsiveValue(
+      block.properties?.previewMessage,
+      currentBreakpoint,
+      'Done. Check your inbox.'
+    )
+  ).trim();
+
+  // The canvas shows the state being styled; a storefront shows nothing until
+  // the form has actually finished. An author who empties the preview text gets
+  // the placeholder rather than an invisible block they cannot select.
+  const shown = message || (isDesigner ? previewMessage : '');
+
+  if (!shown) {
+    if (!isDesigner) return null;
+
+    return (
+      <DesignerPlaceholder label="Form success (shown once the form finishes)" />
+    );
+  }
+
+  return (
+    <div
+      data-auth-success=""
+      // Fills its block wrapper; see the note in auth-step-block.tsx.
+      className="w-full"
+      // Only the live message is announced. `role="status"` on the canvas
+      // preview would have a designer's screen reader read a confirmation for
+      // something that has not happened.
+      role={message ? 'status' : undefined}
+      data-auth-success-state={message ? 'success' : 'preview'}
+      {...partAttrs('root')}
+      // No inline colour, unlike its error twin: that block sets one because
+      // the auth forms paint their message through a variable a brand may
+      // already have set, while a confirmation has never had a colour of its
+      // own. So this line inherits the composition's text colour, and the
+      // block's own Text Color — emitted `!important` as every part style is —
+      // is what overrides it.
+      style={{ margin: 0 }}
+    >
+      {shown}
+    </div>
+  );
+};
+
+export default AuthSuccessBlock;

package/src/blocks/block-renderer-registry.tsx

@@ -79,10 +79,14 @@ import AuthFlowBlock from './auth-flow-block';
 import AuthStepBlock from './auth-step-block';
 import AuthStepTitleBlock from './auth-step-title-block';
 import AuthErrorBlock from './auth-error-block';
+import AuthSuccessBlock from './auth-success-block';
+import FormStateBlock from './form-state-block';
 import AuthConsentBlock from './auth-consent-block';
 import AuthFieldBlock from './auth-field-block';
 import OtpPhaseBlock from './otp-phase-block';
 import OtpCodeInputBlock from './otp-code-input-block';
+import CaptchaBlock from './captcha-block';
+import ResetPasswordBlock from './reset-password-block';
 import StoreLocatorBlock from './store-locator-block';
 import FaqAccordionBlock from './faq-accordion-block';
 import ShareBlock from './share-block';
@@ -224,10 +228,14 @@ blockRendererRegistry.register('auth-flow', AuthFlowBlock);
 blockRendererRegistry.register('auth-step', AuthStepBlock);
 blockRendererRegistry.register('auth-step-title', AuthStepTitleBlock);
 blockRendererRegistry.register('auth-error', AuthErrorBlock);
+blockRendererRegistry.register('auth-success', AuthSuccessBlock);
+blockRendererRegistry.register('form-state', FormStateBlock);
 blockRendererRegistry.register('auth-consent', AuthConsentBlock);
 blockRendererRegistry.register('auth-field', AuthFieldBlock);
 blockRendererRegistry.register('otp-phase', OtpPhaseBlock);
 blockRendererRegistry.register('otp-code-input', OtpCodeInputBlock);
+blockRendererRegistry.register('captcha', CaptchaBlock);
+blockRendererRegistry.register('reset-password', ResetPasswordBlock);
 blockRendererRegistry.register('store-locator', StoreLocatorBlock);
 blockRendererRegistry.register('faq-accordion', FaqAccordionBlock);
 blockRendererRegistry.register('share', ShareBlock);

package/src/blocks/button-block.tsx

@@ -87,8 +87,29 @@ const ButtonBlock = ({
     return 'Click Me';
   };
 
+  const submitFormId = String(
+    getResponsiveValue(block.properties?.submitFormId, currentBreakpoint, '')
+  ).trim();
+  /**
+   * A detached CTA is a real submit button and has to behave like one while the
+   * form it drives is working: staying bright and clickable through a request
+   * is what makes a shopper press it twice. An empty id costs no subscription,
+   * so this is safe to read unconditionally — as a hook must be.
+   */
+  const isSubmittedFormBusy = useFormSubmitState(submitFormId);
+
   const textValue = block.properties?.text || block.value;
-  const text = getLocalizedText(textValue);
+  /**
+   * What the caption says while the form this button drives is working.
+   *
+   * Empty keeps the caption put, which is what every published button does —
+   * the same absence-preserving default the forms' own `busyLabel` carries.
+   */
+  const busyTextValue = block.properties?.busyText;
+  const text =
+    isSubmittedFormBusy && busyTextValue
+      ? getLocalizedText(busyTextValue)
+      : getLocalizedText(textValue);
 
   const url = block.properties?.url
     ? String(getResponsiveValue(block.properties.url, currentBreakpoint, '#'))
@@ -133,16 +154,6 @@ const ButtonBlock = ({
    * live in a pinned bottom bar while the fields stay in the flow above.
    * Forces the <button> branch: an anchor cannot submit anything.
    */
-  const submitFormId = String(
-    getResponsiveValue(block.properties?.submitFormId, currentBreakpoint, '')
-  ).trim();
-  /**
-   * A detached CTA is a real submit button and has to behave like one while the
-   * form it drives is working: staying bright and clickable through a request
-   * is what makes a shopper press it twice. An empty id costs no subscription,
-   * so this is safe to read unconditionally — as a hook must be.
-   */
-  const isSubmittedFormBusy = useFormSubmitState(submitFormId);
 
   const iconUrl = block.properties?.icon
     ? String(getResponsiveValue(block.properties.icon, currentBreakpoint, ''))
@@ -660,8 +671,27 @@ const ButtonBlock = ({
           // root styles HERE instead of onto the designer wrapper, so padding
           // and border land once, on the element the shopper actually clicks —
           // not once on the wrapper and again inline (which doubled them).
-          {...partAttrs('root')}
-          style={finalStyles}
+          //
+          // The states travel with it: `disabled` alone changed nothing a
+          // shopper could see, because an authored background and colour
+          // override what a browser paints on a disabled button — so a
+          // detached CTA stayed bright and clickable-looking through the whole
+          // request, which is exactly what makes someone press it twice.
+          {...partAttrs('root', {
+            loading: isSubmittedFormBusy,
+            disabled: isSubmittedFormBusy
+          })}
+          style={
+            isSubmittedFormBusy
+              ? {
+                  ...finalStyles,
+                  // A default a designer does not have to author, and the same
+                  // one the forms' own submit buttons use.
+                  opacity: 0.7,
+                  cursor: 'not-allowed'
+                }
+              : finalStyles
+          }
           onClick={handleClick}
           {...action.ariaProps}
         >

package/src/blocks/captcha-block.tsx

@@ -0,0 +1,61 @@
+'use client';
+
+import React from 'react';
+import { getResponsiveValue, partAttrs } from '../utils';
+import { useAuthCaptcha } from '../auth/auth-captcha';
+import { DesignerPlaceholder } from './product-block-utils';
+import { BlockRendererProps } from './block-renderer-registry';
+
+/**
+ * Where the security check appears inside an auth form.
+ *
+ * The challenge itself is not a design decision — commerce decides when to
+ * escalate, and the widget is Google's — but WHERE it lands is: above the
+ * submit, under the password, inside the drawer's scrolling area rather than
+ * behind its bottom bar. So it is a block, and the form it sits in offers the
+ * widget through `auth/auth-captcha.tsx`.
+ *
+ * Renders nothing at all until there is something to render: the form has
+ * `showCaptcha` off, or commerce has not escalated. That is what lets a
+ * designer place it once and forget it, instead of composing a second version
+ * of the form for the abuse-protected case.
+ *
+ * Properties: label. Parts: captcha.
+ */
+const CaptchaBlock = ({
+  block,
+  currentBreakpoint = 'desktop',
+  isDesigner = false
+}: BlockRendererProps) => {
+  const captcha = useAuthCaptcha();
+
+  const label = String(
+    getResponsiveValue(
+      block.properties?.label,
+      currentBreakpoint,
+      'Security check'
+    )
+  );
+
+  /**
+   * In the canvas it is a marker rather than a live widget. Two reasons, and
+   * the first is enough on its own: rendering reCAPTCHA into an editor iframe
+   * asks Google for a token against the wrong origin. The second is that a
+   * designer has to be able to SEE and select a block whose whole point is to
+   * be invisible most of the time.
+   */
+  if (isDesigner) {
+    return <DesignerPlaceholder label={label} attribute="data-auth-captcha" />;
+  }
+
+  // No form is offering a challenge — see the note above.
+  if (!captcha) return null;
+
+  return (
+    <div {...partAttrs('captcha')} data-auth-captcha="">
+      <captcha.View />
+    </div>
+  );
+};
+
+export default CaptchaBlock;

package/src/blocks/change-password-form-block.tsx

@@ -3,6 +3,7 @@
 import React, { useState } from 'react';
 import { useUpdatePasswordMutation } from '@akinon/next/data/client/account';
 import { getResponsiveValue, partAttrs } from '../utils';
+import { useHostModalCloser } from '../overlays/modal-host-context';
 import { BlockRendererProps } from './block-renderer-registry';
 import { readToggle } from './product-block-utils';
 
@@ -63,6 +64,19 @@ const ChangePasswordFormBlock = ({
       getResponsiveValue(block.properties?.[key], currentBreakpoint, fallback)
     );
 
+  /**
+   * Whether finishing closes the modal this block is inside. OFF by default
+   * here, because this block's success state is something the shopper is meant
+   * to read — see `useHostModalCloser`.
+   */
+  const closeHostModalOnSuccess = readToggle(
+    block.properties?.closeHostModalOnSuccess,
+    currentBreakpoint,
+    false
+  );
+  const closeHostModal = useHostModalCloser(closeHostModalOnSuccess);
+
+
   const submitLabel = text('submitLabel', 'Change password');
   const submitAlign = text('submitAlign', 'stretch');
   const currentPasswordLabel = text('currentPasswordLabel', 'Current password');
@@ -125,6 +139,7 @@ const ChangePasswordFormBlock = ({
       await updatePassword(values).unwrap();
       setValues(EMPTY_FORM);
       setIsDone(true);
+      closeHostModal();
     } catch (requestError) {
       setError(readPasswordError(requestError, errorMessage));
     }

package/src/blocks/forgot-password-block.tsx

@@ -8,12 +8,28 @@ import {
   AuthFieldErrors,
   AuthFieldErrorsProvider,
   clearAuthFieldError,
-  collectAuthFieldErrors
+  collectAuthFieldErrors,
+  focusFirstAuthFieldError
 } from '../auth/auth-field-errors';
+import {
+  authFormMessage,
+  readCommerceError,
+  splitByKnownFields
+} from '../auth/read-auth-error';
 import {
   AuthFormErrorProvider,
   containsAuthErrorBlock
 } from '../auth/form-error-context';
+import {
+  AuthFormSuccessProvider,
+  containsAuthSuccessBlock
+} from '../auth/form-success-context';
+import {
+  AuthFormStateProvider,
+  AuthFormStateValue,
+  containsFormStateBlock,
+  showsInFormState
+} from '../auth/form-state-context';
 import {
   clearFormSubmitState,
   publishFormSubmitState
@@ -24,8 +40,17 @@ import {
   setAuthStep
 } from '../auth/auth-flow-bus';
 import { renderComposedChildren } from './render-composed-children';
+import { useHostModalCloser } from '../overlays/modal-host-context';
 import { BlockRendererProps } from './block-renderer-registry';
 
+/**
+ * The only name this form submits under, and therefore the only one a
+ * field-level refusal can be hung on. Named as well as measured, because a
+ * composition whose CTA is a detached Button still has to attribute
+ * "no account with this address" to the address field.
+ */
+const FORGOT_PASSWORD_FIELD_NAMES = ['email'] as const;
+
 /**
  * Functional auth block: e-mail input that triggers the password reset mail
  * through the v1 `forgotPassword` mutation. Behaviour is fixed (commerce sends
@@ -58,6 +83,19 @@ const ForgotPasswordBlock = ({
       getResponsiveValue(block.properties?.[key], currentBreakpoint, fallback)
     );
 
+  /**
+   * Whether finishing closes the modal this block is inside. OFF by default
+   * here, because this block's success state is something the shopper is meant
+   * to read — see `useHostModalCloser`.
+   */
+  const closeHostModalOnSuccess = readToggle(
+    block.properties?.closeHostModalOnSuccess,
+    currentBreakpoint,
+    false
+  );
+  const closeHostModal = useHostModalCloser(closeHostModalOnSuccess);
+
+
   const submitLabel = prop('submitLabel', 'Send reset link');
   // Empty on purpose: without a busy label the submit caption stays put while
   // the request runs, which is what published blocks render today.
@@ -143,6 +181,21 @@ const ForgotPasswordBlock = ({
     .filter((childBlock) => (isDesigner ? true : !childBlock.hidden))
     .sort((a, b) => (a.order || 0) - (b.order || 0));
   const isComposed = childBlocks.length > 0;
+  /**
+   * Whether the composition draws the confirmation itself — either with a Form
+   * Success block carrying this form's sentence, or with a whole screen scoped
+   * to the success state in a Form State container.
+   *
+   * Two things follow: the built-in success copy stands down, and the form is
+   * NOT replaced by it — a block inside a form that has been swapped out is
+   * unmounted and would draw nothing at all, which is the whole reason the
+   * confirmation was unmanageable in the first place.
+   */
+  const successScreenIsComposed =
+    isComposed && containsFormStateBlock(childBlocks, 'success', currentBreakpoint);
+  const successIsAuthored =
+    successScreenIsComposed ||
+    (isComposed && containsAuthSuccessBlock(childBlocks));
 
   const [email, setEmail] = useState('');
   const [error, setError] = useState('');
@@ -185,10 +238,14 @@ const ForgotPasswordBlock = ({
     // Submitting inside the designer would send a real reset mail.
     if (isDesigner || isLoading) return;
 
+    // Held onto because `currentTarget` is only the form for as long as the
+    // handler runs, and the refusal is read after an await.
+    const formElement = event.currentTarget;
+
     // The form carries `noValidate`, so this is what stops an empty submit —
     // and it says so under the field rather than in a browser bubble.
     const { errors: nextFieldErrors, firstInvalid } = collectAuthFieldErrors(
-      event.currentTarget,
+      formElement,
       { required: requiredMessage, invalid: invalidMessage }
     );
 
@@ -204,7 +261,7 @@ const ForgotPasswordBlock = ({
     // form the way every other composed auth form reads its fields, rather
     // than from state no child writes to.
     const address = isComposed
-      ? String(new FormData(event.currentTarget).get('email') ?? '').trim()
+      ? String(new FormData(formElement).get('email') ?? '').trim()
       : email;
 
     try {
@@ -216,8 +273,28 @@ const ForgotPasswordBlock = ({
       if (successStep) {
         setAuthStep(successStep.flowId, successStep.stepKey);
       }
-    } catch {
-      setError(errorLabel);
+
+      // Contradictory on purpose-tolerant: a composition that names a success
+      // STEP and also asks to close gets the close, because a step inside a
+      // closed drawer is moot. Off by default — "check your inbox" is the
+      // point of this form's success state.
+      closeHostModal();
+    } catch (rejection) {
+      /**
+       * What commerce actually said, rather than "could not send" over a rate
+       * limit the shopper cannot see. RTK Query puts the body on `data`; a
+       * message naming the address goes under the field, which is where the
+       * shopper is looking, and anything form-level stays above it.
+       */
+      const reading = splitByKnownFields(
+        readCommerceError((rejection as { data?: unknown })?.data),
+        formElement,
+        FORGOT_PASSWORD_FIELD_NAMES
+      );
+
+      setFieldErrors((current) => ({ ...current, ...reading.fieldMessages }));
+      focusFirstAuthFieldError(formElement, reading.fieldMessages);
+      setError(authFormMessage(reading, errorLabel));
     }
   };
 
@@ -249,9 +326,26 @@ const ForgotPasswordBlock = ({
     </button>
   ) : null;
 
+  /** Finished — for real on a storefront, on the toggle in the canvas. */
+  const inSuccessState =
+    (isSuccess && !isDesigner) || (isDesigner && previewSuccess);
+
+  /**
+   * What the composition's Form State containers read. `busy` and `hasError`
+   * sit beside the screen rather than replacing it, so a refusal does not take
+   * the fields away with it — see `auth/form-state-context.tsx`.
+   */
+  const formStateValue: AuthFormStateValue = {
+    screen: inSuccessState ? 'success' : 'form',
+    busy: isLoading,
+    hasError: Boolean(error)
+  };
+
   // The success copy replaces the form so the shopper is not invited to submit
   // the same address twice; the root attribute is kept so styling still applies.
-  if ((isSuccess && !isDesigner) || (isDesigner && previewSuccess)) {
+  // A composition that placed a Form Success block keeps its own layout
+  // instead — see `successIsAuthored`.
+  if (inSuccessState && !successIsAuthored) {
     return (
       <div
         data-forgot-password=""
@@ -279,6 +373,10 @@ const ForgotPasswordBlock = ({
 
     return (
       <AuthFormErrorProvider value={error}>
+        {/* The confirmation, for the block the composition placed for it. Empty
+            until the mail is away, so the block draws nothing before then. */}
+        <AuthFormSuccessProvider value={inSuccessState ? successLabel : ''}>
+        <AuthFormStateProvider value={formStateValue}>
         <AuthFieldErrorsProvider value={fieldErrors}>
           <form
             id={formHtmlId || undefined}
@@ -286,7 +384,9 @@ const ForgotPasswordBlock = ({
             data-forgot-password-composed=""
             // Fills its block wrapper; see the note in auth-step-block.tsx.
             className="w-full"
-            data-forgot-password-state={isLoading ? 'busy' : 'idle'}
+            data-forgot-password-state={
+              inSuccessState ? 'success' : isLoading ? 'busy' : 'idle'
+            }
             {...partAttrs('form')}
             onSubmit={submit}
             // Our own message under the field instead of the browser's bubble
@@ -301,7 +401,17 @@ const ForgotPasswordBlock = ({
             }}
           >
             {renderComposedChildren({
-              blocks: childBlocks,
+              // Only the containers this screen calls for; everything that is
+              // not a container is shared chrome and shows on all of them.
+              blocks: childBlocks.filter((childBlock) =>
+                showsInFormState({
+                  block: childBlock,
+                  state: formStateValue,
+                  isDesigner,
+                  selectedBlockId,
+                  currentBreakpoint
+                })
+              ),
               placeholderId,
               sectionId,
               isDesigner,
@@ -322,7 +432,14 @@ const ForgotPasswordBlock = ({
               </div>
             )}
 
-            {showSubmit && (
+            {/* Kept in the success state where the confirmation is only a
+                LINE — the address is still valid and the fields are still on
+                screen, so pressing it again is a RESEND, the affordance a
+                "check your inbox" screen normally wants. Dropped where a Form
+                State container owns the success screen: the fields are then
+                scoped away with it and this would be an orphan button under a
+                composition that never asked for it. */}
+            {showSubmit && !(inSuccessState && successScreenIsComposed) && (
               <button
                 type="submit"
                 data-forgot-password-submit=""
@@ -344,8 +461,14 @@ const ForgotPasswordBlock = ({
                 {isLoading && busyLabel ? busyLabel : submitLabel}
               </button>
             )}
+
+            {/* The authored way back. Not when a container owns the screen:
+                the way onward is then part of the composition. */}
+            {inSuccessState && !successScreenIsComposed && backControl}
           </form>
         </AuthFieldErrorsProvider>
+        </AuthFormStateProvider>
+        </AuthFormSuccessProvider>
       </AuthFormErrorProvider>
     );
   }

package/src/blocks/form-state-block.tsx

@@ -0,0 +1,84 @@
+'use client';
+
+import React from 'react';
+
+import { readFormStateKey } from '../auth/form-state-context';
+import { partAttrs } from '../utils';
+import { renderComposedChildren } from './render-composed-children';
+import { BlockRendererProps } from './block-renderer-registry';
+import { DesignerPlaceholder } from './product-block-utils';
+
+/**
+ * One SCREEN of a composed form, as a named wrapper whose contents are
+ * ordinary child blocks.
+ *
+ * This is what makes "the confirmation can be a line of text, or a whole
+ * component" true: the confirmation is whatever the designer puts in here — a
+ * Text block, or an icon and a heading and a Button, or the Form Success block
+ * that carries the form's own sentence. Same for the refusal, the busy moment,
+ * and the dead-link screen a password reset can land on. Before this, every
+ * state except the form itself was the form's own markup with one authored
+ * string in it.
+ *
+ * Deliberately shaped like `otp-phase` and `auth-step`, and for the same
+ * reason: the container decides NOTHING about its own visibility. The form it
+ * stands in draws the containers whose state matches — see
+ * `auth/form-state-context.tsx` — so dropped anywhere else this is just a
+ * labelled column whose children always show, which is what keeps it dressable
+ * on its own.
+ *
+ * Properties: formState.
+ * Parts: state.
+ */
+const FormStateBlock = ({
+  block,
+  placeholderId,
+  sectionId,
+  isDesigner = false,
+  selectedBlockId,
+  currentBreakpoint = 'desktop'
+}: BlockRendererProps) => {
+  const formState = readFormStateKey(block, currentBreakpoint);
+
+  const childBlocks = (block.blocks || [])
+    .filter((childBlock) => (isDesigner ? true : !childBlock.hidden))
+    .sort((a, b) => (a.order || 0) - (b.order || 0));
+
+  // An empty container draws nothing a shopper could see; in the canvas it has
+  // to say what it is waiting for, or adding one looks like nothing happened.
+  if (childBlocks.length === 0 && !isDesigner) return null;
+
+  return (
+    <div
+      data-form-state=""
+      // Fills its block wrapper; see the note in auth-step-block.tsx.
+      className="w-full"
+      data-form-state-key={formState || undefined}
+      {...partAttrs('state')}
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--form-state-gap, 12px)'
+      }}
+    >
+      {childBlocks.length === 0 ? (
+        <DesignerPlaceholder
+          label={`Form state${
+            formState ? ` · ${formState}` : ''
+          } (drop its content here)`}
+        />
+      ) : (
+        renderComposedChildren({
+          blocks: childBlocks,
+          placeholderId,
+          sectionId,
+          isDesigner,
+          selectedBlockId,
+          currentBreakpoint
+        })
+      )}
+    </div>
+  );
+};
+
+export default FormStateBlock;

package/src/blocks/newsletter-form-block.tsx

@@ -3,6 +3,8 @@
 import React, { useState } from 'react';
 import { useEmailSubscriptionMutation } from '@akinon/next/data/client/misc';
 import { getResponsiveValue, partAttrs } from '../utils';
+import { useHostModalCloser } from '../overlays/modal-host-context';
+import { readToggle } from './product-block-utils';
 import { BlockRendererProps } from './block-renderer-registry';
 
 /** The wording the block has always shipped with; every label is editable. */
@@ -37,9 +39,22 @@ const NewsletterFormBlock = ({
       currentBreakpoint,
       fallback
     );
+
     return value === undefined || value === null ? fallback : String(value);
   };
 
+  /**
+   * Whether finishing closes the modal this block is inside. OFF by default
+   * here, because this block's success state is something the shopper is meant
+   * to read — see `useHostModalCloser`.
+   */
+  const closeHostModalOnSuccess = readToggle(
+    block.properties?.closeHostModalOnSuccess,
+    currentBreakpoint,
+    false
+  );
+  const closeHostModal = useHostModalCloser(closeHostModalOnSuccess);
+
   const placeholder = prop('placeholder', 'Your email address');
   const inputLabel = prop('inputLabel', '');
   const submitLabel = prop('submitLabel', 'Subscribe');
@@ -71,6 +86,7 @@ const NewsletterFormBlock = ({
       // form itself is the consent, so it is always sent as true.
       await subscribe({ email: value, subscribe_contract: true }).unwrap();
       setStatus('success');
+      closeHostModal();
       setEmail('');
     } catch {
       setErrorKind('request');