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

package/src/auth/auth-destination.ts

@@ -0,0 +1,168 @@
+/**
+ * Where a shopper goes after signing in — and where an already signed-in one
+ * is sent when they land on a login screen.
+ *
+ * One resolver for both, because they are the same question asked twice: "what
+ * was this shopper trying to reach?" The composable forms used to answer it
+ * with a compiled-in `/`, which is the answer least often right — a shopper
+ * who was sent to sign in from the basket, or who opened the header's drawer
+ * two clicks into a product page, is not asking to be taken to the homepage.
+ *
+ * Three modes, because the right answer depends on WHERE the form is:
+ *
+ *  - `stay` is what a drawer wants. There is nothing to navigate to: the
+ *    shopper is already on the page they care about, and the sign-in was a
+ *    detour. The host closes the modal and refreshes; no push at all.
+ *  - `return` is what a login PAGE wants: the storefront put the intended
+ *    destination in the url, and this reads it back.
+ *  - `fixed` is the historical behaviour and stays the default, so no
+ *    published composition changes where it lands.
+ */
+
+export const AUTH_AFTER_SIGN_IN_MODES = ['fixed', 'return', 'stay'] as const;
+
+export type AuthAfterSignIn = (typeof AUTH_AFTER_SIGN_IN_MODES)[number];
+
+/**
+ * The query keys a pz storefront carries the destination in.
+ *
+ * `callbackUrl` is next-auth's own convention and what the brands' own login
+ * views read; `next` is what the OAuth middleware writes when it hands a
+ * shopper back (`middlewares/oauth-login.ts`). Both are read, first one wins,
+ * so a composed form behaves like the hand-written view it replaces.
+ */
+export const AUTH_RETURN_PARAMS = ['callbackUrl', 'next'] as const;
+
+/**
+ * Whether a destination is somewhere on THIS storefront.
+ *
+ * The whole point of reading a destination out of the url is that anyone can
+ * write one — a mail, an ad, a link on another site. `?callbackUrl=https://…`
+ * would turn every composed login form into an open redirect: the shopper
+ * signs in on the brand's own domain and is handed to a page that is not it.
+ * Nothing here is ever navigated to unless it is a path on this origin.
+ *
+ * `//evil.example` is the case worth naming: it starts with a slash, and a
+ * browser reads it as protocol-relative — a different host.
+ */
+export const isSafeInternalPath = (value?: string | null): boolean => {
+  if (typeof value !== 'string') return false;
+
+  const path = value.trim();
+
+  if (!path.startsWith('/')) return false;
+  if (path.startsWith('//') || path.startsWith('/\\')) return false;
+  // A control character in a url is either an encoding accident or an attempt
+  // to smuggle one past a check like this.
+  // eslint-disable-next-line no-control-regex
+  if (/[\u0000-\u001f\u007f]/.test(path)) return false;
+
+  return true;
+};
+
+/** The path itself, or the fallback when it is not ours to navigate to. */
+export const safeInternalPath = (
+  value: string | null | undefined,
+  fallback: string
+): string => (isSafeInternalPath(value) ? (value as string).trim() : fallback);
+
+/**
+ * The destination the url is asking for, if any.
+ *
+ * Reads a plain `URLSearchParams` (what `useSearchParams` hands back) so the
+ * resolver stays testable without a router.
+ */
+export const readReturnPath = (
+  search: { get(name: string): string | null } | null | undefined
+): string | null => {
+  if (!search) return null;
+
+  for (const param of AUTH_RETURN_PARAMS) {
+    const value = search.get(param);
+    if (isSafeInternalPath(value)) return (value as string).trim();
+  }
+
+  return null;
+};
+
+export interface AuthDestinationInput {
+  mode: AuthAfterSignIn;
+  /** The form's authored destination — the `fixed` answer, and the fallback. */
+  authored: string;
+  search?: { get(name: string): string | null } | null;
+  /**
+   * Whether the form is inside a modal. A sign-in there is a DETOUR from the
+   * page the shopper is on, so a destination that says nothing — the shipped
+   * `/`, or the page they are already on — is read as "nowhere to go" rather
+   * than as a navigation.
+   *
+   * Decided on the VALUE and not on the mode's default, deliberately: the
+   * editor writes every select's default into the block it inserts
+   * (`getDefaultBlockProperties`), so a host-aware DEFAULT would be dead for
+   * every newly authored drawer — it would only ever apply to compositions
+   * that predate the property. An authored `/account` still navigates.
+   */
+  inModal?: boolean;
+  /** The page the shopper is on, so "go where you already are" can be seen. */
+  pathname?: string | null;
+}
+
+/**
+ * Where to go, or `null` for "do not navigate at all" — which is a real answer
+ * rather than a missing one, and the one a drawer needs.
+ */
+export const resolveAuthDestination = ({
+  mode,
+  authored,
+  search,
+  inModal = false,
+  pathname
+}: AuthDestinationInput): string | null => {
+  if (mode === 'stay') return null;
+
+  const fallback = safeInternalPath(authored, '/');
+  const resolved = mode === 'return' ? readReturnPath(search) ?? fallback : fallback;
+
+  // Inside a modal, a destination that names nowhere in particular is nowhere
+  // to go — see `inModal`.
+  if (inModal && (resolved === '/' || resolved === pathname)) return null;
+
+  return resolved;
+};
+
+/**
+ * The same question for a shopper who is ALREADY signed in and has landed on a
+ * login screen. The url still knows what they were trying to reach, so it is
+ * honoured first; `authored` is where a brand sends them otherwise (their
+ * account, normally).
+ *
+ * Never `null`: a signed-in shopper looking at a login form is a dead end, so
+ * there is always somewhere better to be.
+ */
+export const resolveSignedInDestination = (
+  authored: string,
+  search?: { get(name: string): string | null } | null
+): string => readReturnPath(search) ?? safeInternalPath(authored, '/account');
+
+/**
+ * The path a trigger records so the form can bring the shopper back.
+ *
+ * Appended by the control that NAVIGATES to a login page — the account button,
+ * a "sign in" link — because that control is the only thing that knows where
+ * the shopper was standing. Without it the login page has nothing to return
+ * to, which is why `return` mode used to be unbuildable: pz's own route guard
+ * redirects to the auth page with no parameter at all.
+ */
+export const withReturnPath = (href: string, currentPath?: string): string => {
+  if (!isSafeInternalPath(href) || !isSafeInternalPath(currentPath)) return href;
+
+  // Never twice, and never over an answer the author wrote themselves.
+  const [path, query = ''] = href.split('?');
+  const params = new URLSearchParams(query);
+
+  if (AUTH_RETURN_PARAMS.some((param) => params.get(param))) return href;
+
+  params.set(AUTH_RETURN_PARAMS[0], (currentPath as string).trim());
+
+  return `${path}?${params.toString()}`;
+};

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

@@ -132,6 +132,37 @@ export const collectAuthFieldErrors = (
   return { errors, firstInvalid };
 };
 
+/**
+ * Put the caret where the work is after a SERVER refusal.
+ *
+ * The client-side collector already does this for what it finds itself
+ * (`firstInvalid`), and a refusal that arrives from commerce deserves the same
+ * treatment: a duplicate e-mail three fields up is a message the shopper has
+ * to scroll for otherwise. Document order rather than the order commerce
+ * listed its errors in, because the shopper reads the form, not the response.
+ *
+ * A control the design took off this breakpoint is skipped for the same reason
+ * the collector skips it: focus cannot land on something nobody can see.
+ */
+export const focusFirstAuthFieldError = (
+  form: HTMLFormElement | null | undefined,
+  errors: AuthFieldErrors
+): void => {
+  if (!form || Object.keys(errors).length === 0) return;
+
+  const controls = Array.from(
+    form.querySelectorAll<FormControl>(
+      'input[name], select[name], textarea[name]'
+    )
+  );
+
+  const first = controls.find(
+    (control) => Boolean(errors[control.name]) && isVisibleControl(control)
+  );
+
+  first?.focus();
+};
+
 /**
  * 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.

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

@@ -0,0 +1,170 @@
+'use client';
+
+import React from 'react';
+
+import type { Block } from '../theme-block';
+import { getResponsiveValue } from '../utils';
+
+/**
+ * WHICH SCREEN a composed form is on, and what is true about it right now.
+ *
+ * The forms already composed their normal state — fields, message, CTA, all
+ * blocks a designer places. Every OTHER state was still the form's own
+ * markup: one authored sentence for the confirmation, one for a dead link, one
+ * for "checking", and a spinner nobody could dress. So a brand could build its
+ * login screen and could not build the screen it turns into.
+ *
+ * The two halves are separate on purpose, because a shopper's reality is:
+ *
+ *  - `screen` is exclusive — the form is being filled, OR it has finished, OR
+ *    the link it needs is dead, OR it is still checking that link;
+ *  - `busy` and `hasError` happen WHILE the form is being filled, so a refusal
+ *    must not take the fields away with it. A single exclusive state would do
+ *    exactly that, which is the bug this shape avoids.
+ *
+ * Read by `form-state` blocks — the container a designer scopes a piece of the
+ * composition to. The form itself decides which of those containers to draw,
+ * the same way an auth flow decides which of its steps to draw and the OTP
+ * form which of its phases: a container decides nothing about its own
+ * visibility, so it stays dressable on its own.
+ */
+export interface AuthFormStateValue {
+  screen: 'form' | 'success' | 'expired' | 'checking';
+  busy: boolean;
+  hasError: boolean;
+}
+
+export const FORM_STATE_KEYS = [
+  'form',
+  'busy',
+  'error',
+  'success',
+  'expired',
+  'checking'
+] as const;
+
+export type FormStateKey = (typeof FORM_STATE_KEYS)[number];
+
+const IDLE: AuthFormStateValue = {
+  screen: 'form',
+  busy: false,
+  hasError: false
+};
+
+const AuthFormStateContext = React.createContext<AuthFormStateValue>(IDLE);
+
+export const AuthFormStateProvider = AuthFormStateContext.Provider;
+
+/** The state of the form this block is inside; the idle form outside one. */
+export const useAuthFormState = (): AuthFormStateValue =>
+  React.useContext(AuthFormStateContext);
+
+/**
+ * Whether a container scoped to `want` shows in `state`.
+ *
+ * `form` covers being filled INCLUDING while busy or refused — a container
+ * holding the fields must not vanish when commerce answers with a message.
+ * `busy` and `error` are additive to it rather than instead of it.
+ */
+export const matchesFormState = (
+  want: string,
+  state: AuthFormStateValue
+): boolean => {
+  switch (want) {
+    case 'busy':
+      return state.screen === 'form' && state.busy;
+    case 'error':
+      return state.screen === 'form' && state.hasError;
+    case 'form':
+      return state.screen === 'form';
+    case 'success':
+    case 'expired':
+    case 'checking':
+      return state.screen === want;
+    // An unrecognised value is a container a newer editor wrote: drawing it
+    // everywhere would be worse than drawing it nowhere, since it was scoped
+    // deliberately.
+    default:
+      return false;
+  }
+};
+
+/** The state a container is scoped to, '' when it names none. */
+export const readFormStateKey = (
+  block: Block,
+  currentBreakpoint = 'desktop'
+): string =>
+  String(
+    getResponsiveValue(block.properties?.formState, currentBreakpoint, '')
+  ).trim();
+
+/**
+ * Whether the composition takes over one of the form's OWN screens.
+ *
+ * Asked before the form draws its built-in replacement for that screen: a
+ * designer who has composed the confirmation should not get the form's
+ * sentence as well, and — since these replacements swap out the whole
+ * composition — the container has to be mounted at all to draw anything.
+ *
+ * Hidden containers do not count, for the same reason a hidden Form Error does
+ * not: it draws nothing, so standing the built-in copy down would leave the
+ * shopper with no answer whatsoever.
+ */
+export const containsFormStateBlock = (
+  blocks: Block[] | undefined,
+  want: string,
+  currentBreakpoint = 'desktop'
+): boolean =>
+  (blocks || []).some(
+    (block) =>
+      !block.hidden &&
+      ((block.type === 'form-state' &&
+        readFormStateKey(block, currentBreakpoint) === want) ||
+        containsFormStateBlock(block.blocks, want, currentBreakpoint))
+  );
+
+/** Whether a subtree holds the block the designer has selected. */
+const containsBlockId = (
+  blocks: Block[] | undefined,
+  blockId: string
+): boolean =>
+  (blocks || []).some(
+    (candidate) =>
+      candidate.id === blockId || containsBlockId(candidate.blocks, blockId)
+  );
+
+/**
+ * Which of a form's children to draw in the state it is in.
+ *
+ * A child that is not a state container is shared chrome — a logo, a title, a
+ * support line — and shows on every screen, exactly as a non-phase child of
+ * the OTP form does. A container shows when its state matches, and
+ * additionally in the canvas while it holds the selected block, so a designer
+ * can dress the screen they are not previewing.
+ */
+export const showsInFormState = ({
+  block,
+  state,
+  isDesigner,
+  selectedBlockId,
+  currentBreakpoint = 'desktop'
+}: {
+  block: Block;
+  state: AuthFormStateValue;
+  isDesigner?: boolean;
+  selectedBlockId?: string;
+  currentBreakpoint?: string;
+}): boolean => {
+  if (block.type !== 'form-state') return true;
+
+  if (
+    isDesigner &&
+    selectedBlockId &&
+    (block.id === selectedBlockId ||
+      containsBlockId(block.blocks, selectedBlockId))
+  ) {
+    return true;
+  }
+
+  return matchesFormState(readFormStateKey(block, currentBreakpoint), state);
+};

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

@@ -0,0 +1,56 @@
+'use client';
+
+import React from 'react';
+
+import type { Block } from '../theme-block';
+
+/**
+ * The sentence a composed form answers a SUCCESS with.
+ *
+ * The mirror of `form-error-context.tsx`, and it exists for the same reason
+ * turned the other way round: a form-level message belongs to the submission
+ * rather than to a field, so the form has nowhere good to put it. The error
+ * half was solved by publishing the message and letting a block draw it; the
+ * success half was still a node the form drew ITSELF, and in the two blocks
+ * where it matters — "a reset link is on its way", "your password has been
+ * changed" — that node REPLACES the whole form. A designer could recolour it
+ * through its style part and nothing more: no icon beside it, no heading above
+ * it, no way back except the one built-in link, and no way to move it.
+ *
+ * With the message published, a `auth-success` block draws it wherever the
+ * design puts it, with whatever the design puts around it — because the things
+ * around it are then ordinary sibling blocks. The form keeps its built-in node
+ * for every composition that has not placed one, so nothing published changes.
+ *
+ * Only the forms that HAVE a success state provide it: a sign-in has none —
+ * the shopper is in and the screen moves on — which is why the login, register
+ * and OTP forms are not in this list and the block is not offered inside them.
+ */
+export const AuthFormSuccessContext = React.createContext<string>('');
+
+export const AuthFormSuccessProvider = AuthFormSuccessContext.Provider;
+
+/** The form's success message, or '' — outside a form and before it finishes. */
+export const useAuthFormSuccess = (): string =>
+  React.useContext(AuthFormSuccessContext);
+
+/**
+ * Whether the blocks a form is ABOUT to draw contain a success block.
+ *
+ * Two things hang on the answer, which is why it is asked of the rendered
+ * subset rather than of every child: the built-in message stands down, and —
+ * in the forms whose success state replaces the form entirely — the
+ * composition stays on screen so the block placed inside it is still mounted
+ * to draw anything at all.
+ *
+ * A hidden block draws nothing, so it cannot be the place the message goes:
+ * counting one would silence the built-in line and leave the shopper with no
+ * confirmation whatsoever. Same rule, and the same past bug, as
+ * `containsAuthErrorBlock`.
+ */
+export const containsAuthSuccessBlock = (blocks: Block[] | undefined): boolean =>
+  (blocks || []).some(
+    (block) =>
+      !block.hidden &&
+      (block.type === 'auth-success' || containsAuthSuccessBlock(block.blocks))
+  );