You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 4b25cb0
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: packages/mosaic/AGENTS.md
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -131,6 +131,7 @@ A bug in a feature is often a gap in a shared helper. These rules apply to `fix`
131
131
-**A changed shared signature is a new pattern.** A new parameter, a return type that goes from `void` to a promise, or a returned field whose meaning changes all go through "When nothing fits: ask first".
132
132
-**One source of truth for busy.** When a machine, `usePendingAction` or `useForm` already knows an action is running, derive the flag from it: `isDisabled: actions.isPending || remove.isPending`. Do not mirror it into a second lock, or turn machine state into a promise to feed one.
133
133
-**Handle staleness through lifecycle.** A new identity remounts through a React `key`. A busy action keeps running when its surface closes (Controllers → Rules). Do not thread run ids or `AbortSignal`s through the model, controller and machine.
134
+
-**Ship a shared change on its own.** A change to `src/styles/`, `src/components/`, `src/blocks/` or `src/hooks/` made for one feature goes in its own PR, unless the user asks for it in the feature's PR. Its values come from Mosaic tokens; another Clerk app's design shows the intent, not the values.
134
135
-**Extend a contract with an options object.** Make a field required when every caller has it: `connect(strategy, { walletName, onTarget })`, not `connect(strategy, walletName?, onTarget?)`.
135
136
-**Pass shared results through whole.** The view gets `form`, not an object that renames `form.id`, `form.isSubmitting` and `form.handleSubmit`.
136
137
-**Keep controller state off model types.** Pending and error flags the controller sets go on a row type the controller builds, not as optional fields on the type the model returns.
Turn the hits into a behavior inventory, one row per effect, guard, error path, empty or loading state, permission gate, revalidate, reset-on-close and derived label. The table does not cover every behavior; read the files too. For shared answers (`save`, `useReverificationFlow`), use [Reuse before you write](../AGENTS.md#reuse-before-you-write).
37
37
38
+
### Screens
39
+
40
+
Before you build a view, screenshot each legacy screen it replaces and list what the screen shows: each header line (title, description, identity preview), alerts, the primary and secondary actions, fallback links such as "Get help", and what the actions do while a request runs. Build against that list.
41
+
42
+
To reach a screen that needs a server state, run the legacy sandbox (`pnpm dev:sandbox`, `packages/clerk-js/sandbox/README.md`) with a scenario from `packages/clerk-js/sandbox/scenarios/` that mocks the response with `@clerk/msw`, then activate it with `scenario.setScenario('<Name>')`.
43
+
44
+
For each screen, decide whether it is its own step or a state of another one. A failure the user can recover from on the same screen is an error state of that step, not a step: legacy shows a lockout as a banner on the sign-in start screen, so Mosaic does too. If the flow has a design doc in `docs/internals/`, check it before you add a step the doc has no route for.
45
+
38
46
## Phase 2: map every row to a layer
39
47
40
48
- Clerk reads, mutations, permission gates, revalidate timing, first-load empty states and capability flags go in the **model** ([Models](models.md)).
Copy file name to clipboardExpand all lines: packages/mosaic/docs/parity-audit.md
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,6 +8,7 @@ Read this when you review whether a migrated feature kept every legacy behavior,
8
8
- Each one is **Migrated** (points at a state, transition, context field or prop in the new code), **Deliberately changed** (names the new behavior and why) or **Deferred** (not implemented; say whether a ticket tracks it).
9
9
- A Deferred item tracked only by a `// TODO` is a regression at risk of shipping. Surface it as a tracked item.
10
10
- Run it as a read-only subagent that returns a conclusion, not file dumps. The table guides the work and the PR discussion; nothing is committed.
11
+
- For a migration with views, also compare each screen with the legacy screenshot from [Migration → Screens](migration.md#screens), and put the pairs in a Legacy / Mosaic table in the PR description. A behavior audit reads code; it misses a dropped identity preview or an error shown as plain text.
Copy file name to clipboardExpand all lines: packages/mosaic/docs/views.md
+11Lines changed: 11 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,6 +11,7 @@ Worked example: `src/features/switcher/switcher.view.tsx`.
11
11
- An absent callback hides the affordance it drives. The model says "this instance does not offer this" by omitting the callback, so the view checks `onSignOutAll ? … : null`, not a capability flag.
12
12
- Take derived booleans from the controller. The view never re-implements a machine guard or works out whether an action is allowed.
13
13
- Every string comes from the feature's `*.messages.ts`, read with `useMessages`. Never import a `*.messages.ts` directly: that skips the customer's locale and overrides.
14
+
- Text that reports a failure is an error, never a description: `Card.Banner color='negative'` with `role='alert'` for the form, `Field.Feedback` for one field. This holds for a fixed message too, such as a breached password.
14
15
- Pure derivation (which affordance lands in which slot, how a consumer's `order` array rearranges a list) has no React in it. It lives in `*.layout.ts` or `*.utils.ts` with its own tests, and the view calls the result.
15
16
16
17
## Moving between screens on one surface
@@ -41,6 +42,8 @@ When one screen replaces another on the same card or dialog, render both as step
41
42
-**The surface sits outside the flow, and a step renders only what goes inside it.** A screen used as a step of another feature cannot bring its own `Card.Root`: `ConfirmShell` owns the card and `Reverification` renders only its contents.
42
43
-**One flow per surface.** A step that has steps of its own adds them to the same flow, so the view renders one `Flow.Root`.
43
44
-**The controller owns the step.** Going back is direction `-1`. Derive it from the step when each step has one way in, and hold it in the controller when it does not (`reverification.controller.ts`).
45
+
-**Name step kinds for what the user does,** not for what the screen looks like: `credential`, `code`, `choice`. Before adding a member to a kind, check the name still fits it (a passkey is a credential but not a secret).
46
+
-**Hold the primary action while it runs.** A step's async action is a `SubmitButton` with `isPending` and a `pendingLabel`, and it stays pending until the next step renders. Every other action on the step takes `disabled={isPending}` (`reverification.view.tsx`).
44
47
-**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.
45
48
-**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).
46
49
- 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.
@@ -61,6 +64,12 @@ A feature's skeleton is a surface too. A feature another feature can embed expor
61
64
62
65
Chrome that stays across steps goes under the surface, outside the flow. A step's `Card.Footer` must be a sibling of its `Card.Content`, so a step on a surface with a shared footer puts its submit button in `Card.Content` (`waitlist.view.tsx`).
63
66
67
+
### Header or content
68
+
69
+
-`Card.Description` holds text that describes the card, and may hold an inline link or an extra line such as the identity preview or a "Didn't receive a link? Resend" line. On a centered card the header centers every line in it.
70
+
-`Card.Content` does not follow the card's `align`. A line that should sit centered under content, such as "Don't have any of these? Get help", centers itself (`verification-method-picker.tsx`).
71
+
- A field, a list or a copyable value goes in `Card.Content`, never in the header.
72
+
64
73
## Forms on a card
65
74
66
75
The controller owns the form with `useForm`, including what `canSubmit` allows, and passes `form` to the view whole. The view does not check values, call `preventDefault` or create the form's id. Worked example: `organization-profile-edit-name.dialog.tsx`.
@@ -82,6 +91,8 @@ To add copy for a new section, step or dialog:
82
91
2. Mount the object in `src/localization/registry.ts` under the public component the user sees it in (see the key tree below).
83
92
3. Read it inside the component that renders it, with `useMessages` and the root: `const m = useMessages('userProfile').mfa;`. A module-level helper takes the messages as a parameter rather than importing them.
84
93
94
+
A block shared by several features (`blocks/verification`) does not read a feature's messages. It takes its copy as a `messages` prop, and the step that renders it reads the feature's messages and passes them in. Copy that branches on step data, such as a code step's title by purpose and channel, is a pure helper in the feature's `*.utils.ts` with a test.
95
+
85
96
### Message keys are public
86
97
87
98
`MosaicCatalog` is derived from the registry, so a consumer's overrides type-check against the real keys, as a dot path (`'userButton.popup.label'`) or a nested object. Renaming or moving a key breaks every override that names it; treat it like renaming a prop.
0 commit comments