Skip to content

Commit 28562dd

Browse files
docs(mosaic): add sign-in and sign-up flow guide (#10733)
1 parent 12ef401 commit 28562dd

3 files changed

Lines changed: 101 additions & 0 deletions

File tree

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
---
2+
---

‎packages/mosaic/docs/controllers.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -150,6 +150,8 @@ return {
150150

151151
The view side is in [Views → Moving between screens](views.md#moving-between-screens-on-one-surface).
152152

153+
**Exception: sign-in and sign-up.** FAPI owns their step, so there is no step machine. The model returns the step from `getSignInNextStep` or `getSignUpNextStep`, the controller picks the screen from it, and the route holds what the step can't say, such as the factor the user picked ([Sign-in and sign-up flow](internals/sign-in-sign-up-flow.md#pick-the-screen)).
154+
153155
## Wrapping actions
154156

155157
- **One wrapper for every action**, so each is wrapped the same way and only one is in flight (`runAction` in `switcher.controller.tsx`).
Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# Sign-in and sign-up flow
2+
3+
How sign-in and sign-up decide which screen to show, from the step FAPI says comes next. Paths are relative to `packages/`.
4+
5+
## The model
6+
7+
A step is a step of the auth flow, not a screen. FAPI owns the step, the order of steps, and whether a code is already sent. Mosaic owns the routes, the layout and copy, and when to send a code.
8+
9+
Today FAPI sends `status`, `missing_fields` and `unverified_fields`, not a step. Until it sends `nextStep`, `getSignInNextStep` and `getSignUpNextStep` in `shared` compute it from those fields (see [Bridge](#bridge)).
10+
11+
There is no step machine and no local copy of the step. What the step can't say lives in the route, such as the factor the user picked in `factorOne`'s `:factor` param.
12+
13+
## Pick the screen
14+
15+
The route and the step can disagree: the user went back, opened an old link, or the sign-in reset. A route the step allows stays. Any other route is replaced with the step's route, so the screen and the route never drift. `unknown` shows "Start over" on whatever route it's on.
16+
17+
```tsx
18+
const { step } = model;
19+
const { route } = useRouterScope(signInRoutes, { routing, path, root: 'start' });
20+
const screen = step.type === 'unknown' ? 'startOver' : allowedRoute(route, step) ? route : routeFor(step);
21+
```
22+
23+
- `routeFor(step)` returns the step's route, from the lists below.
24+
- `allowedRoute(route, step)` is `true` for `start`, for the step's own route, and for `continue` while sign-up verifies, so the user can edit a field. `complete` and `transfer` have no route, so they allow any route: the current screen stays up while `next` runs, and shows the error if it fails.
25+
- The component that owns the route table computes `screen` during render, with no effect.
26+
- This runs once the model is `ready`, and after Clerk loads there is always a step. Until then the scope gets `ready: false`, so a starting route like `factor-one` isn't reset to `start`.
27+
28+
## Move on after a submit
29+
30+
The model makes the Clerk call and returns the next step. The methods return `{ error }` instead of rejecting, so the model throws it for `save` and the controller's error owners. The controller passes the step to `next(step)`.
31+
32+
```ts
33+
submitPassword: async (password: string) => {
34+
await save(async () => {
35+
const { error } = await signIn.password({ password });
36+
if (error) throw error;
37+
}, ['password']);
38+
return getSignInNextStep(signIn);
39+
},
40+
```
41+
42+
- `complete`: the model's `finalize()`, then leave the flow. In a modal, don't `close()` when the flow leaves: `finalize()`'s navigation is the last write and takes the modal with it.
43+
- `transfer` from sign-in: the model's `transfer()` calls `signUp.create({ transfer: true, unsafeMetadata })`, then `next` with the sign-up's step. A sign-in with sign-up built in holds the sign-up routes under `create/`, so it stays in the component. Otherwise it leaves for the sign-up page.
44+
- `transfer` from sign-up, when the identifier already has an account: the model's `transfer()` calls `signIn.create({ transfer: true })`, then `next` with the sign-in's step.
45+
- `unknown`: nothing. The screen already shows "Start over".
46+
- Anything else: `go(routeFor(step))`.
47+
- An error from `finalize()` or the transfer stays on the current screen.
48+
49+
## Routes and steps
50+
51+
Each flow owns one route table through `useRouterScope`. Paths match `ui`'s, so links carry over.
52+
53+
Sign-in:
54+
55+
- `identifier` → `start`
56+
- `protect` → `protectCheck`
57+
- `first_factor` (`strategy`, `sent`) → `factorOne`
58+
- `second_factor` (`strategy`, `sent`) → `factorTwo`
59+
- `client_trust` → `clientTrust`
60+
- `new_password` → `resetPassword`
61+
62+
Sign-up:
63+
64+
- `start` → `start`
65+
- `protect` → `protectCheck`
66+
- `enterprise_sso` → `enterpriseConnections`, which goes straight to the IdP unless there are several connections to pick from
67+
- `fields` (`fields`) → `continue`
68+
- `verify_email` (`target`, `sent`) → `verifyEmail`
69+
- `verify_phone` (`target`, `sent`) → `verifyPhone`
70+
71+
`identifier` and `start` are what Mosaic shows before the resource exists; a sign-in with no status and a sign-up not yet created both return them. `sent` means a code or link is out, so a reload on the same `:factor` doesn't send another. Picking a different factor always sends, because `sent` can't tell two targets with the same strategy apart (see [Bridge](#bridge)).
72+
73+
With no `:factor`, `factorOne` starts on the factor `ui`'s `determineStartingSignInFactor` picks (`ui/src/components/SignIn/utils.ts:76`). That rule moves to `shared` so both use one copy.
74+
75+
## Back, forward and reload
76+
77+
- FAPI's state changes only on submit. A route the step doesn't allow is replaced with the step's route.
78+
- Back to `start` shows the identifier form; submitting it creates a new sign-in. Forward to `factorOne` still works.
79+
- Reload on `factorOne` keeps the picked factor (`:factor`) and sends no second code (`sent`).
80+
- Virtual routing has no history: a remount starts at `start`, and FAPI's state is kept.
81+
82+
## Entry actions
83+
84+
The controller calls these model callbacks on `start`, then `next(step)`.
85+
86+
- Ticket (`__clerk_ticket`): `__clerk_status=sign_up` redeems it with `signUp.ticket({ unsafeMetadata })`; any other status with `signIn.ticket()`, as `ui/src/components/SignIn/SignInStart.tsx` does. A ticket works only once, so redeem it once: keep the "already started" flag in a component that doesn't remount, so a remount or StrictMode can't redeem it twice. A failed redemption shows its error on `start`.
87+
- Email-link return (`__clerk_status`): `verified` with a `__clerk_created_session` this client has activates that session (`clerk-js/src/core/clerk.ts:2620-2636`); any other `verified` continues by step. `transferable` and the error statuses show their own screen, as `ui/src/common/EmailLinkVerify.tsx` does.
88+
- Redirect URLs for email links and OAuth/SAML returns come from the router (the planned `useReturnUrl(name, params)`), never hand-built. That part waits for the routing follow-up.
89+
- A step that is already `complete` or `transfer` on mount, such as a reload before it ran: `next(step)` runs it once, with the same guard as a ticket. The email-link return is handled first.
90+
91+
## Bridge
92+
93+
`getSignInNextStep` and `getSignUpNextStep` (`shared/src/internal/clerk-js/nextStep.ts`) compute the step from today's fields, and return FAPI's `nextStep` once it is sent. They can't compute three things, so FAPI must send them:
94+
95+
- The sign-up order.
96+
- `target` for sign-in. Nothing says which email or phone a code went to.
97+
- `sent` per target for sign-in. `first_factor_verification` has no identification, so after a code to one email, a second email with the same strategy also reads as sent.

0 commit comments

Comments
 (0)