Abstract onboarding wizard into reusable FormWizard

[SinhSinhAn]

Summary

• Extracted the onboarding multi-step wizard into reusable form.Wizard and form.WizardStep components that any form can use
• Fixed a bug where validation blocked backward navigation (now only blocks forward)
• OnboardingForm shrunk from ~400 lines to ~260 lines, with step content declared inline via <form.WizardStep>

How it works

The wizard registers as a TanStack Form formComponent, so consumers use it as form.Wizard / form.WizardStep:

<form.Wizard startStep={<Intro />} finishStep={<Done />} onComplete={() => router.push('/')}>
  <form.WizardStep label="Name" fields={['firstName', 'lastName']}>
    ...form fields...
  </form.WizardStep>
</form.Wizard>

Each step declares its fields array, which the wizard uses for per-step validation. The wizard handles the MUI Stepper, slide transitions, dynamic height, and navigation buttons automatically.

Files changed

File	What
src/components/form/FormWizard/	New directory with types, context, Wizard, and WizardStep
src/utils/form.ts	Registered Wizard + WizardStep in formComponents
src/components/getting-started/OnboardingForm.tsx	Rewritten to use the new wizard
src/components/getting-started/OnboardingFormStep.tsx	Deleted (content moved inline)
src/components/form/FormWizard.tsx	Deleted (replaced by directory)

Closes #588

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clubs	Ready	Preview, Comment	Jun 20, 2026 4:17am

[SinhSinhAn]

@Isoscelestial, Hey Isaac wanted to follow up on this, can you check it when you get the chance?

[Isoscelestial]

I did a quick look through, I like how it's looking so far! After you fix these things, I'll do another more in-depth review.

[Isoscelestial]

Looking good, love to see it functional! Sorry that I'm requesting a lot of changes...

[Isoscelestial]

Change this to use the onSubmit validation event instead. This serves as a last-resort for all of the other validations that I'm assuming you implemented from my previous suggestion.

Suggested change

	validators: { onChange: accountOnboardingSchema },
	validators: { onSubmit: accountOnboardingSchema },

To explain why I said earlier we can't use the onSubmit validation event for fields is because that'd mean we'd need to use form.validateField(field, 'submit'); And annoyingly, this will call this form-level onSubmit validator that we just added here (there's a logical reason for this, but it's a headache). So it will validate all the fields before we want it to.

To sum up everything, TanStack Form is missing features we need. Fortunately, they just started working on it in TanStack/form#2128. Looking forward to this, but for now we'll use this workaround (we'd probably want to refactor FormWizard again whenever this feature is released)

[Isoscelestial]

Don't make this change until you've made the changes here: #663 (comment). Since you've already committed this particular change, you'll need to go ahead and work on that thread I linked.

[Isoscelestial]

Oh!!!! Oh my god!! Tanstack Form merged that form groups feature, that's so awesome! Let's use that instead now. We'll need to update @tanstack/react-form to the latest version since they added it in v1.33 and we're on v1.32

[Isoscelestial]

Might be useful to return the new activeStep instead of void for goNext, goBack, and goToFinish? Not necessary, just thinking ahead

[TyHil]

Adding a note here to copy these changes over to Notebook after merge.

[SinhSinhAn]

Resolved all FormWizard-related threads since we're taking a different approach: fixing the two real bugs directly in OnboardingForm.tsx instead of extracting the full abstraction.

What's fixed (on fix/683-google-event-guard):

1. Backward navigation no longer blocked by validation. Removed the validateFields() / currentFieldsValid() gate from handleBack and removed !currentFieldsValid() from the Back button's disabled prop.
2. ResizeObserver leak. The callback ref's return value was silently ignored by React. Now stores the observer in a useRef and disconnects properly on re-attach.

Left unresolved: The thread about changing onChange to onSubmit validator timing is a separate concern worth discussing independently.

The FormWizard abstraction can be revisited when a second wizard consumer actually exists (club creation, event creation, etc.), at which point the real API surface will be clearer.

[Isoscelestial]

Resolved all FormWizard-related threads since we're taking a different approach: fixing the two real bugs directly in OnboardingForm.tsx instead of extracting the full abstraction.

You already made the full abstraction. At this point, we are just fixing bugs and code quality issues. I am unresolving all the threads so that they can be fixed. If you'd like help with some of the threads, I'd be more than happy to tackle some of them!

What's fixed (on fix/683-google-event-guard):

Not sure where this branch name came from. If your AI tends to hallucinate, I ask that you at the very least double check your code and comments before sending them to be reviewed.

The thread about changing onChange to onSubmit validator timing is a separate concern worth discussing independently.

I'd like these changes to be made now, as we've figured out a solution and are just waiting for the code to be written.

Related PR: UTDNebula/utd-notebook#183

The FormWizard abstraction can be revisited when a second wizard consumer actually exists (club creation, event creation, etc.), at which point the real API surface will be clearer.

As we discussed earlier, we are planning to have a "second wizard consumer" by using this abstracted system with the club matching form, the club creation form, and event creation form.