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 583bd3e
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: packages/mosaic/AGENTS.md
+16Lines changed: 16 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -98,6 +98,22 @@ Stop and check the table if you are writing any of these in a feature:
98
98
99
99
The form rule applies when you add or rewrite a form. Some existing forms predate it.
100
100
101
+
## Shaping a fix
102
+
103
+
A bug in a feature is often a gap in a shared helper. These rules apply to `fix` PRs as much as to features.
104
+
105
+
-**Fix the owner, don't wrap it.** When a shared helper (`src/hooks/`, `src/blocks/`, `src/components/`, `src/machine/`, or `@clerk/shared`) behaves wrongly, change the helper and its tests, then delete the workarounds. Do not spread a helper's return value to swap one method, copy a `||` that undoes one of its fields, or add a second hook beside it for one caller.
106
+
-**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".
107
+
-**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.
108
+
-**Handle staleness through lifecycle.** A new identity remounts through a React `key`. A busy state ignores close (Controllers → Rules). Do not thread run ids or `AbortSignal`s through the model, controller and machine.
109
+
-**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?)`.
110
+
-**Pass shared results through whole.** The view gets `form`, not an object that renames `form.id`, `form.isSubmitting` and `form.handleSubmit`.
111
+
-**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.
112
+
-**Narrow by mounting.** A hook that needs loaded data takes it non-null. Mount its component once the model is ready instead of checking for `null` inside (Controllers → Composition and dialog lifetime).
113
+
-**Machines:**`assign` stays pure. An effect the machine starts runs in `invoke`. The runtime has no spawned actors, so effects that run side by side, like `useForm`'s per-field `validateAsync`, run in the hook and report back by event, and the machine drops stale results. A phase of an action the user can see (queued, pending, failed) is a named state, not a context field plus a predicate. Screens that can sit on top of any state, like reverification's method picker and help, may be a stack in context, because the runtime has no parallel or history states.
114
+
115
+
If code or a test contradicts a rule in these docs, do not copy the code. Stop and ask which one is right, and fix the loser in the same PR.
116
+
101
117
## Nested radii
102
118
103
119
A part inset from a rounded surface gets its radius from that surface: `max(0px, calc(outer - border - padding))`. Do not pick a fixed step, or it stops matching when `--cl-radius-*` or `--cl-spacing` is overridden. This applies to small insets. When the inset is about as large as the outer radius or larger (Card content, TagInput tags), the part keeps its own radius.
Copy file name to clipboardExpand all lines: packages/mosaic/ARCHITECTURE.md
+40-29Lines changed: 40 additions & 29 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -59,10 +59,15 @@ A theme styles a part from CSS, against that class and its attributes:
59
59
}
60
60
```
61
61
62
-
A part exposes no `className` or `style` prop. Inside `@clerk/mosaic`, code that renders a part and needs to nudge it passes StyleX atoms through `xstyle`, declared in its own `stylex.create` and composed last so they win:
62
+
A part exposes no `className` or `style` prop. Inside `@clerk/mosaic`, code that renders a part and needs to nudge it passes StyleX atoms through `xstyle`, declared in its own `*.styles.ts` file and composed last so they win:
@@ -187,20 +192,20 @@ and neither can its tests. `src/machine/ADOPTION.md` holds the criteria.
187
192
A flow slice lives under `src/features/<feature>/` and is split by role, one file per layer, prefixed with the feature name. Use `.ts` unless the file renders JSX:
188
193
189
194
```text
190
-
user-button.model.ts(x) // Clerk adapter — the only file that imports Clerk
191
-
user-button.controller.ts(x) // local state (React state or a machine) + action wrapping
192
-
user-button.view.tsx // rendering only
193
-
user-button.tsx // composition wrapper and the public props type
195
+
switcher.model.ts(x) // Clerk adapter — the only file that imports Clerk
196
+
switcher.controller.ts(x) // local state (React state or a machine) + action wrapping
197
+
switcher.view.tsx // rendering only
198
+
switcher.tsx // composition wrapper and the public props type
194
199
```
195
200
196
201
Supporting files carry the parts that would otherwise bloat those four:
197
202
198
203
```text
199
-
user-button.types.ts // the data contract the model and view both agree on
200
-
user-button.messages.ts // every string the surface renders, as one `as const` object
201
-
user-button.layout.ts // pure derivation (which affordance goes in which slot)
202
-
user-button.utils.ts // pure helpers
203
-
user-button.styles.ts // `stylex.create` atoms (see the StyleX authoring rules)
204
+
switcher.types.ts // the data contract the model and view both agree on
205
+
switcher.messages.ts // every string the surface renders, as one `as const` object
206
+
switcher.layout.ts // pure derivation (which affordance goes in which slot)
207
+
switcher.utils.ts // pure helpers
208
+
switcher.styles.ts // `stylex.create` atoms (see the StyleX authoring rules)
204
209
<name>.dialog.tsx // a dialog the view opens, when it would crowd the view file
205
210
```
206
211
@@ -270,10 +275,10 @@ Two shapes, chosen by whether the slice fetches its own data.
270
275
wrapper resolves the model, hands it to the controller, and branches on `status`:
0 commit comments