@akinon/pz-theme 2.0.83-rc.0 → 2.0.84-beta.0

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

@@ -0,0 +1,1092 @@
+'use client';
+
+import React, { useContext, useEffect, useRef, useState } from 'react';
+import { useRouter } from 'next/navigation';
+import { signIn } from 'next-auth/react';
+import { useLocalization } from '@akinon/next/hooks';
+import { useOtpLoginMutation } from '@akinon/next/data/client/user';
+import { getResponsiveValue, partAttrs, resolveOption } from '../utils';
+import { readToggle } from './product-block-utils';
+import { closeAllModals } from '../overlays/overlay-bus';
+import {
+  AuthFlowIdContext,
+  clearPendingOtp,
+  ownsPendingOtp,
+  setPendingOtp,
+  usePendingOtp
+} from '../auth/auth-flow-bus';
+import {
+  AuthFieldErrors,
+  AuthFieldErrorsProvider,
+  clearAuthFieldError,
+  collectAuthFieldErrors
+} from '../auth/auth-field-errors';
+import {
+  AuthFormErrorProvider,
+  containsAuthErrorBlock
+} from '../auth/form-error-context';
+import {
+  clearFormSubmitState,
+  publishFormSubmitState
+} from '../auth/form-submit-bus';
+import { OtpFormApi, OtpFormProvider } from '../auth/otp-form-context';
+import { renderComposedChildren } from './render-composed-children';
+import { BlockRendererProps } from './block-renderer-registry';
+
+/**
+ * pz brands serialise an AuthError[] into next-auth's `error` string, but a
+ * plain string is also possible, so both shapes are handled. Kept local rather
+ * than imported from auth-form-block, for the same reason register-form keeps
+ * its own copy: exporting it would change a shipped module's public surface.
+ */
+const readAuthError = (error: string | null | undefined): string => {
+  if (!error) return '';
+
+  try {
+    const parsed = JSON.parse(error);
+    if (!Array.isArray(parsed)) return String(error);
+
+    const messages: string[] = [];
+
+    parsed.forEach((entry) => {
+      const data = (entry as { data?: unknown })?.data;
+
+      if (Array.isArray(data)) {
+        data.forEach((item) => {
+          if (typeof item === 'string') {
+            messages.push(item);
+          } else if (item && typeof item === 'object') {
+            const value = (item as { value?: unknown }).value;
+            if (typeof value === 'string') messages.push(value);
+          }
+        });
+      } else if (typeof data === 'string') {
+        messages.push(data);
+      }
+    });
+
+    return messages.join(' ') || String(error);
+  } catch {
+    return String(error);
+  }
+};
+
+/**
+ * Where the serialised AuthError[] actually lives depends on the next-auth
+ * major. v4 puts it into `error` itself; v5 keeps `error` at the generic
+ * "CredentialsSignin" enum name and moves the serialised array onto `code` —
+ * which is also what the brands' own views read. Preferring `code` shows the
+ * shopper the real commerce message on v5 storefronts instead of the enum.
+ */
+const signInErrorDetail = (
+  response: { error?: string | null; code?: string | null } | null | undefined
+): string | null | undefined => response?.code || response?.error;
+
+/**
+ * Whether commerce answered with another SMS-verification challenge — which is
+ * what a RESEND of a parked registration is supposed to get back, as opposed to
+ * the refusals (a rate limit, an expired attempt) that must reach the shopper.
+ * Kept local for the same reason `readAuthError` is: exporting register-form's
+ * copy would change a shipped module's public surface.
+ */
+const hasOtpChallenge = (error: string | null | undefined): boolean => {
+  if (!error) return false;
+
+  try {
+    const parsed = JSON.parse(error);
+
+    return (
+      Array.isArray(parsed) &&
+      parsed.some((entry) => (entry as { type?: unknown })?.type === 'otp')
+    );
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * The OTP endpoint answers a successful send with 2xx and an EMPTY body, which
+ * RTK Query rejects as a parse failure. Brands treat that rejection as the
+ * success it is, and so does this block.
+ */
+const isEmptyBodySuccess = (error: unknown): boolean => {
+  const shaped = error as { status?: unknown; originalStatus?: unknown };
+
+  return (
+    shaped?.status === 'PARSING_ERROR' &&
+    typeof shaped.originalStatus === 'number' &&
+    shaped.originalStatus >= 200 &&
+    shaped.originalStatus < 300
+  );
+};
+
+type OtpPhase = 'phone' | 'code';
+
+type PreviewPhase = 'auto' | OtpPhase;
+
+const PREVIEW_PHASES: PreviewPhase[] = ['auto', 'phone', 'code'];
+
+/**
+ * Functional auth block: SMS verification as a step of its own.
+ *
+ * Two phases in one block. The PHONE phase collects a number and asks
+ * commerce for a code (`/users/otp-login/`) — that alone is the "log in with
+ * your phone" journey. The CODE phase renders the code boxes, a countdown, a
+ * resend control and the verify submit. Which sign-in the code completes
+ * comes from the auth bus: a `register` context re-submits the registration
+ * the register form parked there (same payload, now with `code`), anything
+ * else signs in through the OTP credentials path (`formType: 'otpLogin'`),
+ * exactly as brand storefronts do.
+ *
+ * Because the pending context is module state, the block works from anywhere:
+ * the step after a register form, a drawer of its own, or standalone with
+ * `collectPhone` on. Without a phone phase and with nothing pending there is
+ * nothing to verify, so on the storefront the block renders nothing at all.
+ *
+ * Properties: collectPhone, showLabels, phoneLabel, phonePlaceholder,
+ * phoneDescription, sendLabel, sendBusyLabel, sendErrorLabel,
+ * codeDescription, codeLength, timerSeconds, showCountdown, resendLabel,
+ * verifyLabel, verifyBusyLabel, changeLabel, providerId, otpFormType,
+ * callbackUrl, errorLabel, closeModalsOnSuccess, previewPhase.
+ * Parts: form, description, field, label, input, code, code-input, countdown,
+ * resend, change, error, submit.
+ */
+/** Whether a subtree holds the block the designer has selected. */
+const containsBlockId = (
+  blocks: BlockRendererProps['block']['blocks'],
+  blockId: string
+): boolean =>
+  (blocks || []).some(
+    (candidate) =>
+      candidate.id === blockId || containsBlockId(candidate.blocks, blockId)
+  );
+
+const OtpFormBlock = ({
+  block,
+  placeholderId,
+  sectionId,
+  selectedBlockId,
+  currentBreakpoint = 'desktop',
+  isDesigner = false
+}: BlockRendererProps) => {
+  const prop = (key: string, fallback: string) =>
+    String(
+      getResponsiveValue(block.properties?.[key], currentBreakpoint, fallback)
+    );
+
+  const collectPhone = readToggle(
+    block.properties?.collectPhone,
+    currentBreakpoint,
+    true
+  );
+  const showLabels = readToggle(
+    block.properties?.showLabels,
+    currentBreakpoint,
+    true
+  );
+  const phoneLabel = prop('phoneLabel', 'Phone');
+  const phonePlaceholder = prop('phonePlaceholder', '');
+  /**
+   * The copy for a number left empty or typed wrongly — the brand's own
+   * sentence in place of the browser's bubble.
+   */
+  const requiredMessage = prop('requiredMessage', 'This field is required.');
+  const invalidMessage = prop('invalidMessage', 'Please check this field.');
+  const phoneDescription = prop('phoneDescription', '');
+  const sendLabel = prop('sendLabel', 'Send code');
+  // Empty on purpose: without a busy label the caption stays put while the
+  // request runs, matching every other auth block.
+  const sendBusyLabel = prop('sendBusyLabel', '');
+  const sendErrorLabel = prop(
+    'sendErrorLabel',
+    'Could not send the code. Please try again.'
+  );
+  const codeDescription = prop(
+    'codeDescription',
+    'Enter the verification code sent to {phone}.'
+  );
+  const rawCodeLength = Number(
+    getResponsiveValue(block.properties?.codeLength, currentBreakpoint, 6)
+  );
+  const codeLength =
+    Number.isFinite(rawCodeLength) && rawCodeLength >= 4 && rawCodeLength <= 8
+      ? Math.floor(rawCodeLength)
+      : 6;
+  const rawTimer = Number(
+    getResponsiveValue(block.properties?.timerSeconds, currentBreakpoint, 60)
+  );
+  const timerSeconds =
+    Number.isFinite(rawTimer) && rawTimer >= 10 && rawTimer <= 600
+      ? Math.floor(rawTimer)
+      : 60;
+  const showCountdown = readToggle(
+    block.properties?.showCountdown,
+    currentBreakpoint,
+    true
+  );
+  const resendLabel = prop('resendLabel', 'Resend code');
+  const verifyLabel = prop('verifyLabel', 'Verify');
+  const verifyBusyLabel = prop('verifyBusyLabel', '');
+  const changeLabel = prop('changeLabel', 'Use a different number');
+  const providerId = prop('providerId', 'default');
+  const otpFormType = prop('otpFormType', 'otpLogin');
+  const callbackUrl = prop('callbackUrl', '/');
+  const errorLabel = prop('errorLabel', 'Verification failed.');
+  /**
+   * Submitting a half-typed code used to be a silent no-op: the built-in verify
+   * button is disabled until the last box is filled, so nothing could reach it.
+   * A COMPOSED form's CTA is an ordinary Button block, which cannot disable
+   * itself — so the form has to say what is missing instead of doing nothing.
+   */
+  /**
+   * Detached submit, the same pair the other auth forms carry: naming the form
+   * lets a Button anywhere on the page submit it through the native `form`
+   * attribute — which is how a drawer pins its CTA to the bottom bar.
+   */
+  const formHtmlId = prop('formHtmlId', '').trim();
+  const codeIncompleteMessage = prop(
+    'codeIncompleteMessage',
+    'Enter the {length}-digit code we sent you.'
+  );
+  // Defaults on: the commonest home for this block is a drawer, and a drawer
+  // still covering the page the shopper just signed into reads as a hang.
+  // closeAllModals is a no-op when nothing is open, so pages pay nothing.
+  const closeModalsOnSuccess = readToggle(
+    block.properties?.closeModalsOnSuccess,
+    currentBreakpoint,
+    true
+  );
+  // The code phase is unreachable in the canvas without sending a real SMS,
+  // so the designer picks the phase to dress — the previewSuccess pattern.
+  const previewPhase = resolveOption<PreviewPhase>(
+    block.properties?.previewPhase,
+    currentBreakpoint,
+    'auto',
+    PREVIEW_PHASES
+  );
+
+  const router = useRouter();
+  const { locale, defaultLocaleValue } = useLocalization();
+  const contextFlowId = useContext(AuthFlowIdContext);
+  /**
+   * The verification this form is allowed to finish.
+   *
+   * A page carries one parked record, and every OTP form used to answer to it —
+   * so a header's phone-login drawer, opened after a sign-up was abandoned
+   * elsewhere on the page, would open straight on the code screen and re-post
+   * that registration under whatever code the shopper typed. A form claims the
+   * record only when it belongs to the same journey; anything else is somebody
+   * else's, and this form starts where it always did.
+   */
+  const parked = usePendingOtp();
+  const pending = ownsPendingOtp(parked, contextFlowId) ? parked : null;
+  const [otpLogin, { isLoading: isSending }] = useOtpLoginMutation();
+
+  const [phone, setPhone] = useState('');
+  const [code, setCode] = useState('');
+  const [error, setError] = useState('');
+  // Per FIELD, as opposed to `error`, which is what the backend answered.
+  const [fieldErrors, setFieldErrors] = useState<AuthFieldErrors>({});
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  // Its own flag rather than a fold into `isSubmitting`: a resend and a verify
+  // are different requests, and the countdown restart hangs off this one.
+  const [isResending, setIsResending] = useState(false);
+  // The author's phase choice: 'phone' after "use a different number", 'code'
+  // right after a send. Everything else derives from the pending context.
+  const [phaseOverride, setPhaseOverride] = useState<OtpPhase | null>(null);
+  const [secondsLeft, setSecondsLeft] = useState(timerSeconds);
+  // Bumped to restart the countdown after a send or resend.
+  const [timerEpoch, setTimerEpoch] = useState(0);
+  const codeInputsRef = useRef<Array<HTMLInputElement | null>>([]);
+  /**
+   * Whether the caret should walk itself to the next empty box.
+   *
+   * True while digits ARRIVE (typing into the row, a paste), false when the
+   * shopper goes back to correct one — moving the caret off a box the moment
+   * its digit is fixed would make the second correction land somewhere else.
+   */
+  const advanceCaretRef = useRef(true);
+
+  /**
+   * Composed mode: the form's pieces are CHILD blocks — an `otp-phase` per
+   * half of the journey, the code boxes as `otp-code-input`, the number as an
+   * ordinary Auth Field, the CTA as a Button. Same contract the auth form uses:
+   * children present means they draw the form, empty means the fixed layout
+   * renders exactly as it always did.
+   */
+  const childBlocks = (block.blocks || [])
+    .filter((childBlock) => (isDesigner ? true : !childBlock.hidden))
+    .sort((a, b) => (a.order || 0) - (b.order || 0));
+  const isComposed = childBlocks.length > 0;
+
+  /** One flag for the three requests this block makes. */
+  const isBusy = isSending || isSubmitting || isResending;
+
+  const phase: OtpPhase = isDesigner
+    ? previewPhase === 'auto'
+      ? collectPhone
+        ? 'phone'
+        : 'code'
+      : previewPhase
+    : phaseOverride ?? (pending ? 'code' : 'phone');
+
+  useEffect(() => {
+    if (isDesigner || phase !== 'code') return undefined;
+
+    setSecondsLeft(timerSeconds);
+    const interval = setInterval(() => {
+      setSecondsLeft((current) => (current > 0 ? current - 1 : 0));
+    }, 1000);
+
+    return () => clearInterval(interval);
+  }, [isDesigner, phase, timerSeconds, timerEpoch]);
+
+  // Keep the caret on the next empty box while digits arrive — but leave it
+  // where the shopper put it when they are correcting one.
+  useEffect(() => {
+    if (isDesigner || phase !== 'code') return;
+    if (!advanceCaretRef.current) return;
+
+    const index = Math.min(code.length, codeLength - 1);
+    codeInputsRef.current[index]?.focus();
+  }, [isDesigner, phase, code, codeLength]);
+
+  /**
+   * A detached CTA (a Button carrying this form's id) is outside this subtree
+   * and cannot see `isBusy` — so the form publishes it. See
+   * `auth/form-submit-bus.ts`.
+   */
+  React.useEffect(() => {
+    if (!formHtmlId) return undefined;
+
+    publishFormSubmitState(formHtmlId, isBusy);
+
+    return () => clearFormSubmitState(formHtmlId);
+  }, [formHtmlId, isBusy]);
+
+  // Nothing to collect and nothing pending: there is no journey this block
+  // could complete, and a dead verify form is worse than no block at all.
+  if (!isDesigner && !collectPhone && !pending && phaseOverride === null) {
+    return null;
+  }
+
+  const canResend = secondsLeft <= 0;
+  /**
+   * Every box filled. Not the same as the code being `codeLength` long: a
+   * shopper who skips a box and fills a later one leaves a gap, which the code
+   * carries as a blank so the boxes after it stay where they were typed.
+   */
+  const isCodeComplete = code.length === codeLength && !code.includes(' ');
+  const displayPhone = pending?.phone || phone.replace(/[^\d]/g, '');
+  const verifyProvider = pending?.providerId || providerId;
+
+  const startCodePhase = () => {
+    setCode('');
+    setPhaseOverride('code');
+    setTimerEpoch((epoch) => epoch + 1);
+  };
+
+  const sendCode = async (digits: string): Promise<boolean> => {
+    try {
+      await otpLogin({ phone: digits }).unwrap();
+      return true;
+    } catch (sendError) {
+      if (isEmptyBodySuccess(sendError)) return true;
+
+      setError(sendErrorLabel);
+      return false;
+    }
+  };
+
+  /**
+   * A message describes what the field WAS: it goes as soon as it is edited.
+   * Both events, because a keystroke raises `input` while autofill raises
+   * `change`.
+   */
+  const handleInput = (event: React.FormEvent<HTMLFormElement>) => {
+    const target = event.target as { name?: string } | null;
+
+    setFieldErrors((current) =>
+      clearAuthFieldError(current, target?.name || '')
+    );
+  };
+
+  const submitPhone = async (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setError('');
+
+    // Submitting inside the designer would text a real shopper.
+    if (isDesigner || isSending) return;
+
+    // The form carries `noValidate`, so an empty number used to leave the
+    // browser's bubble here and now leaves our own message under the field.
+    // See `auth-field-errors.tsx`.
+    const { errors: nextFieldErrors, firstInvalid } = collectAuthFieldErrors(
+      event.currentTarget,
+      { required: requiredMessage, invalid: invalidMessage }
+    );
+
+    setFieldErrors(nextFieldErrors);
+
+    if (firstInvalid) {
+      firstInvalid.focus();
+
+      return;
+    }
+
+    // Composed: the number lives in a child Auth Field, so it is read off the
+    // form the same way an auth form reads its composed fields.
+    const typedPhone = isComposed
+      ? String(new FormData(event.currentTarget).get('phone') ?? '')
+      : phone;
+    const digits = typedPhone.replace(/[^\d]/g, '');
+
+    // A number made only of the mask characters a brand renders around the
+    // input passes `required` and still has nothing to text.
+    if (!digits) {
+      setFieldErrors({ phone: invalidMessage });
+
+      return;
+    }
+
+    // Kept so the code phase can name the number before `pending` carries it.
+    if (isComposed) setPhone(typedPhone);
+
+    if (await sendCode(digits)) {
+      setPendingOtp({
+        kind: 'login',
+        phone: digits,
+        providerId,
+        // Scoped to the journey this form stands in, so a verification started
+        // here is not picked up by an unrelated OTP form elsewhere.
+        scope: contextFlowId
+      });
+      startCodePhase();
+    }
+  };
+
+  const submitCode = async (event: React.FormEvent) => {
+    event.preventDefault();
+    setError('');
+
+    if (isDesigner || isSubmitting) return;
+
+    if (!isCodeComplete) {
+      // The built-in button is disabled until the code is complete, so this is
+      // reachable only from a composed CTA — where silence would read as a
+      // dead button.
+      setError(codeIncompleteMessage.replace('{length}', String(codeLength)));
+
+      return;
+    }
+
+    const isRegisterVerification =
+      pending?.kind === 'register' && Boolean(pending.payload);
+
+    const payload: Record<string, unknown> = isRegisterVerification
+      ? { ...(pending?.payload ?? {}), code }
+      : {
+          formType: otpFormType,
+          // The credentials provider throws when the locale is missing, so an
+          // explicit value is always sent.
+          locale: locale || defaultLocaleValue || '',
+          phone: displayPhone,
+          code
+        };
+
+    setIsSubmitting(true);
+
+    try {
+      const response = await signIn(verifyProvider, {
+        // After the payload, for the reason register-form spells out: a key
+        // travelling in the body must not decide whether next-auth answers.
+        ...payload,
+        redirect: false,
+        callbackUrl
+      });
+
+      if (!response || response.error) {
+        setError(readAuthError(signInErrorDetail(response)) || errorLabel);
+        return;
+      }
+
+      clearPendingOtp(contextFlowId);
+      if (closeModalsOnSuccess) closeAllModals();
+      router.refresh();
+      router.push(response.url || callbackUrl);
+    } catch {
+      setError(errorLabel);
+    } finally {
+      setIsSubmitting(false);
+    }
+  };
+
+  const resend = async () => {
+    // `isBusy` as well as the countdown: the countdown only restarts once the
+    // request has ANSWERED, so between the click and the response the control
+    // still reads as available — a second click there texts the shopper twice,
+    // which is billed twice and which some backends count as abuse. Every other
+    // request-firing block in the package guards the same way.
+    if (isDesigner || !canResend || isBusy) return;
+
+    setError('');
+    setIsResending(true);
+
+    try {
+      if (pending?.kind === 'register' && pending.payload) {
+        // Re-submitting the parked registration makes commerce text a fresh
+        // code; the answer is another `otp` challenge, which is expected.
+        const response = await signIn(verifyProvider, {
+          ...pending.payload,
+          resend: true,
+          redirect: false,
+          callbackUrl
+        });
+
+        // `signIn` RESOLVES on a refusal rather than throwing, so the response
+        // has to be read: a rate limit or an expired attempt is not the `otp`
+        // challenge a resend expects, and restarting the countdown over it
+        // would leave the shopper waiting out a lockout for an SMS that was
+        // never sent. (Same shape `submitCode` reads.)
+        const detail = signInErrorDetail(response);
+
+        if (response?.error && !hasOtpChallenge(detail)) {
+          setError(readAuthError(detail) || sendErrorLabel);
+          return;
+        }
+
+        setCode('');
+        setTimerEpoch((epoch) => epoch + 1);
+        return;
+      }
+
+      if (displayPhone && (await sendCode(displayPhone))) {
+        setCode('');
+        setTimerEpoch((epoch) => epoch + 1);
+      }
+    } catch {
+      setError(sendErrorLabel);
+    } finally {
+      setIsResending(false);
+    }
+  };
+
+  /**
+   * A registration in flight has nowhere else to live: `pending.payload` is the
+   * ONLY copy of what the shopper filled in, so forgetting it to collect a new
+   * number would throw the sign-up away. The fixed layout has always hidden the
+   * control for that reason; a composed one puts it on a Button the author
+   * places, so the refusal belongs on the method rather than on the markup.
+   */
+  const canChangeNumber = collectPhone && pending?.kind !== 'register';
+
+  const changeNumber = () => {
+    if (isDesigner || !canChangeNumber) return;
+
+    clearPendingOtp();
+    setCode('');
+    setError('');
+    setPhaseOverride('phone');
+  };
+
+  const appendDigits = (digits: string) => {
+    if (!digits) return;
+
+    advanceCaretRef.current = true;
+    setCode((current) => (current + digits).slice(0, codeLength));
+  };
+
+  /**
+   * Write one box.
+   *
+   * Everything used to go through `appendDigits`, which put digits at the END
+   * of the code whatever box they were typed in. Correcting a wrong digit was
+   * therefore impossible: on a full code the append was capped away and the
+   * keystroke did nothing at all, and on a half-typed one the box's OWN digit
+   * came back with the new one (the input is controlled, so its value is both)
+   * and both landed at the end — "123" fixed at the first box became "12319".
+   *
+   * The row already knows which box was typed in; it just had no way to say so.
+   */
+  const setDigitAt = (index: number, digit: string) => {
+    if (index < 0 || index >= codeLength) return;
+
+    // A shopper typing into a box they have already filled means the LAST
+    // character they pressed, not the one that was sitting there.
+    const next = digit.slice(-1);
+    if (!next) return;
+
+    advanceCaretRef.current = false;
+    setCode((current) => {
+      const boxes = current.padEnd(codeLength, ' ').split('');
+      boxes[index] = next;
+
+      // Trailing blanks are what "not typed yet" looks like; a gap in the
+      // middle is a box the shopper skipped and can still come back to.
+      return boxes.join('').replace(/ +$/, '');
+    });
+
+    // The caret still walks forward when the row is being filled in order,
+    // which is what makes typing a code feel like one field.
+    if (index === code.length && index < codeLength - 1) {
+      advanceCaretRef.current = true;
+    }
+  };
+
+  /** Empty one box — what Backspace means in the box it was pressed in. */
+  const clearDigitAt = (index: number) => {
+    if (index < 0 || index >= codeLength) return;
+
+    advanceCaretRef.current = false;
+    setCode((current) => {
+      if (index >= current.length) return current;
+
+      const boxes = current.split('');
+      boxes[index] = ' ';
+
+      return boxes.join('').replace(/ +$/, '');
+    });
+  };
+
+  const inputStyle: React.CSSProperties = {
+    width: '100%',
+    border: '1px solid var(--otp-form-border, #d1d5db)',
+    background: 'transparent',
+    color: 'inherit',
+    padding: '10px 12px',
+    outline: 'none'
+  };
+
+  const submitStyle = (busy: boolean): React.CSSProperties => ({
+    padding: '12px 20px',
+    background: 'var(--otp-form-cta-bg, #111827)',
+    color: 'var(--otp-form-cta-color, #ffffff)',
+    border: 'none',
+    cursor: busy ? 'not-allowed' : 'pointer',
+    opacity: busy ? 0.7 : 1
+  });
+
+  const errorNode = error ? (
+    <div data-otp-form-error="" {...partAttrs('error')} role="alert">
+      {error}
+    </div>
+  ) : null;
+
+  /**
+   * Which children this phase draws.
+   *
+   * A child that is not a phase is shared chrome — a logo, a title, a support
+   * link — and shows in both halves. A phase shows when it IS the phase, and
+   * additionally in the canvas while it holds the selected block, so the
+   * designer can dress the half they are not previewing. Same rule the auth
+   * flow applies to its steps.
+   */
+  const showsInPhase = (childBlock: BlockRendererProps['block']): boolean => {
+    if (childBlock.type !== 'otp-phase') return true;
+
+    if (
+      isDesigner &&
+      selectedBlockId &&
+      (childBlock.id === selectedBlockId ||
+        containsBlockId(childBlock.blocks, selectedBlockId))
+    ) {
+      return true;
+    }
+
+    return (
+      String(
+        getResponsiveValue(
+          childBlock.properties?.phaseKey,
+          currentBreakpoint,
+          ''
+        )
+      ).trim() === phase
+    );
+  };
+
+  /**
+   * The children, with the six editor callbacks each one needs to be movable,
+   * duplicable, hideable, deletable and renamable on the canvas.
+   *
+   * Through the package's own `renderComposedChildren` rather than a private
+   * copy of it. The copies each posted their messages to `'*'`, which
+   * `editor-bridge.ts` exists to prevent — it addresses the editor's real
+   * origin, so an editor command never reaches whatever other page happens to
+   * be embedding the storefront — and every copy was a place a new message
+   * field had to be remembered.
+   */
+  const renderChildren = () =>
+    renderComposedChildren({
+      blocks: childBlocks.filter(showsInPhase),
+      placeholderId,
+      sectionId,
+      isDesigner,
+      selectedBlockId,
+      currentBreakpoint
+    });
+
+  if (isComposed) {
+    /**
+     * What the children can reach: the code the form verifies, the countdown
+     * they draw, and the two controls that are actions rather than markup.
+     * See `auth/otp-form-context.tsx` for why a context and not props.
+     */
+    const api: OtpFormApi = {
+      phase,
+      codeLength,
+      code,
+      appendDigits,
+      setDigitAt,
+      clearDigitAt,
+      removeLastDigit: () => {
+        advanceCaretRef.current = true;
+        setCode((current) => current.replace(/ +$/, '').slice(0, -1));
+      },
+      registerCodeInput: (index, element) => {
+        codeInputsRef.current[index] = element;
+      },
+      secondsLeft,
+      timerSeconds,
+      canResend,
+      resend,
+      changeNumber,
+      canChangeNumber,
+      displayPhone,
+      isBusy,
+      isDesigner
+    };
+
+    /**
+     * Asked of the children this phase actually draws, not of all of them: an
+     * error block authored inside the code phase must not silence the built-in
+     * message while the phone phase is up. See `auth/form-error-context.tsx`.
+     */
+    const errorIsAuthored = containsAuthErrorBlock(
+      childBlocks.filter(showsInPhase)
+    );
+
+    return (
+      // Three providers, three audiences: the OTP api is what the code boxes
+      // and the resend read, the field errors are what an Auth Field child
+      // draws under itself — the phone number here is an ordinary field and
+      // gets its message the same way a login form's does — and the form-level
+      // message is what a Form Error block draws wherever the design put it.
+      <OtpFormProvider value={api}>
+        <AuthFormErrorProvider value={error}>
+          <AuthFieldErrorsProvider value={fieldErrors}>
+            <form
+              id={formHtmlId || undefined}
+              data-otp-form=""
+              // Fills its block wrapper; see the note in auth-step-block.tsx.
+              className="w-full"
+              data-otp-form-phase={phase}
+              {...partAttrs('form')}
+              // One form for both halves: the phase decides which submit runs, so a
+              // composed CTA is an ordinary submit Button in either phase.
+              onSubmit={phase === 'phone' ? submitPhone : submitCode}
+              noValidate
+              onInput={handleInput}
+              onChange={handleInput}
+              style={{
+                display: 'flex',
+                flexDirection: 'column',
+                gap: 'var(--otp-form-gap, 12px)'
+              }}
+            >
+              {renderChildren()}
+
+              {/* The fallback for a composition that has not placed a Form Error
+                block: appended after every child, which is below the composed
+                CTA and outside the padding the design put on its own wrapper.
+                That is the whole reason the block exists. */}
+              {!errorIsAuthored && errorNode}
+            </form>
+          </AuthFieldErrorsProvider>
+        </AuthFormErrorProvider>
+      </OtpFormProvider>
+    );
+  }
+
+  if (phase === 'phone') {
+    return (
+      <form
+        id={formHtmlId || undefined}
+        data-otp-form=""
+        // Fills its block wrapper; see the note in auth-step-block.tsx.
+        className="w-full"
+        data-otp-form-phase="phone"
+        {...partAttrs('form')}
+        onSubmit={submitPhone}
+        // Our own message under the field instead of the browser's bubble over
+        // it; `required` below is still what decides.
+        noValidate
+        onInput={handleInput}
+        onChange={handleInput}
+        style={{
+          display: 'flex',
+          flexDirection: 'column',
+          gap: 'var(--otp-form-gap, 12px)'
+        }}
+      >
+        {phoneDescription && (
+          <div data-otp-form-description="" {...partAttrs('description')}>
+            {phoneDescription}
+          </div>
+        )}
+
+        <label
+          data-otp-form-field="phone"
+          {...partAttrs('field')}
+          style={{ display: 'flex', flexDirection: 'column', gap: '4px' }}
+        >
+          {/* Hiding the caption must not cost the input its accessible name,
+              so the label text moves onto aria-label instead. */}
+          {showLabels && <span {...partAttrs('label')}>{phoneLabel}</span>}
+          <input
+            type="tel"
+            name="phone"
+            value={phone}
+            onChange={(event) => setPhone(event.target.value)}
+            autoComplete="tel"
+            inputMode="tel"
+            placeholder={phonePlaceholder || undefined}
+            aria-label={showLabels ? undefined : phoneLabel}
+            aria-invalid={fieldErrors.phone ? true : undefined}
+            required
+            {...partAttrs('input')}
+            style={{
+              ...inputStyle,
+              ...(fieldErrors.phone
+                ? { borderColor: 'var(--otp-form-border-invalid, #dc2626)' }
+                : null)
+            }}
+          />
+          {fieldErrors.phone && (
+            <span
+              data-otp-form-field-error="phone"
+              {...partAttrs('error')}
+              role="alert"
+              style={{
+                color: 'var(--otp-form-error-color, #dc2626)',
+                fontSize: '0.875em'
+              }}
+            >
+              {fieldErrors.phone}
+            </span>
+          )}
+        </label>
+
+        {errorNode}
+
+        <button
+          type="submit"
+          data-otp-form-submit="send"
+          {...partAttrs('submit', { loading: isSending, disabled: isSending })}
+          disabled={isSending}
+          aria-busy={isSending}
+          style={submitStyle(isSending)}
+        >
+          {isSending && sendBusyLabel ? sendBusyLabel : sendLabel}
+        </button>
+      </form>
+    );
+  }
+
+  const displayedSeconds = isDesigner ? timerSeconds : secondsLeft;
+  const countdownRatio =
+    timerSeconds > 0 ? Math.max(0, displayedSeconds / timerSeconds) : 0;
+  const ringCircumference = 2 * Math.PI * 16;
+
+  const countdown =
+    showCountdown && (isDesigner || !canResend) ? (
+      <span
+        data-otp-form-countdown=""
+        {...partAttrs('countdown')}
+        aria-hidden="true"
+        style={{ display: 'inline-flex', flexShrink: 0 }}
+      >
+        <svg width="40" height="40" viewBox="0 0 40 40" role="presentation">
+          <circle
+            cx="20"
+            cy="20"
+            r="16"
+            fill="none"
+            stroke="var(--otp-form-ring-track, #e5e7eb)"
+            strokeWidth="3"
+          />
+          <circle
+            cx="20"
+            cy="20"
+            r="16"
+            fill="none"
+            stroke="var(--otp-form-ring, currentColor)"
+            strokeWidth="3"
+            strokeLinecap="round"
+            strokeDasharray={ringCircumference}
+            strokeDashoffset={ringCircumference * (1 - countdownRatio)}
+            transform="rotate(-90 20 20)"
+          />
+          <text
+            x="20"
+            y="20"
+            textAnchor="middle"
+            dominantBaseline="central"
+            fontSize="12"
+            fill="currentColor"
+          >
+            {displayedSeconds}
+          </text>
+        </svg>
+      </span>
+    ) : null;
+
+  const showChangeNumber =
+    collectPhone && (isDesigner || pending?.kind !== 'register');
+
+  return (
+    <form
+      id={formHtmlId || undefined}
+      data-otp-form=""
+      // Fills its block wrapper; see the note in auth-step-block.tsx.
+      className="w-full"
+      data-otp-form-phase="code"
+      {...partAttrs('form')}
+      onSubmit={submitCode}
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--otp-form-gap, 12px)'
+      }}
+    >
+      {codeDescription && (
+        <div data-otp-form-description="" {...partAttrs('description')}>
+          {codeDescription.replace('{phone}', displayPhone)}
+        </div>
+      )}
+
+      <div
+        data-otp-form-code=""
+        {...partAttrs('code')}
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: 'var(--otp-form-code-gap, 8px)'
+        }}
+      >
+        {countdown}
+
+        {Array.from({ length: codeLength }, (_, index) => (
+          <input
+            key={index}
+            ref={(element) => {
+              codeInputsRef.current[index] = element;
+            }}
+            type="text"
+            inputMode="numeric"
+            autoComplete={index === 0 ? 'one-time-code' : 'off'}
+            aria-label={`${index + 1} / ${codeLength}`}
+            // A blank stands for a box the shopper skipped; it draws empty.
+            value={(code[index] ?? '').trim()}
+            onChange={(event) =>
+              setDigitAt(index, event.target.value.replace(/\D/g, ''))
+            }
+            onKeyDown={(event) => {
+              if (event.key === 'Backspace') {
+                event.preventDefault();
+
+                // Empty the box it was pressed in, then step back — what a row
+                // of boxes does everywhere else. Deleting the LAST digit
+                // instead meant a shopper correcting the second box watched the
+                // sixth one disappear.
+                if (code[index] && code[index] !== ' ') {
+                  clearDigitAt(index);
+                } else if (index > 0) {
+                  clearDigitAt(index - 1);
+                  codeInputsRef.current[index - 1]?.focus();
+                }
+              }
+            }}
+            onPaste={(event) => {
+              event.preventDefault();
+              appendDigits(
+                event.clipboardData.getData('text').replace(/\D/g, '')
+              );
+            }}
+            {...partAttrs('code-input')}
+            style={{
+              width: '40px',
+              height: '48px',
+              textAlign: 'center',
+              fontSize: '18px',
+              border: '1px solid var(--otp-form-border, #d1d5db)',
+              background: 'transparent',
+              color: 'inherit',
+              outline: 'none'
+            }}
+          />
+        ))}
+
+        <button
+          type="button"
+          data-otp-form-resend=""
+          {...partAttrs('resend', { disabled: !isDesigner && !canResend })}
+          onClick={resend}
+          disabled={!isDesigner && !canResend}
+          style={{
+            padding: 0,
+            margin: 0,
+            border: 'none',
+            background: 'transparent',
+            color: 'inherit',
+            font: 'inherit',
+            textDecoration: 'underline',
+            cursor: !isDesigner && !canResend ? 'not-allowed' : 'pointer',
+            opacity: !isDesigner && !canResend ? 0.5 : 1
+          }}
+        >
+          {resendLabel}
+        </button>
+      </div>
+
+      {errorNode}
+
+      <button
+        type="submit"
+        data-otp-form-submit="verify"
+        {...partAttrs('submit', {
+          loading: isSubmitting,
+          disabled: isSubmitting || (!isDesigner && !isCodeComplete)
+        })}
+        disabled={isSubmitting || (!isDesigner && !isCodeComplete)}
+        aria-busy={isSubmitting}
+        style={submitStyle(isSubmitting)}
+      >
+        {isSubmitting && verifyBusyLabel ? verifyBusyLabel : verifyLabel}
+      </button>
+
+      {showChangeNumber && (
+        <button
+          type="button"
+          data-otp-form-change=""
+          {...partAttrs('change')}
+          onClick={changeNumber}
+          style={{
+            alignSelf: 'flex-start',
+            padding: 0,
+            margin: 0,
+            border: 'none',
+            background: 'transparent',
+            color: 'inherit',
+            font: 'inherit',
+            textDecoration: 'underline',
+            cursor: 'pointer'
+          }}
+        >
+          {changeLabel}
+        </button>
+      )}
+    </form>
+  );
+};
+
+export default OtpFormBlock;