Skip to content

Commit 4b25cb0

Browse files
docs(mosaic): add view rules for legacy screen parity, errors, pending and shared changes
1 parent 9a14357 commit 4b25cb0

6 files changed

Lines changed: 24 additions & 0 deletions

File tree

‎.changeset/mosaic-view-rules.md‎

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

‎packages/mosaic/AGENTS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -131,6 +131,7 @@ A bug in a feature is often a gap in a shared helper. These rules apply to `fix`
131131
- **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".
132132
- **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.
133133
- **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.
134135
- **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?)`.
135136
- **Pass shared results through whole.** The view gets `form`, not an object that renames `form.id`, `form.isSubmitting` and `form.handleSubmit`.
136137
- **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.

‎packages/mosaic/docs/documenting-components.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -305,4 +305,5 @@ Which surface the dialog holds, and the geometry that comes with it.
305305
- [ ] MDX sections match the archetype's required order exactly.
306306
- [ ] Every props-table row states its default in the **Default** column.
307307
- [ ] Wiring done per `packages/swingset/README.md`: `registry.ts`, `DocsViewer.tsx`'s `docModules`, and the `app/(explorer)/page.tsx` redirect if this is now the first component.
308+
- [ ] Every story added, renamed or removed is changed in `registry.ts` too. It imports each story by name, so an import of a story that no longer exists fails the whole page.
308309
- [ ] `pnpm format --filter @clerk/swingset` is clean.

‎packages/mosaic/docs/migration.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,14 @@ rg -n 'useEffect|handleError|card\.setError|useReverification|revalidate|<Protec
3535

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

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+
3846
## Phase 2: map every row to a layer
3947

4048
- Clerk reads, mutations, permission gates, revalidate timing, first-load empty states and capability flags go in the **model** ([Models](models.md)).

‎packages/mosaic/docs/parity-audit.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ Read this when you review whether a migrated feature kept every legacy behavior,
88
- 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).
99
- A Deferred item tracked only by a `// TODO` is a regression at risk of shipping. Surface it as a tracked item.
1010
- 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.
1112

1213
## The subagent prompt
1314

‎packages/mosaic/docs/views.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ Worked example: `src/features/switcher/switcher.view.tsx`.
1111
- 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.
1212
- Take derived booleans from the controller. The view never re-implements a machine guard or works out whether an action is allowed.
1313
- 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.
1415
- 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.
1516

1617
## 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
4142
- **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.
4243
- **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`.
4344
- **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`).
4447
- **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.
4548
- **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).
4649
- 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
6164

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

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+
6473
## Forms on a card
6574

6675
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:
8291
2. Mount the object in `src/localization/registry.ts` under the public component the user sees it in (see the key tree below).
8392
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.
8493

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+
8596
### Message keys are public
8697

8798
`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

Comments
 (0)