Build the register form as three steps

web/frontend/app/features/auth/components/LoginCallout.tsx

@@ -1,18 +0,0 @@
-import { Link } from 'react-router';
-
-const LoginCallout = () => (
-    <>
-        <div className="divider text-xs">Already have an account?</div>
-
-        <div className="text-center space-y-2">
-            <Link to="/login" className="btn btn-outline btn-sm w-full">
-                Sign in
-            </Link>
-            <Link to="/" className="link link-hover text-sm text-base-content/70">
-                Back to home
-            </Link>
-        </div>
-    </>
-);
-
-export default LoginCallout;

web/frontend/app/features/auth/components/RegisterForm.stories.tsx

@@ -1,25 +1,30 @@
-import { zodResolver } from '@hookform/resolvers/zod';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useState } from 'react';
-import { useForm } from 'react-hook-form';
 import { expect, fireEvent, userEvent, within } from 'storybook/test';
+import AuthCardHeading from './AuthCardHeading';
 import RegisterForm from './RegisterForm';
-import { registerSchema, type RegisterSchema } from '../schemas';
+import RegisterStepProgress from './RegisterStepProgress';
+import { useRegisterWizard } from '../hooks/useRegisterWizard';
+import { type RegisterSchema } from '../schemas';
 
-const registerFormDescription = `Renders the real \`RegisterForm\` component wired to the real \`registerSchema\` (zod) through the same react-hook-form setup used on the register page, including its cross-field rule that the confirmation must match the password, so these stories validate actual client-side validation behavior rather than a re-implemented form.`;
+const registerFormDescription = `Renders the real \`RegisterForm\` driven by the real \`useRegisterWizard\` hook, so these stories exercise the production three-step flow: each step validates its own fields through \`registerSchema\` (zod) before the next one opens, entered values survive going back, and only the final step submits.`;
 
 const RegisterFormHarness = () => {
     const [submitted, setSubmitted] = useState<RegisterSchema | null>(null);
-    const form = useForm<RegisterSchema>({ resolver: zodResolver(registerSchema) });
+    const wizard = useRegisterWizard(setSubmitted);
 
     return (
-        <div className="w-full max-w-lg space-y-3 rounded-box bg-base-100 p-6 shadow-lg">
-            <RegisterForm
-                onSubmit={form.handleSubmit((values) => setSubmitted(values))}
-                formState={form.formState}
-                register={form.register}
-                submitting={false}
+        <div className="flex w-full max-w-md flex-col gap-4 rounded-box bg-base-100 p-6 shadow-lg">
+            <RegisterStepProgress
+                step={wizard.step}
+                totalSteps={wizard.totalSteps}
+                name={wizard.name}
             />
+
+            <AuthCardHeading title={wizard.title} subtitle={wizard.subtitle} />
+
+            <RegisterForm wizard={wizard} submitting={false} />
+
             {submitted ? <p data-testid="submit-result">Registered {submitted.username}</p> : null}
         </div>
     );
@@ -42,75 +47,120 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-export const Empty: Story = {};
+type Canvas = ReturnType<typeof within>;
 
-const fillValidRegistration = async (canvas: ReturnType<typeof within>) => {
+const adultDateOfBirth = '2000-01-15';
+
+const underageDateOfBirth = () => {
+    const tenYearsAgo = new Date();
+    tenYearsAgo.setFullYear(tenYearsAgo.getFullYear() - 10);
+    return tenYearsAgo.toISOString().slice(0, 10);
+};
+
+const completeAccountStep = async (canvas: Canvas) => {
     await userEvent.type(canvas.getByLabelText(/^username$/i), 'jane_doe');
+    await userEvent.type(canvas.getByLabelText(/^email$/i), 'jane@example.com');
+    await userEvent.click(canvas.getByRole('button', { name: /continue/i }));
+    await canvas.findByLabelText(/first name/i);
+};
+
+const completeDetailsStep = async (canvas: Canvas, dateOfBirth = adultDateOfBirth) => {
     await userEvent.type(canvas.getByLabelText(/first name/i), 'Jane');
     await userEvent.type(canvas.getByLabelText(/last name/i), 'Doe');
-    await userEvent.type(canvas.getByLabelText(/^email$/i), 'jane@example.com');
     await fireEvent.change(canvas.getByLabelText(/date of birth/i), {
-        target: { value: '2000-01-15' },
+        target: { value: dateOfBirth },
     });
-    await userEvent.type(canvas.getByLabelText('Password'), 'StrongPass1!');
-    await userEvent.type(canvas.getByLabelText(/confirm password/i), 'StrongPass1!');
+    await userEvent.click(canvas.getByRole('button', { name: /continue/i }));
 };
 
-export const RejectsEmptySubmission: Story = {
+export const Empty: Story = {};
+
+export const BlocksAdvanceOnInvalidAccount: Story = {
     play: async ({ canvasElement }) => {
         const canvas = within(canvasElement);
-        await userEvent.click(canvas.getByRole('button', { name: /create account/i }));
+        await userEvent.click(canvas.getByRole('button', { name: /continue/i }));
         await expect(
-            canvas.getByText(/username must be at least 3 characters/i),
+            await canvas.findByText(/username must be at least 3 characters/i),
         ).toBeInTheDocument();
-        await expect(canvas.getByText(/first name is required/i)).toBeInTheDocument();
-        await expect(canvas.queryByTestId('submit-result')).not.toBeInTheDocument();
-    },
-};
-
-export const RejectsInvalidEmail: Story = {
-    play: async ({ canvasElement }) => {
-        const canvas = within(canvasElement);
-        await fillValidRegistration(canvas);
-        await userEvent.clear(canvas.getByLabelText(/^email$/i));
-        await userEvent.type(canvas.getByLabelText(/^email$/i), 'jane@example');
-        await userEvent.click(canvas.getByRole('button', { name: /create account/i }));
         await expect(canvas.getByText(/invalid email address/i)).toBeInTheDocument();
-        await expect(canvas.queryByTestId('submit-result')).not.toBeInTheDocument();
+        await expect(canvas.getByText(/step 1 of 3/i)).toBeInTheDocument();
     },
 };
 
-export const RejectsWeakPassword: Story = {
+export const ClearsFieldErrorOnEdit: Story = {
     play: async ({ canvasElement }) => {
         const canvas = within(canvasElement);
-        await fillValidRegistration(canvas);
-        await userEvent.clear(canvas.getByLabelText('Password'));
-        await userEvent.type(canvas.getByLabelText('Password'), 'weakpassword');
-        await userEvent.clear(canvas.getByLabelText(/confirm password/i));
-        await userEvent.type(canvas.getByLabelText(/confirm password/i), 'weakpassword');
-        await userEvent.click(canvas.getByRole('button', { name: /create account/i }));
-        await expect(canvas.getByText(/uppercase letter/i)).toBeInTheDocument();
-        await expect(canvas.queryByTestId('submit-result')).not.toBeInTheDocument();
+        await userEvent.click(canvas.getByRole('button', { name: /continue/i }));
+        await canvas.findByText(/username must be at least 3 characters/i);
+
+        await userEvent.type(canvas.getByLabelText(/^username$/i), 'jane_doe');
+        await expect(
+            canvas.queryByText(/username must be at least 3 characters/i),
+        ).not.toBeInTheDocument();
+    },
+};
+
+export const AdvancesToPersonalDetails: Story = {
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await completeAccountStep(canvas);
+        await expect(canvas.getByRole('heading', { name: 'About you' })).toBeInTheDocument();
+        await expect(canvas.getByText(/step 2 of 3 · personal details/i)).toBeInTheDocument();
+    },
+};
+
+export const KeepsValuesWhenGoingBack: Story = {
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await completeAccountStep(canvas);
+        await userEvent.click(canvas.getByRole('button', { name: /back/i }));
+        await expect(await canvas.findByLabelText(/^username$/i)).toHaveValue('jane_doe');
+        await expect(canvas.getByLabelText(/^email$/i)).toHaveValue('jane@example.com');
+    },
+};
+
+export const RejectsUnderageDateOfBirth: Story = {
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await completeAccountStep(canvas);
+        await completeDetailsStep(canvas, underageDateOfBirth());
+        await expect(await canvas.findByText(/at least 19 years old/i)).toBeInTheDocument();
+        await expect(canvas.getByText(/step 2 of 3/i)).toBeInTheDocument();
     },
 };
 
 export const RejectsMismatchedConfirmPassword: Story = {
     play: async ({ canvasElement }) => {
         const canvas = within(canvasElement);
-        await fillValidRegistration(canvas);
-        await userEvent.clear(canvas.getByLabelText(/confirm password/i));
+        await completeAccountStep(canvas);
+        await completeDetailsStep(canvas);
+        await userEvent.type(await canvas.findByLabelText('Password'), 'StrongPass1!');
         await userEvent.type(canvas.getByLabelText(/confirm password/i), 'Different1!');
         await userEvent.click(canvas.getByRole('button', { name: /create account/i }));
-        await expect(canvas.getByText(/passwords must match/i)).toBeInTheDocument();
+        await expect(await canvas.findByText(/passwords must match/i)).toBeInTheDocument();
         await expect(canvas.queryByTestId('submit-result')).not.toBeInTheDocument();
     },
 };
 
+export const RevealsBothPasswords: Story = {
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await completeAccountStep(canvas);
+        await completeDetailsStep(canvas);
+        await userEvent.click(await canvas.findByRole('button', { name: /show password/i }));
+        await expect(canvas.getByLabelText('Password')).toHaveAttribute('type', 'text');
+        await expect(canvas.getByLabelText(/confirm password/i)).toHaveAttribute('type', 'text');
+    },
+};
+
 export const AcceptsValidRegistration: Story = {
     play: async ({ canvasElement }) => {
         const canvas = within(canvasElement);
-        await fillValidRegistration(canvas);
+        await completeAccountStep(canvas);
+        await completeDetailsStep(canvas);
+        await userEvent.type(await canvas.findByLabelText('Password'), 'StrongPass1!');
+        await userEvent.type(canvas.getByLabelText(/confirm password/i), 'StrongPass1!');
         await userEvent.click(canvas.getByRole('button', { name: /create account/i }));
-        await expect(canvas.getByTestId('submit-result')).toHaveTextContent('jane_doe');
+        await expect(await canvas.findByTestId('submit-result')).toHaveTextContent('jane_doe');
     },
 };

web/frontend/app/features/auth/components/RegisterForm.tsx

@@ -1,97 +1,129 @@
-import { BaseSyntheticEvent } from 'react';
-import { FormState, UseFormRegister } from 'react-hook-form';
+import { Button } from '@headlessui/react';
+import { useState } from 'react';
 import FormField from '../../../components/ui/forms/FormField';
 import SubmitButton from '../../../components/ui/forms/SubmitButton';
-import type { RegisterSchema } from '../schemas';
+import type { RegisterWizard } from '../hooks/useRegisterWizard';
+import { minimumAgeYears } from '../schemas';
+import ShowPasswordToggle from './ShowPasswordToggle';
 
 interface RegisterFormProps {
-    onSubmit: (e?: BaseSyntheticEvent) => Promise<Awaited<void> | undefined>;
-    formState: FormState<RegisterSchema>;
-    register: UseFormRegister<RegisterSchema>;
+    wizard: RegisterWizard;
     submitting: boolean;
 }
 
-const RegisterForm = (props: RegisterFormProps) => (
-    <form onSubmit={props.onSubmit} className="space-y-3">
+const RegisterForm = ({ wizard, submitting }: RegisterFormProps) => {
+    const [showPassword, setShowPassword] = useState(false);
+    const { step, isLastStep, canGoBack, register, formState } = wizard;
+    const { errors } = formState;
+
+    return (
+        <form onSubmit={wizard.onSubmit} className="flex flex-col gap-4" noValidate>
+            {step === 1 && (
+                <div className="flex flex-col gap-4">
                     <FormField
                         id="username"
                         type="text"
                         autoComplete="username"
-            placeholder="your_username"
                         label="Username"
                         hint="3-64 characters, alphanumeric and . _ -"
-            error={props.formState.errors.username?.message}
-            {...props.register('username')}
+                        error={errors.username?.message}
+                        {...register('username')}
                     />
 
-        <div className="grid grid-cols-2 gap-3">
+                    <FormField
+                        id="email"
+                        type="email"
+                        autoComplete="email"
+                        label="Email"
+                        error={errors.email?.message}
+                        {...register('email')}
+                    />
+                </div>
+            )}
+
+            {step === 2 && (
+                <div className="flex flex-col gap-4">
+                    <div className="grid grid-cols-1 gap-3.5 min-[420px]:grid-cols-2">
                         <FormField
                             id="firstName"
                             type="text"
                             autoComplete="given-name"
-                placeholder="Jane"
-                label="First Name"
-                error={props.formState.errors.firstName?.message}
-                {...props.register('firstName')}
+                            label="First name"
+                            error={errors.firstName?.message}
+                            {...register('firstName')}
                         />
 
                         <FormField
                             id="lastName"
                             type="text"
                             autoComplete="family-name"
-                placeholder="Doe"
-                label="Last Name"
-                error={props.formState.errors.lastName?.message}
-                {...props.register('lastName')}
+                            label="Last name"
+                            error={errors.lastName?.message}
+                            {...register('lastName')}
                         />
                     </div>
 
-        <FormField
-            id="email"
-            type="email"
-            autoComplete="email"
-            placeholder="jane@example.com"
-            label="Email"
-            error={props.formState.errors.email?.message}
-            {...props.register('email')}
-        />
-
                     <FormField
                         id="dateOfBirth"
                         type="date"
-            label="Date of Birth"
-            hint="Must be 19 years or older"
-            error={props.formState.errors.dateOfBirth?.message}
-            {...props.register('dateOfBirth')}
+                        label="Date of birth"
+                        hint={`Must be ${minimumAgeYears} years or older.`}
+                        error={errors.dateOfBirth?.message}
+                        {...register('dateOfBirth')}
                     />
+                </div>
+            )}
 
+            {step === 3 && (
+                <div className="flex flex-col gap-4">
                     <FormField
                         id="password"
-            type="password"
+                        type={showPassword ? 'text' : 'password'}
                         autoComplete="new-password"
-            placeholder="••••••••"
                         label="Password"
                         hint="8+ chars: uppercase, lowercase, digit, special character"
-            error={props.formState.errors.password?.message}
-            {...props.register('password')}
+                        error={errors.password?.message}
+                        {...register('password')}
                     />
 
                     <FormField
                         id="confirmPassword"
-            type="password"
+                        type={showPassword ? 'text' : 'password'}
                         autoComplete="new-password"
-            placeholder="••••••••"
-            label="Confirm Password"
-            error={props.formState.errors.confirmPassword?.message}
-            {...props.register('confirmPassword')}
+                        label="Confirm password"
+                        error={errors.confirmPassword?.message}
+                        {...register('confirmPassword')}
                     />
 
-        <SubmitButton
-            isSubmitting={props.submitting}
-            idleText="Create Account"
-            submittingText="Creating account..."
+                    <ShowPasswordToggle
+                        shown={showPassword}
+                        onToggle={() => setShowPassword((shown) => !shown)}
                     />
+                </div>
+            )}
+
+            <div className="flex gap-3">
+                {canGoBack && (
+                    <Button
+                        type="button"
+                        onClick={wizard.back}
+                        className="btn btn-outline min-h-12"
+                    >
+                        Back
+                    </Button>
+                )}
+
+                <div className="flex-1">
+                    <SubmitButton
+                        isSubmitting={submitting}
+                        idleText={isLastStep ? 'Create account' : 'Continue'}
+                        submittingText="Creating account…"
+                        className="btn btn-primary min-h-12 w-full"
+                    />
+                </div>
+            </div>
         </form>
-);
+    );
+};
 
 export default RegisterForm;

web/frontend/app/features/auth/components/RegisterStepProgress.tsx

@@ -0,0 +1,24 @@
+interface RegisterStepProgressProps {
+    step: number;
+    totalSteps: number;
+    name: string;
+}
+
+const RegisterStepProgress = ({ step, totalSteps, name }: RegisterStepProgressProps) => (
+    <div className="flex flex-col gap-2">
+        <div className="flex gap-1.5" aria-hidden="true">
+            {Array.from({ length: totalSteps }, (_, index) => (
+                <div
+                    key={index}
+                    className={`h-1 flex-1 rounded ${index < step ? 'bg-primary' : 'bg-base-300'}`}
+                />
+            ))}
+        </div>
+
+        <p className="text-[0.8125rem] font-semibold text-[var(--color-muted)]">
+            Step {step} of {totalSteps} · {name}
+        </p>
+    </div>
+);
+
+export default RegisterStepProgress;

web/frontend/app/features/auth/hooks/useRegisterWizard.ts

@@ -0,0 +1,74 @@
+import { zodResolver } from '@hookform/resolvers/zod';
+import { useState } from 'react';
+import { useForm, type FieldErrors, type Resolver } from 'react-hook-form';
+import { earliestStepForFields, lastRegisterStepIndex, registerSteps } from '../registerSteps';
+import { registerSchema, type RegisterSchema } from '../schemas';
+
+const resolveRegisterSchema = zodResolver(registerSchema);
+
+/**
+ * Drives the multi-step register form: one react-hook-form instance spans every
+ * step so values survive going back and forward, and each step validates its own
+ * fields before the next one opens.
+ */
+export const useRegisterWizard = (onValid: (values: RegisterSchema) => void) => {
+    const [stepIndex, setStepIndex] = useState(0);
+
+    const currentStep = registerSteps[stepIndex];
+    const isLastStep = stepIndex === lastRegisterStepIndex;
+
+    // Every step submits through `handleSubmit`, so each one has to report only its
+    // own fields: resolve the whole schema, then keep the errors this step owns. The
+    // last step keeps all of them, which is also what runs the password-match
+    // refinement across steps.
+    const resolver: Resolver<RegisterSchema> = async (values, context, options) => {
+        const result = await resolveRegisterSchema(values, context, options);
+        if (isLastStep) return result;
+
+        const errors = Object.fromEntries(
+            Object.entries(result.errors).filter(([name]) =>
+                currentStep.fields.includes(name as keyof RegisterSchema),
+            ),
+        ) as FieldErrors<RegisterSchema>;
+
+        return Object.keys(errors).length ? { values: {}, errors } : { values, errors: {} };
+    };
+
+    const { register, handleSubmit, formState } = useForm<RegisterSchema>({
+        resolver,
+        mode: 'onTouched',
+    });
+
+    const onSubmit = handleSubmit(
+        (values) => {
+            if (isLastStep) {
+                onValid(values);
+                return;
+            }
+
+            setStepIndex((index) => index + 1);
+        },
+        // The last step validates fields from earlier steps too, so open whichever
+        // step owns the problem rather than reporting it out of sight.
+        (errors: FieldErrors<RegisterSchema>) => {
+            const step = earliestStepForFields(Object.keys(errors) as (keyof RegisterSchema)[]);
+            if (step !== null) setStepIndex(step);
+        },
+    );
+
+    return {
+        step: stepIndex + 1,
+        totalSteps: registerSteps.length,
+        name: currentStep.name,
+        title: currentStep.title,
+        subtitle: currentStep.subtitle,
+        isLastStep,
+        canGoBack: stepIndex > 0,
+        back: () => setStepIndex((index) => Math.max(index - 1, 0)),
+        onSubmit,
+        register,
+        formState,
+    };
+};
+
+export type RegisterWizard = ReturnType<typeof useRegisterWizard>;

web/frontend/app/features/auth/routes/register.tsx

@@ -1,11 +1,15 @@
-import { zodResolver } from '@hookform/resolvers/zod';
-import { useForm } from 'react-hook-form';
 import { redirect, useNavigation, useSubmit } from 'react-router';
+import { z } from 'zod';
 import { createAuthSession, getOptionalAuth, register } from '../auth.server';
-import LoginCallout from '../components/LoginCallout';
+import AuthCardHeading from '../components/AuthCardHeading';
+import AuthErrorAlert from '../components/AuthErrorAlert';
+import AuthSplitLayout from '../components/AuthSplitLayout';
+import AuthSwitchPrompt from '../components/AuthSwitchPrompt';
 import RegisterForm from '../components/RegisterForm';
+import RegisterStepProgress from '../components/RegisterStepProgress';
 import { useActionErrorToast } from '../hooks/useActionErrorToast';
-import { registerSchema, type RegisterSchema } from '../schemas';
+import { useRegisterWizard } from '../hooks/useRegisterWizard';
+import { registerSchema } from '../schemas';
 import type { Route } from './+types/register';
 
 export const meta = ({}: Route.MetaArgs) => {
@@ -20,33 +24,14 @@ export const loader = async ({ request }: Route.LoaderArgs) => {
 
 export const action = async ({ request }: Route.ActionArgs) => {
     const formData = await request.formData();
-    const result = registerSchema.safeParse({
-        username: formData.get('username'),
-        firstName: formData.get('firstName'),
-        lastName: formData.get('lastName'),
-        email: formData.get('email'),
-        dateOfBirth: formData.get('dateOfBirth'),
-        password: formData.get('password'),
-        confirmPassword: formData.get('confirmPassword'),
-    });
+    const result = registerSchema.safeParse(Object.fromEntries(formData));
 
     if (!result.success) {
-        const fieldErrors = result.error.flatten().fieldErrors as Record<
-            keyof RegisterSchema,
-            string[] | undefined
-        >;
-        return { error: null, fieldErrors };
+        return { error: null, fieldErrors: z.flattenError(result.error).fieldErrors };
     }
 
     try {
-        const body = {
-            username: result.data.username,
-            firstName: result.data.firstName,
-            lastName: result.data.lastName,
-            email: result.data.email,
-            dateOfBirth: result.data.dateOfBirth,
-            password: result.data.password,
-        };
+        const { confirmPassword: _confirmPassword, ...body } = result.data;
         const payload = await register(body);
         return createAuthSession(payload, '/dashboard');
     } catch (err) {
@@ -62,44 +47,31 @@ const Register = ({ actionData }: Route.ComponentProps) => {
     const submit = useSubmit();
     const isSubmitting = navigation.state === 'submitting';
 
-    const {
-        register: field,
-        handleSubmit,
-        formState,
-    } = useForm<RegisterSchema>({ resolver: zodResolver(registerSchema) });
-
-    const onSubmit = handleSubmit((data) => {
+    const wizard = useRegisterWizard((data) => {
         submit(data, { method: 'post' });
     });
 
     useActionErrorToast(actionData?.error);
 
     return (
-        <div className="min-h-screen bg-base-200 flex items-center justify-center p-4">
-            <div className="card w-full max-w-lg bg-base-100 shadow-xl">
-                <div className="card-body gap-4">
-                    <div className="text-center">
-                        <h1 className="card-title text-3xl justify-center">Register</h1>
-                        <p className="text-base-content/70">Create your Biergarten account</p>
-                    </div>
-
-                    {actionData?.error && (
-                        <div role="alert" className="alert alert-error alert-soft">
-                            <span>{actionData.error}</span>
-                        </div>
-                    )}
-
-                    <RegisterForm
-                        onSubmit={onSubmit}
-                        formState={formState}
-                        register={field}
-                        submitting={isSubmitting}
+        <AuthSplitLayout
+            headline="Pull up a chair."
+            blurb="Create an account to explore partner breweries and their beers."
+        >
+            <RegisterStepProgress
+                step={wizard.step}
+                totalSteps={wizard.totalSteps}
+                name={wizard.name}
             />
 
-                    <LoginCallout />
-                </div>
-            </div>
-        </div>
+            <AuthCardHeading title={wizard.title} subtitle={wizard.subtitle} />
+
+            {actionData?.error && <AuthErrorAlert message={actionData.error} />}
+
+            <RegisterForm wizard={wizard} submitting={isSubmitting} />
+
+            <AuthSwitchPrompt lead="Already have an account?" to="/login" label="Sign in" />
+        </AuthSplitLayout>
     );
 };