Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
37 commits
Select commit Hold shift + click to select a range
4e8b502
refactor(shared): split the sign-in and sign-up next step types
austincalvelage Nov 17, 2026
2d7668c
fix(shared): verify the sign-up email and phone before collecting mis…
austincalvelage Nov 17, 2026
6b502e8
chore(shared): note the sign-up requirement FAPI does not send
austincalvelage Nov 17, 2026
c0a0583
feat(mosaic): add the sign-up route table
austincalvelage Nov 17, 2026
aa30f77
feat(mosaic): add the sign-up model shape
austincalvelage Nov 17, 2026
77b104b
chore(repo): add an empty changeset for the sign-up routing work
austincalvelage Nov 17, 2026
9ca1d9c
refactor(shared): accept any sign-up shape in minimizeFieldsForExisti…
austincalvelage Nov 17, 2026
4e680f7
feat(mosaic): add the sign-up model hook
austincalvelage Nov 17, 2026
828ac0d
refactor(mosaic): share the start-over notice through blocks/auth
austincalvelage Nov 17, 2026
c0082f5
feat(mosaic): add the start-over notice to sign-up
austincalvelage Nov 17, 2026
c14a90b
refactor(mosaic): name the sign-up email field emailAddress
austincalvelage Nov 17, 2026
3f53c33
feat(mosaic): tell the sign-up controller whether email and phone can…
austincalvelage Nov 17, 2026
39eb8d2
feat(mosaic): add the sign-up controller
austincalvelage Nov 17, 2026
5a4e54a
feat(mosaic): send sign-up verification codes with a resend countdown
austincalvelage Nov 17, 2026
5538a5a
feat(mosaic): add the SignUp component
austincalvelage Nov 17, 2026
0da9f5d
chore(swingset): add a live sign-up page
austincalvelage Nov 17, 2026
79cba5a
fix(mosaic): finalize the sign-up after verifying and verify the code…
austincalvelage Nov 17, 2026
8549e68
docs(mosaic): name the order sign-up follows until FAPI sends one
austincalvelage Nov 17, 2026
b0d2aad
refactor(shared,ui): move the blocked request parser into shared
austincalvelage Nov 17, 2026
2c79e3e
refactor(mosaic): name the sign-up route file sign-up.routes.ts
austincalvelage Nov 17, 2026
4c0e05f
fix(mosaic): close the sign-up gaps found in the legacy inventory
austincalvelage Nov 17, 2026
b064114
fix(mosaic): leave the password off the sign-up continue screen once …
austincalvelage Nov 17, 2026
f72481f
test(mosaic): fake the sign-up endpoints and reset the auth signals b…
austincalvelage Nov 17, 2026
055a111
test(mosaic): add the sign-up feature tests
austincalvelage Nov 17, 2026
4fdb427
fix(mosaic): fill the username length error and clear the sign-up for…
austincalvelage Nov 17, 2026
cd9110b
fix(mosaic): send the sign-up code after a quick edit and submit hidd…
austincalvelage Nov 17, 2026
81503b5
feat(mosaic): take a routing prop on SignUp and replace a route the s…
austincalvelage Nov 17, 2026
ab242a6
Merge remote-tracking branch 'origin/austin/shared-sign-up-form-field…
austincalvelage Nov 18, 2026
dc6b6c4
Merge branch 'austin/shared-sign-up-next-step-order' into austin/mosa…
austincalvelage Nov 18, 2026
f029f60
refactor(mosaic): export the organization task without its card
austincalvelage Nov 18, 2026
56d6681
test(mosaic): drop a completed sign-up from the fake client
austincalvelage Nov 18, 2026
191641c
feat(mosaic): mount sign-up screens by route
austincalvelage Nov 18, 2026
ea16f83
docs(mosaic): describe how sign-up mounts its screens
austincalvelage Nov 18, 2026
434272c
chore(swingset): send live sign-up, waitlist and MFA task to Mosaic p…
austincalvelage Nov 18, 2026
f9731b4
docs(mosaic): note each sign-up screen's route in the view
austincalvelage Nov 18, 2026
0bf5889
refactor(mosaic): fold the sign-up code step into the verify step
austincalvelage Nov 18, 2026
e9a4895
refactor(mosaic): use Flow.Step directly in the sign-up view
austincalvelage Nov 18, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .changeset/mosaic-sign-up-routing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
---
---
2 changes: 1 addition & 1 deletion packages/mosaic/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ Most problems a feature hits already have a shared answer. Find the line for you
- An action that may need step-up verification → `useReverificationFlow` (`src/features/reverification/`) in the model, passed to `useConfirmController`
- A direct action that needs step-up verification → `useReverificationFlow` in the model, with `ReverificationDialog` (`src/blocks/reverification/`) in the view
- A step that verifies a factor (a code, password, backup code or passkey, the method picker, help) → the steps in `src/blocks/verification/`, such as `VerificationCode`
- A screen sign-in and sign-up both show (an email link and its status, a loading or protect-check notice, a blocked request, the wallet or enterprise connection picker, the alternative phone channel, the identity line, the captcha) → the steps in `src/blocks/auth/`, such as `AuthEmailLink`
- A screen sign-in and sign-up both show (an email link and its status, a loading, start-over or protect-check notice, a blocked request, the wallet or enterprise connection picker, the alternative phone channel, the identity line, the captcha) → the steps in `src/blocks/auth/`, such as `AuthEmailLink`
- Showing any error to the user → One of the owners above. They call `toLocalizableError` (or `toLocalizableErrors` for all errors) and resolve copy with `useErrorText`
- Moving focus after a list row is removed → `useListRemovalFocus` (`src/hooks/`)
- A debounced, abortable async check as the user types → `useDebouncedAsync` (`src/hooks/`)
Expand Down
2 changes: 1 addition & 1 deletion packages/mosaic/docs/controllers.md
Original file line number Diff line number Diff line change
Expand Up @@ -150,7 +150,7 @@ return {

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

**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)).
**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)). Sign-up mounts one component per screen: its controller holds what outlives a screen, and a screen with work to do on arrival owns its own ([Mount the screen](internals/sign-in-sign-up-flow.md#mount-the-screen)).

## Wrapping actions

Expand Down
27 changes: 14 additions & 13 deletions packages/mosaic/docs/features.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,19 +21,20 @@ Read the split as _where the data comes from_ (model) → _what the user is doin

A feature lives in `src/features/<feature>/`, one file per role, each prefixed with the feature name. Use `.ts` unless the file renders JSX.

| File | Holds |
| ---------------------------- | --------------------------------------------------------------------------- |
| `<feature>.model.ts(x)` | The Clerk adapter |
| `<feature>.controller.ts(x)` | Local state, a machine if it has one, and action wrapping |
| `<feature>.view.tsx` | Rendering only |
| `<feature>.tsx` | The composition wrapper and the public props type |
| `<feature>.types.ts` | The data contract the model and view share |
| `<feature>.messages.ts` | Every string the feature renders ([Views](views.md#where-the-strings-live)) |
| `<feature>.layout.ts` | Pure derivation, such as which affordance goes in which slot |
| `<feature>.utils.ts` | Pure helpers |
| `<feature>.styles.ts` | `stylex.create` atoms ([StyleX](stylex.md)) |
| `<feature>.skeleton.tsx` | The loading placeholder ([Skeletons](skeletons.md)) |
| `<name>.dialog.tsx` | A dialog the view opens, when it would crowd the view file |
| File | Holds |
| ---------------------------- | ------------------------------------------------------------------------------------------------ |
| `<feature>.model.ts(x)` | The Clerk adapter |
| `<feature>.controller.ts(x)` | Local state, a machine if it has one, and action wrapping |
| `<feature>.view.tsx` | Rendering only |
| `<feature>.tsx` | The composition wrapper and the public props type |
| `<feature>.types.ts` | The data contract the model and view share |
| `<feature>.messages.ts` | Every string the feature renders ([Views](views.md#where-the-strings-live)) |
| `<feature>.layout.ts` | Pure derivation, such as which affordance goes in which slot |
| `<feature>.routes.ts` | The route table of a flow that owns its routes, and the pure rules over it (`sign-up.routes.ts`) |
| `<feature>.utils.ts` | Pure helpers |
| `<feature>.styles.ts` | `stylex.create` atoms ([StyleX](stylex.md)) |
| `<feature>.skeleton.tsx` | The loading placeholder ([Skeletons](skeletons.md)) |
| `<name>.dialog.tsx` | A dialog the view opens, when it would crowd the view file |

`*.types.ts` holds the contract so that neither the model nor the view owns it, and the two cannot drift.

Expand Down
29 changes: 23 additions & 6 deletions packages/mosaic/docs/internals/sign-in-sign-up-flow.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ FAPI tracks which requirements are outstanding and whether a code has been sent.

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)).

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.
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, or whether a sign-up verify screen was reached from `continue`.

## Pick the screen

Expand All @@ -20,11 +20,21 @@ const { route } = useRouterScope(signInRoutes, { routing, path, root: 'start' })
const screen = step.type === 'unknown' ? 'startOver' : allowedRoute(route, step) ? route : routeFor(step);
```

- `routeFor(step)` returns the step's route, from the lists below.
- `routeFor(step)` returns the step's route, from the lists below. Sign-up's also takes the current route, so a verify step reached from `continue` stays under it.
- `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.
- The component that owns the route table computes `screen` during render, with no effect.
- 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`.

## Mount the screen

Sign-up renders one component per screen, so the route decides what is mounted (`SignUpView` in `mosaic/src/features/sign-up/sign-up.view.tsx`). Sign-in has no controller yet.

- `useSignUpController` sits above the screens and holds what outlives one: the route, the details form, the chosen identifier and Start over. `start` and `continue` render that one form, so a password typed on `start` is still there after Back from a verify screen. The password lives nowhere else.
- A screen with work to do on arrival owns its controller. `SignUpVerify` holds the code machine and sends the code when it mounts on a step with `sent: false`. A submit, a reload and a redirect all arrive that way.
- `SignUpVerify` takes the sign-up's id as its `key`, so a new sign-up never reuses the last one's screen.
- A screen another feature owns arrives as a slot. The wrapper passes `TaskChooseOrganizationContent`, the task without its card, and the view mounts it on the task route.
- A screen that is not a route sits on top of one. `restricted`, `waitlist` and `actionBlocked` replace `start`, and `startOver` replaces any route. A route whose screen is not built yet (`enterpriseConnections`, `protectCheck`) shows `startOver`.

## Move on after a submit

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)`.
Expand All @@ -39,7 +49,7 @@ submitPassword: async (password: string) => {
},
```

- `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.
- `complete`: the model's `finalize()`, then leave the flow. Creating the session clears the sign-up, so the live step drops back to `start`. Sign-up renders the model it left from until the navigation takes the flow away, or, when `finalize()` answers that a task continues in the flow, until that task's data has loaded, so the task replaces the screen with no skeleton between them. It keeps the action pending throughout, the way the switcher holds its `frozenModel` ([Controllers → Wrapping actions](../controllers.md#wrapping-actions)). In a modal, don't `close()` when the flow leaves: `finalize()`'s navigation is the last write and takes the modal with it.
- `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.
- `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.
- `unknown`: nothing. The screen already shows "Start over".
Expand All @@ -64,10 +74,17 @@ Sign-up:
- `start` → `start`
- `protect` → `protectCheck`
- `enterprise_sso` → `enterpriseConnections`, which goes straight to the IdP unless there are several connections to pick from
- `verify_email` (`target`, `sent`) → `verifyEmail`
- `verify_phone` (`target`, `sent`) → `verifyPhone`
- `verify_email` (`target`, `sent`) → `verifyEmail`, or `continueVerifyEmail` when reached from `continue`
- `verify_phone` (`target`, `sent`) → `verifyPhone`, or `continueVerifyPhone` when reached from `continue`
- `fields` (`fields`) → `continue`

Sign-up's model adds two steps of its own to the ones `getSignUpNextStep` returns, for when there is no sign-up in progress:

- `task` (`key`) → `taskChooseOrganization`: the session has a pending task that sign-up shows in its own card. Only the task route is allowed, so a visit to `start` with the task pending moves to it. A task the application gave a URL in `taskUrls`, or one sign-up has no screen for, is not a `task` step: the flow leaves for its URL.
- `leaving`: a session is active or being activated. It has no route and allows any, so the screen that started the navigation stays up.

Back from a sign-up verify screen goes to the details route above it: `continue` for the two nested routes, `start` for the others (`detailsRouteFor`).

`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)).

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.
Expand All @@ -76,7 +93,7 @@ With no `:factor`, `factorOne` starts on the factor `ui`'s `determineStartingSig

- FAPI's state changes only on submit. A route the step doesn't allow is replaced with the step's route.
- Back to `start` shows the identifier form; submitting it creates a new sign-in. Forward to `factorOne` still works.
- Reload on `factorOne` keeps the picked factor (`:factor`) and sends no second code (`sent`).
- Reload on `factorOne` keeps the picked factor (`:factor`) and sends no second code (`sent`). Reload on a sign-up verify route sends a code only when `sent` is false.
- Virtual routing has no history: a remount starts at `start`, and FAPI's state is kept.

## Entry actions
Expand Down
1 change: 1 addition & 0 deletions packages/mosaic/docs/views.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ When one screen replaces another on the same card or dialog, render both as step
- **Mark what takes focus with `useFlowAutoFocus`.** Focus moves only for a step that transitions in, so a flow that opens on a step does not take focus.
- **A multi-step flow gets derived props.** The view renders the `step`, `form` and flags the controller passes and does not work out the step itself. Every step's `Form` uses `id={form.id}` and the controller's `onSubmit`, and its footer action is a `SubmitButton form={form.id}`: `isPending={isTesting}` and `disabled={!canContinue}` on a middle step, `isPending={form.isSubmitting}` and `disabled={!form.canSubmit}` on the last. The controller side is in [Controllers → Multi-step flows](controllers.md#multi-step-flows).
- A loading or error state of one screen is not a step, and neither is the skeleton shown before a feature has data. Those stay conditionals.
- **Exception: sign-up.** Its screens follow its routes, so the view takes `screen` and one props object per screen, and each `Flow.Step` mounts that screen's component (`sign-up.view.tsx`, [Mount the screen](internals/sign-in-sign-up-flow.md#mount-the-screen)).

The parts, data attributes and CSS variables are in `src/primitives/flow/README.md`.

Expand Down
9 changes: 7 additions & 2 deletions packages/mosaic/src/__tests__/feature/fake-fapi.ts
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ import { createMfaState, type FakeMfaState, mfaHandlers } from './fake-fapi/mfa'
import { organizationMemberHandlers } from './fake-fapi/organization-members';
import { type FakePasskeysSeed, passkeyHandlers } from './fake-fapi/passkeys';
import { envelope, error, findSession, missing, updateUser, VERIFICATION_CODE } from './fake-fapi/shared';
import { createSignUpState, type FakeSignUpSeed, type FakeSignUpState, signUpHandlers } from './fake-fapi/sign-up';
import {
createVerificationState,
type FakeVerificationSeed,
Expand Down Expand Up @@ -84,6 +85,7 @@ export interface FakeFapiState {
enterpriseConnections: EnterpriseConnectionJSON[];
enterpriseLinking: FakeEnterpriseLinking;
mfa: FakeMfaState;
signUp: FakeSignUpState;
activeDevices?: ActiveDeviceRecord[];
deviceTrackingEnabled: boolean;
organizationCreationDefaults?: OrganizationCreationDefaultsJSON;
Expand All @@ -99,7 +101,8 @@ export interface ActiveDeviceRecord extends SessionWithActivitiesJSON {
tokenIssuedAt?: number;
}

export type FakeFapiSeed = Partial<Omit<FakeFapiState, 'verification' | 'enterpriseLinking'>> & {
export type FakeFapiSeed = Partial<Omit<FakeFapiState, 'verification' | 'enterpriseLinking' | 'signUp'>> & {
signUp?: FakeSignUpSeed;
verification?: FakeVerificationSeed;
enterpriseLinking?: Partial<FakeEnterpriseLinking>;
passkeys?: FakePasskeysSeed;
Expand Down Expand Up @@ -310,7 +313,7 @@ export function verifyEmailOutOfBand(state: FakeFapiState, id: string): void {
}

export function serveFapi(seed: FakeFapiSeed = {}): FakeFapiState {
const { verification, enterpriseLinking, passkeys, ...rest } = seed;
const { verification, enterpriseLinking, passkeys, signUp, ...rest } = seed;
const state: FakeFapiState = {
environment: fapiEnvironment(),
client: fapiClient(),
Expand All @@ -330,6 +333,7 @@ export function serveFapi(seed: FakeFapiSeed = {}): FakeFapiState {
mfa: createMfaState(),
...rest,
verification: createVerificationState(verification),
signUp: createSignUpState(signUp),
enterpriseLinking: {
enabled: false,
preparations: {},
Expand All @@ -346,6 +350,7 @@ export function serveFapi(seed: FakeFapiSeed = {}): FakeFapiState {
...enterpriseHandlers(state, fapiUrl),
...passkeyHandlers(state, fapiUrl, passkeys),
...mfaHandlers(state, fapiUrl),
...signUpHandlers(state, fapiUrl),
http.get(fapiUrl('/v1/environment'), () =>
HttpResponse.json(state.environment, state.country ? { headers: { 'x-country': state.country } } : undefined),
),
Expand Down
Loading
Loading