Onboarding — Behavior

State

OnboardJS owns the state via its OnboardingProvider. The shape (SetupWizardContext) is:

type SetupWizardContext = {
  flowData: {
    orgName: string;
    deliveryModes: Array<'schedule' | 'coaching'>;
    programNames: Partial<Record<'schedule' | 'coaching', string>>;
    legalConsentsAccepted: boolean;
  };
}

Persisted to localStorage under key taikan:setup-sheet-v5 with 7-day TTL. The engine has a single step (SETUP_SHEET_STEP_ID = 'sheet', a component that renders nothing), so there is no “current step” to restore: a refresh restores the answers and the sheet recomputes everything else from them.

legalConsentsAccepted is the one field that is never trusted from persistence. LegalStep keeps its own accepted state, starts it at false, and mirrors it into flowData. After a reload the checkbox renders unticked, so a restored true is overwritten with false and consent is never recorded for a box nobody can see ticked.

Sections

All three sections render at once, in this order, inside one <form>.

No conditional/skippable branches. Every org sees all three sections and none can be skipped.

Missing items and marker states

getMissingSetupItems(flowData) (apps/web/src/lib/onboarding/setup-sheet-state.ts) returns what is still needed, in reading order: name, then train or programName, then legal. programName is separate from train so the footer can ask for “a name for your first program” instead of repeating “how you train” to someone who has already ticked a tile. A missing context counts as an untouched sheet.

Each section’s rail marker (StepMarker) derives from that list:

The state is also exposed as data-state on setup-section-{org,train,legal}. Sections are not locked by their state: an upcoming section is fully editable.

Headline, footer and submit

• The headline (setup-sheet-headline) interpolates the trimmed gym name, falling back to a generic phrase until one is typed. Long names wrap and clamp at three lines.
• The sticky footer shows one of two things in the same slot, beside the submit button:
  • the status line (setup-sheet-status, aria-live="polite"): “Still needed:” followed by the missing items, joined with the locale’s own separators and conjunction via Intl.ListFormat. Each item is a button. When nothing is missing it reads as ready.
  • the error (setup-sheet-error, role="alert") after a failed submit. It replaces the status line.
• Clicking a missing item scrolls its field to the centre (smooth, or instant under prefers-reduced-motion) and focuses it: name → the gym name input; programName → the name input of the first unnamed ticked mode; train and legal → the first button or input inside that section.
• The submit button (setup-sheet-submit) is aria-disabled and drawn as ink on a quiet surface until nothing is missing; clicking it in that state moves focus to the first missing item instead of submitting. It is natively disabled only while submitting. Its label is “Open {name}” once a name is typed, a generic label before that, and a pending label with a spinner while submitting.
• Enter in a text field submits the form natively. With something still missing, that moves focus to the first missing item; with nothing missing it creates the gym. Enter on the tiles, radio items and checkbox keeps its native behavior.
• While submitting, the whole form is a disabled <fieldset> with aria-busy. Pending stays on through the navigation to the dashboard so the sheet cannot be submitted twice in the moment before the dashboard paints.

Invariants

• Sheet is unreachable with existing memberships — unless an owner grant is pending: server-side redirect() in the page component. /users/me.canCreateOrganization === true (a claimable owner grant, see below) lifts the redirect so a member of gym A can open the sheet to become owner of gym B.
• An owner grant is required to create an organization: POST /organizations answers 403 OWNER_INVITATION_REQUIRED unless the caller can claim a pending owner_invitations row. One grant creates exactly one organization; the claim, the Clerk org, the org row, the owner membership and the grant’s consumed flip happen in one DB transaction behind a SELECT … FOR UPDATE. Platform admins issue grants (Admin → Owner Invitations; runbook: docs/runbooks/owner-invitations.md).
• No grant, no sheet: a signed-in user with no memberships and no claimable grant is routed to /{lang}/invitation-required (shows their email, a mailto:[email protected] contact link and sign-out) by the (protected) layout, RoleRouter and the onboarding page guard. Course-viewer paths (/library, /buy) keep their exemption, and an account that owns a course (/users/me ownsCourses) is sent to /{lang}/library instead: its home is the courses it bought. An owner grant takes precedence over both.
• Sheet is unreachable without auth: (protected) route group enforces Clerk sign-in.
• OnboardJS persistence is local-only: no server-side resumption; if the user clears localStorage they restart.
• Nothing is written before submit: until handleSubmit runs, no org row exists. The sections only update OnboardJS context.
• A retry never duplicates the organization: handleSubmit remembers the created org id and whether consents were recorded (createdOrgIdRef, consentsRecordedRef). A retry after a partial failure skips the calls that already succeeded. The memory is in-component, so it does not survive a page reload.
• Restored consent is never trusted: see State above.
• Legal acceptance writes one consent row per document type in OWNER_LEGAL_DOC_TYPES (terms_of_use today).

Golden path

Setup guide

SetupGuide (apps/web/src/components/overview/setup-guide.tsx) continues the sheet inside the dashboard. It renders on Overview (under the page guide) and on /dashboard/home for owner/admin. All data comes from useGettingStarted (hooks/use-getting-started.ts).

Steps

* Never for online orgs (compliance forms are off there). Not tier-gated. It sits before inviteMember because a form auto-issued on join reaches only people who join after it is published.

Payments come before plans because a paid plan cannot be created without a provider connected.

Known limitation: setupSchedule is marked complete by the presence of class types, not by scheduled sessions or templates. It settles at the same moment as createClassType, so the guide never promotes it on its own. onboarding-complete also seeds a default class type for every new schedule program, so an org created through the sheet with “Classes on a schedule” ticked arrives with both steps already settled.

Tier-locked steps

connectPayments and createPlan need the automated_billing platform feature. On a tier without it they are locked: shown below the rail in their own group under the label “The rest needs the Pro plan”, each with a dashed lock marker, a one-line upsell and an always-visible “Upgrade” link, and the row links to /dashboard/settings/billing. Locked steps are excluded from the progress count and are never promoted.

Optional payment steps

While the org bills nobody (hasBilling() false: no payment config with status = 'active' and no plan, active or archived), connectPayments and createPlan are optional: listed below the rail under “Optional, for when you start charging” (setup-guide-optional), each linking to its page, never promoted and excluded from the progress count. A gym that does not charge is not unfinished for not charging. As soon as the org bills — a terminal that can charge or a first plan — both return to the rail; connectPayments is complete only once a terminal can charge, so a gym that sells plans for cash is asked to connect one. A tier without automated_billing keeps them in the locked group instead. hasBilling() lives in apps/web/src/lib/billing.ts; the hook is useBilling() (apps/web/src/hooks/use-billing.ts).

Render states

The card has two halves:

• The promoted step: exactly one, the first step that is neither locked nor complete. Heading (setup-guide-next), a one-line reason, a button (setup-guide-cta) that links to the step, and the progress text “{completed} of {total} done”.
• The rail: every step as a link with the same StepMarker the sheet uses (settled for complete, current for the promoted one with aria-current="step", upcoming otherwise). Completed and locked rows carry a screen-reader-only suffix. Other unfinished steps stay reachable here but never compete with the promoted one.

A close button (dismiss-getting-started) hides the guide. The dismissed flag is the localStorage key taikan:getting-started-dismissed; lib/session-reset.ts clears it whenever the signed-in identity changes on the same browser.

Edge cases & error states

Side effects

Analytics events

All events carry onboarding_variant='v5-sheet'.

Permissions