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

package/src/__tests__/registry-parity.test.ts

@@ -32,7 +32,13 @@ const EXPECTED_BLOCK_TYPES = [
   'address-list',
   'announcement-bar',
   'applied-filters',
+  'auth-consent',
+  'auth-error',
+  'auth-flow',
+  'auth-field',
   'auth-form',
+  'auth-step',
+  'auth-step-title',
   'basket-items',
   'basket-summary',
   'button',
@@ -78,6 +84,9 @@ const EXPECTED_BLOCK_TYPES = [
   'order-list',
   'order-success',
   'order-tracking',
+  'otp-code-input',
+  'otp-form',
+  'otp-phase',
   'panel',
   'payment-badges',
   'product-attributes',

package/src/auth/auth-field-errors.tsx

@@ -0,0 +1,151 @@
+'use client';
+
+import React from 'react';
+
+/**
+ * What a composed auth form found wrong on its last submit, keyed by the name
+ * each control submits under.
+ *
+ * Native constraint validation used to do this job: `required` on a field and
+ * the browser draws its own bubble when the form is submitted — its own copy
+ * ("Please fill in this field"), its own typography, its own position, none of
+ * which a brand can touch, and gone the moment focus moves. The storefront's
+ * own auth pages have always drawn the message UNDER the field instead, in the
+ * brand's error colour, and left it there until the field was fixed.
+ *
+ * So the form carries `noValidate`, which turns the bubble off while leaving
+ * `validity` reporting exactly as before: the RULES stay where a designer set
+ * them (the field's Required toggle, `type="email"`) and only the presentation
+ * moves in here.
+ *
+ * Why a context rather than props: the fields of a composed form are child
+ * BLOCKS at any depth — a field inside a Group inside a Step — so the form has
+ * no reference to hand a message to. Each field reads its own entry instead.
+ */
+export type AuthFieldErrors = Readonly<Record<string, string>>;
+
+const NO_ERRORS: AuthFieldErrors = {};
+
+const AuthFieldErrorsContext = React.createContext<AuthFieldErrors>(NO_ERRORS);
+
+export const AuthFieldErrorsProvider = AuthFieldErrorsContext.Provider;
+
+/** The message for one control name, '' while that field is fine. */
+export const useAuthFieldError = (name: string): string => {
+  const errors = React.useContext(AuthFieldErrorsContext);
+
+  return errors[name] || '';
+};
+
+/** The copy a form shows for the two things a field can be wrong about. */
+export interface AuthValidationMessages {
+  /** Left empty while the field is required. */
+  required: string;
+  /** Filled in, but not a value of the field's type — an e-mail with no @. */
+  invalid: string;
+}
+
+export interface AuthFieldValidation {
+  errors: AuthFieldErrors;
+  /**
+   * The first offending control, so the form can put the caret where the work
+   * is — the one thing the native bubble did well.
+   */
+  firstInvalid: HTMLElement | null;
+}
+
+type FormControl = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
+
+/**
+ * Whether a control is actually on screen for this breakpoint.
+ *
+ * `checkVisibility` answers this outright where it exists; the walk is the
+ * fallback for engines (and for jsdom) that do not have it yet. Only the two
+ * properties that REMOVE a control from the page are consulted — an element
+ * scrolled out of view, sized to nothing, or covered by another is still a
+ * control the shopper can be sent to.
+ */
+const isVisibleControl = (control: FormControl): boolean => {
+  if (typeof control.checkVisibility === 'function') {
+    return control.checkVisibility();
+  }
+
+  let node: HTMLElement | null = control;
+
+  while (node) {
+    const style = window.getComputedStyle(node);
+    if (style.display === 'none' || style.visibility === 'hidden') return false;
+    node = node.parentElement;
+  }
+
+  return true;
+};
+
+/**
+ * What is wrong with the form as it stands, read from the controls themselves.
+ *
+ * Deliberately DOM-driven rather than config-driven: a composed form's fields
+ * are blocks the designer arranged, and the constraints already live on the
+ * controls that got rendered. Reading `validity` keeps one source of truth and
+ * covers a field this theme knows nothing about — anything with a name inside
+ * the form is checked the same way the browser would have checked it.
+ */
+export const collectAuthFieldErrors = (
+  form: HTMLFormElement,
+  messages: AuthValidationMessages
+): AuthFieldValidation => {
+  const errors: Record<string, string> = {};
+  let firstInvalid: HTMLElement | null = null;
+
+  const controls = Array.from(
+    form.querySelectorAll<FormControl>(
+      'input[name], select[name], textarea[name]'
+    )
+  );
+
+  controls.forEach((control) => {
+    // `willValidate` is false for a disabled, hidden or readonly control —
+    // exactly the set the browser skips, so the two agree on what counts.
+    if (!control.willValidate || control.validity.valid) return;
+
+    // `hidden` above means `type="hidden"`, NOT a control the design has taken
+    // off this breakpoint. The editor's Visibility setting is CSS — it writes
+    // `display: none` onto the block wrapper and leaves the control in the
+    // form — and `willValidate` does not care about CSS. So a required field
+    // hidden on mobile refused every submit there: nothing was focusable,
+    // `noValidate` had already suppressed the browser's bubble, and the
+    // message this function returns was drawn inside the hidden wrapper. A
+    // field the shopper cannot see is not one they can be asked to fill in.
+    if (!isVisibleControl(control)) return;
+
+    // First one wins per name: a radio group, or a name a composition
+    // duplicated, is one question to the shopper rather than several.
+    if (!errors[control.name]) {
+      errors[control.name] = control.validity.valueMissing
+        ? messages.required
+        : messages.invalid;
+    }
+
+    if (!firstInvalid) firstInvalid = control;
+  });
+
+  return { errors, firstInvalid };
+};
+
+/**
+ * The same map with one field's message dropped — what a form does the moment
+ * that field is edited, so a message never outlives the mistake it describes.
+ * The identical object comes back when there was nothing to drop, which keeps
+ * a keystroke in a valid field from re-rendering the form.
+ */
+export const clearAuthFieldError = (
+  errors: AuthFieldErrors,
+  name: string
+): AuthFieldErrors => {
+  if (!name || !errors[name]) return errors;
+
+  const next = { ...errors };
+  delete next[name];
+
+  return next;
+};

package/src/auth/auth-flow-bus.ts

@@ -0,0 +1,415 @@
+'use client';
+
+import React, { useSyncExternalStore } from 'react';
+
+/**
+ * Which step every auth flow on the page is showing, plus the one pending
+ * SMS-verification the page may be carrying.
+ *
+ * A step is changed by something that is not necessarily inside the flow — a
+ * header button that opens the login drawer straight on the register step, a
+ * banner CTA, the register form asking for its verification code. Those can
+ * live in DIFFERENT React roots: every placeholder mounts its own
+ * `ThemePlaceholderWrapper`, so header and drawer share no provider and no
+ * context. Module state is the one channel that crosses those roots — exactly
+ * the reasoning `overlay-bus.ts` already applies to composed modals, and this
+ * bus copies its shape deliberately (SSR guard, `useSyncExternalStore`,
+ * empty-key subscriptions that cost nothing).
+ *
+ * Two flows that share a `flowId` share a step on purpose: a desktop drawer
+ * and a mobile sheet composed as two blocks stay in sync instead of each
+ * keeping a private half of the journey.
+ *
+ *     // trigger, anywhere on the page
+ *     setAuthStep('auth', 'register');
+ *
+ *     // the flow block
+ *     const state = useAuthFlowState(flowId);
+ *     const activeKey = state?.active ?? initialStep;
+ */
+
+export interface AuthFlowState {
+  /** The step key the flow should be showing. */
+  active: string;
+  /** Previously active step keys, oldest first — what "back" walks. */
+  history: readonly string[];
+}
+
+/**
+ * The registration or phone-login a shopper started that now waits on an SMS
+ * code. Written by whichever block hit the OTP branch (the register form, the
+ * OTP form's own phone phase) and read by the `otp-form` block, which may sit
+ * in another step or another placeholder entirely.
+ */
+export interface PendingOtp {
+  kind: 'login' | 'register';
+  /** Bare digits, as commerce expects them. */
+  phone?: string;
+  /** The next-auth provider the verification must re-submit through. */
+  providerId?: string;
+  /**
+   * For `register`: the full signIn payload (formType, locale, fields,
+   * consents) the code is appended to on verify — commerce answers the same
+   * endpoint, now with `code`, exactly as the brand's own register view does.
+   */
+  payload?: Record<string, unknown>;
+  /**
+   * Which journey the verification belongs to: the flow whose step holds the
+   * OTP form, or `''` for a page that stands a register form and an OTP form
+   * side by side without a flow around them.
+   *
+   * An `otp-form` claims only a record from its OWN scope. Without that, one
+   * page-wide slot meant every form on the page answered to it: a header's
+   * phone-login drawer, opened long after a sign-up was abandoned, would find
+   * a `register` record, skip its own phone half, and re-post someone's
+   * registration — password included — under a code they typed for something
+   * else.
+   */
+  scope?: string;
+  /**
+   * The step the handoff moved to, when a target was named. Navigating the
+   * flow anywhere else abandons the verification: a payload that outlives the
+   * step it belongs to is one nothing on the page is waiting for.
+   */
+  stepKey?: string;
+}
+
+/**
+ * The flow id every control falls back to when nothing narrower is known: a
+ * page composes one auth journey far more often than several, and asking every
+ * author to invent and retype an id for it would make the common case the
+ * fiddly one.
+ */
+export const DEFAULT_AUTH_FLOW_ID = 'auth';
+
+/**
+ * A journey cannot meaningfully be this deep; past it something is navigating
+ * in a loop. The history is capped rather than refused so "back" keeps
+ * working — the oldest entries fall off instead of the click dying.
+ */
+const MAX_HISTORY = 32;
+
+/**
+ * How long a parked verification stays meaningful.
+ *
+ * The commerce code expires long before this; the cap is here because the
+ * record carries a REGISTRATION until it is verified — a password among the
+ * fields — and module state lives as long as the tab does. On a page where
+ * nothing else can clear it (a register form standing on its own, with no flow
+ * to unmount and no OTP form to finish the journey) the payload would otherwise
+ * sit in memory for the rest of the visit.
+ */
+const PENDING_OTP_TTL_MS = 15 * 60 * 1000;
+
+let flowStates: ReadonlyMap<string, AuthFlowState> = new Map();
+let pendingOtp: PendingOtp | null = null;
+let pendingOtpTimer: ReturnType<typeof setTimeout> | null = null;
+
+const listeners = new Set<() => void>();
+
+const notify = () => {
+  listeners.forEach((listener) => listener());
+};
+
+export const subscribeToAuthFlows = (listener: () => void): (() => void) => {
+  listeners.add(listener);
+
+  return () => {
+    listeners.delete(listener);
+  };
+};
+
+/**
+ * Mutations are refused outside the browser. Module state on a server is per
+ * PROCESS, not per request — one visitor's step change would leak into the
+ * next visitor's render. Nothing legitimate calls these outside an event
+ * handler or an effect. (Same contract as `overlay-bus.ts`.)
+ */
+const canMutate = () => typeof window !== 'undefined';
+
+/**
+ * Drop the parked verification and the timer holding it. Declared here rather
+ * than beside the other pending helpers because the step mutations below abandon
+ * a verification the shopper has navigated away from, and a `const` does not
+ * hoist. Callers that also change flow state notify once, for both.
+ */
+const forgetPendingOtp = ({ quiet = false }: { quiet?: boolean } = {}) => {
+  if (pendingOtpTimer) {
+    clearTimeout(pendingOtpTimer);
+    pendingOtpTimer = null;
+  }
+
+  if (pendingOtp === null) return;
+
+  pendingOtp = null;
+  if (!quiet) notify();
+};
+
+/**
+ * Whether a step change leaves behind the verification the page is carrying.
+ * Only a record that named a step can be abandoned this way — one parked
+ * without a target (the register form and the OTP form composed side by side,
+ * no flow between them) is not tied to any step and stays until it is finished,
+ * cleared, or times out.
+ */
+const abandonsPendingOtp = (flowId: string, stepKey: string): boolean =>
+  pendingOtp !== null &&
+  (pendingOtp.scope || '') === flowId &&
+  Boolean(pendingOtp.stepKey) &&
+  pendingOtp.stepKey !== stepKey;
+
+export const getAuthFlowState = (flowId: string): AuthFlowState | null =>
+  flowStates.get(flowId) ?? null;
+
+export const setAuthStep = (flowId: string, stepKey: string): void => {
+  if (!canMutate() || !flowId || !stepKey) return;
+
+  const current = flowStates.get(flowId);
+
+  // Re-selecting the active step must not stack a phantom "back" entry.
+  if (current?.active === stepKey) return;
+
+  const history = current
+    ? [...current.history, current.active].slice(-MAX_HISTORY)
+    : [];
+
+  const next = new Map(flowStates);
+  next.set(flowId, { active: stepKey, history });
+  flowStates = next;
+
+  // Walking away from the step that holds the verification abandons it: a
+  // payload left armed is one the next OTP form to mount would answer for.
+  if (abandonsPendingOtp(flowId, stepKey)) forgetPendingOtp({ quiet: true });
+
+  notify();
+};
+
+/**
+ * Walk one step back. With no history left the flow is reset instead: the
+ * state disappears and the flow block falls back to its authored initial
+ * step, which is where the journey began.
+ */
+export const goBackAuthStep = (flowId: string): void => {
+  if (!canMutate() || !flowId) return;
+
+  const current = flowStates.get(flowId);
+  if (!current) return;
+
+  const next = new Map(flowStates);
+
+  if (current.history.length === 0) {
+    next.delete(flowId);
+    // No history left means the flow is back at its authored initial step,
+    // which is never the step a handoff moved to.
+    if (abandonsPendingOtp(flowId, '')) forgetPendingOtp({ quiet: true });
+  } else {
+    const history = [...current.history];
+    const active = history.pop() as string;
+    next.set(flowId, { active, history });
+    if (abandonsPendingOtp(flowId, active)) forgetPendingOtp({ quiet: true });
+  }
+
+  flowStates = next;
+  notify();
+};
+
+/** Drop a flow's state so it renders its authored initial step again. */
+export const resetAuthFlow = (flowId: string): void => {
+  if (!canMutate() || !flowStates.has(flowId)) return;
+
+  const next = new Map(flowStates);
+  next.delete(flowId);
+  flowStates = next;
+  notify();
+};
+
+/**
+ * How many flow blocks currently render each flow id, so a flow that leaves
+ * the page can clean up after itself without a breakpoint twin resetting it.
+ * A drawer's flow unmounts when the drawer closes (`ThemeModalMount` renders
+ * children only while open) — that is the moment a fresh-start flow forgets
+ * the abandoned journey. But a desktop and a mobile flow sharing an id are
+ * BOTH mounted (responsive hiding is CSS, not unmount), so only the last
+ * mount out may reset.
+ */
+const mountCounts = new Map<string, number>();
+
+export const registerAuthFlowMount = (
+  flowId: string,
+  { resetOnLastUnmount = false }: { resetOnLastUnmount?: boolean } = {}
+): (() => void) => {
+  if (!canMutate() || !flowId) return () => undefined;
+
+  mountCounts.set(flowId, (mountCounts.get(flowId) ?? 0) + 1);
+
+  // Releases its own registration exactly once — StrictMode double-invokes
+  // effect cleanups in development, same guard as overlay-bus's host counter.
+  let released = false;
+
+  return () => {
+    if (released) return;
+
+    released = true;
+    const remaining = Math.max(0, (mountCounts.get(flowId) ?? 1) - 1);
+
+    if (remaining === 0) {
+      mountCounts.delete(flowId);
+
+      if (resetOnLastUnmount) {
+        resetAuthFlow(flowId);
+        // A verification the shopper walked away from must not resurface in a
+        // later, unrelated login: the payload holds a password. Scoped to THIS
+        // flow — the reset above already is, and a page may carry a second
+        // flow, or an OTP form outside every flow, whose journey is still live.
+        clearPendingOtp(flowId);
+      }
+    } else {
+      mountCounts.set(flowId, remaining);
+    }
+  };
+};
+
+/**
+ * The step a flow is showing, and what it is called.
+ *
+ * A drawer that walks a shopper through several steps has ONE close button and
+ * ONE title row, but the title changes with the step. Authoring the title
+ * inside each step cannot produce that: the row is a sibling of the steps, so
+ * it renders once and has no way to know which step is up. The flow does know —
+ * it is the thing that decided — so it says so here, and a title block sitting
+ * anywhere inside the flow can read it.
+ *
+ * Context rather than the module bus above: the value is derived per render
+ * from the flow's own children (their keys and titles), not shared page state,
+ * and a flow renders its children in the same React tree.
+ */
+export interface ActiveAuthStep {
+  key: string;
+  title: string;
+}
+
+export const ActiveAuthStepContext = React.createContext<ActiveAuthStep | null>(
+  null
+);
+
+/** Null outside a flow, which is how a title block knows to draw nothing. */
+export const useActiveAuthStep = (): ActiveAuthStep | null =>
+  React.useContext(ActiveAuthStepContext);
+
+export const getPendingOtp = (): PendingOtp | null => pendingOtp;
+
+export const setPendingOtp = (next: PendingOtp): void => {
+  if (!canMutate()) return;
+
+  forgetPendingOtp({ quiet: true });
+  pendingOtp = next;
+  pendingOtpTimer = setTimeout(forgetPendingOtp, PENDING_OTP_TTL_MS);
+  notify();
+};
+
+/**
+ * Forget the parked verification.
+ *
+ * With a `scope` the clear speaks only for that journey — the flow cleanup
+ * below is per flow id, and the verification the page is carrying may belong to
+ * a different flow entirely, or to an OTP form standing outside every flow.
+ * Without one it is unconditional: that is what a shopper's own "use a
+ * different number" and a finished verification mean.
+ */
+export const clearPendingOtp = (scope?: string): void => {
+  if (!canMutate() || pendingOtp === null) return;
+  if (scope !== undefined && (pendingOtp.scope || '') !== scope) return;
+
+  forgetPendingOtp();
+};
+
+/**
+ * Whether an OTP form standing in `flowId` (empty outside every flow) is the
+ * one this verification was parked for. Scopes must match rather than merely
+ * overlap: an unscoped record belongs to the page's own composition, and a
+ * form inside a drawer is not part of it.
+ */
+export const ownsPendingOtp = (
+  pending: PendingOtp | null,
+  flowId: string
+): boolean => pending !== null && (pending.scope || '') === (flowId || '');
+
+/**
+ * Nothing is navigated and nothing is pending during SSR — the server
+ * snapshot must always say so, or the serialized markup would differ from the
+ * client's page-load state and hydration would tear. (See `overlay-bus.ts`.)
+ */
+const nullOnServer = () => null;
+
+/** Subscription for a caller with no flow to watch — costs no listener. */
+const neverNotifies = () => () => undefined;
+
+const alwaysNull = () => null;
+
+/** Pass an empty id for "nothing to watch" — it costs no subscription. */
+export const useAuthFlowState = (flowId: string): AuthFlowState | null =>
+  useSyncExternalStore(
+    flowId ? subscribeToAuthFlows : neverNotifies,
+    flowId ? () => flowStates.get(flowId) ?? null : alwaysNull,
+    nullOnServer
+  );
+
+export const usePendingOtp = (): PendingOtp | null =>
+  useSyncExternalStore(subscribeToAuthFlows, getPendingOtp, nullOnServer);
+
+/**
+ * The flow a block sits inside, when it sits inside one. The flow block
+ * provides it around its children — those render through `ThemeBlock` in the
+ * same React tree, so context works there and spares the author retyping the
+ * flow id on every trigger. Cross-root triggers (a header button) have no
+ * provider and spell the flow out in their target instead.
+ */
+export const AuthFlowIdContext = React.createContext<string>('');
+
+export interface AuthStepTarget {
+  flowId: string;
+  stepKey: string;
+}
+
+/**
+ * What an authored step target means.
+ *
+ * Two spellings: `stepKey` alone acts on the nearest flow (context, then the
+ * default id), and `flowId:stepKey` names the flow outright — what a trigger
+ * outside every flow uses. An empty step is no target at all.
+ */
+export const resolveAuthStepTarget = (
+  target: string,
+  contextFlowId = ''
+): AuthStepTarget | null => {
+  const trimmed = target.trim();
+  if (!trimmed) return null;
+
+  const separator = trimmed.indexOf(':');
+
+  if (separator >= 0) {
+    const flowId = trimmed.slice(0, separator).trim();
+    const stepKey = trimmed.slice(separator + 1).trim();
+    if (!stepKey) return null;
+
+    return {
+      flowId: flowId || contextFlowId || DEFAULT_AUTH_FLOW_ID,
+      stepKey
+    };
+  }
+
+  return {
+    flowId: contextFlowId || DEFAULT_AUTH_FLOW_ID,
+    stepKey: trimmed
+  };
+};
+
+/** Test-only: drop all state so cases cannot leak into each other. */
+export const __resetAuthFlowBusForTests = (): void => {
+  flowStates = new Map();
+  if (pendingOtpTimer) clearTimeout(pendingOtpTimer);
+  pendingOtpTimer = null;
+  pendingOtp = null;
+  listeners.clear();
+  mountCounts.clear();
+};

package/src/auth/form-error-context.tsx

@@ -0,0 +1,55 @@
+'use client';
+
+import React from 'react';
+
+import type { Block } from '../theme-block';
+
+/**
+ * The one message a composed auth form is answering with right now.
+ *
+ * A form-level error has no field to sit under — it is about the submission,
+ * not about an input — so the form used to append it after everything it drew.
+ * In a composition that is the wrong place twice over: the CTA is one of the
+ * children, so the message landed BELOW the button that caused it, and the
+ * padding a composition puts on its own wrapper does not reach a node the form
+ * appends outside that wrapper, so the message also sat flush against the panel
+ * edge while every other line was inset.
+ *
+ * Neither is fixable from the form's side: it cannot know which child is the
+ * CTA, and it cannot know which wrapper carries the design's padding. What it
+ * does know is the message — so it publishes it here and an `auth-error` block
+ * draws it wherever the design says, inheriting that block's own spacing like
+ * any other. The form keeps its built-in node for the composition that has not
+ * placed one, so nothing goes silent.
+ *
+ * Both auth forms provide it: an OTP verification and an email login answer
+ * with the same kind of message and a composition should not care which one it
+ * is standing in.
+ */
+export const AuthFormErrorContext = React.createContext<string>('');
+
+export const AuthFormErrorProvider = AuthFormErrorContext.Provider;
+
+/** The form's current message, or '' — outside a form and while it is fine. */
+export const useAuthFormError = (): string =>
+  React.useContext(AuthFormErrorContext);
+
+/**
+ * Whether the blocks a form is ABOUT to draw contain an error block.
+ *
+ * Asked of the rendered subset rather than of every child, because the OTP form
+ * draws one phase at a time: an error block authored only inside the code phase
+ * must not silence the built-in message while the phone phase is up, or a
+ * shopper whose number was refused would be told nothing at all.
+ */
+export const containsAuthErrorBlock = (blocks: Block[] | undefined): boolean =>
+  (blocks || []).some(
+    (block) =>
+      // A hidden block draws nothing, so it cannot be the place the message
+      // goes. The forms filter their OWN children before asking, but the
+      // recursion did not — a Form Error tucked inside a Group and then hidden
+      // counted as authored, silenced the form's built-in message, and drew
+      // nothing itself. The shopper was told nothing at all.
+      !block.hidden &&
+      (block.type === 'auth-error' || containsAuthErrorBlock(block.blocks))
+  );