Skip to content

Commit 625bbc3

Browse files
austincalvelageaustincalvelage
committed
refactor(mosaic): share pending ownership for identifier actions
1 parent aad2c1b commit 625bbc3

9 files changed

Lines changed: 143 additions & 142 deletions

File tree

‎packages/mosaic/AGENTS.md‎

Lines changed: 27 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -31,33 +31,33 @@ A flow lives in `src/features/<feature>/`. The **model** (`*.model.ts(x)`) is th
3131

3232
Most problems a feature hits already have a shared answer. Find the row for your problem and use it. Do not write a local version, even a small one.
3333

34-
| Problem | Use |
35-
| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
36-
| An async action from a button or row: pending, an error, one lock | `usePendingAction` (`src/hooks/`) |
37-
| Direct actions and confirmation dialogs that must exclude each other | `useActionLock` injected into `usePendingAction` and `useConfirmController` (`src/hooks/`, `src/blocks/confirm/`) |
38-
| A form: values, validation, submit, field errors | `useForm` (`src/components/form/`), with `validateAsync` for a server-side check |
39-
| A `<form>` element, without the browser's validation popup | `Form` (`src/primitives/form/`) |
40-
| A model save whose Clerk errors should land on form fields | `save` (`src/utils/errors.ts`) in the model, or reject with `FormSubmitError` |
41-
| A confirm step before an action | `useConfirmController` (`src/blocks/confirm/`) with `Confirmation` (`src/blocks/confirmation/`) |
42-
| A delete that needs the user to type a phrase | `useConfirmController` (`src/blocks/confirm/`) with `Destructive` (`src/blocks/destructive/`) |
43-
| An action that may need step-up verification | `useReverificationFlow` (`src/features/reverification/`) in the model, passed to `useConfirmController` |
44-
| A direct action that needs step-up verification | `useReverificationFlow` in the model, with `ReverificationDialog` (`src/blocks/reverification/`) in the view |
45-
| Showing any error to the user | One of the owners above. They call `toLocalizableError` and resolve copy with `useErrorText` |
46-
| Moving focus after a list row is removed | `useListRemovalFocus` (`src/hooks/`) |
47-
| A debounced, abortable async check as the user types | `useDebouncedAsync` (`src/hooks/`) |
48-
| A spinner that should not flash or flicker | `useSpinDelay` (`src/hooks/`) |
49-
| A placeholder for content that is still loading | `Skeleton` (`src/components/skeleton/`), see [Skeletons](docs/skeletons.md) |
50-
| A date shown to the user | `formatDate` (`src/utils/format-date.ts`) |
51-
| A value turned into kebab case, e.g. for a `data-*` attribute | `kebabCase` (`src/utils/kebab-case.ts`) |
52-
| Current time for display labels | `useNow` (`src/hooks/`) |
53-
| Whether enterprise SSO permits adding another identification | `allowsIdentificationCreation` (`src/utils/allows-identification-creation.ts`) |
54-
| An inline message row that animates open and closed | `useHeldMessage`, `useMessageHeight`, `FeedbackBody` (`src/utils/feedback.tsx`) + `src/styles/feedback.styles.ts` |
55-
| Data read from a Clerk resource that should be cached across mounts | A query hook in `src/queries/`, called from the model (`src/queries/use-user-sessions-query.ts`) |
56-
| An item changed in place in an infinite list, kept until the next reload | `replaceInPages` (`src/utils/infinite-pages.ts`), passed to the list's `setData` |
57-
| Siblings that slide when an item is added or removed | `useLayoutAnimation` (`src/primitives/hooks/`) |
58-
| An input that reformats as the user types without moving the caret | `useFormattedInput` (`src/primitives/hooks/`) |
59-
| An interaction with an async lifecycle or two values that move together | A machine in the controller file, via `setup()` (`src/machine/`) |
60-
| Styles several components share | `src/styles/*.styles.ts` |
34+
| Problem | Use |
35+
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
36+
| An async action from a button or row: pending, an error, one lock | `usePendingAction` (`src/hooks/`) |
37+
| Direct actions and confirmation dialogs that must exclude each other | One `usePendingAction` owner, with `runExternal` passed as `useConfirmController`'s `runAction` (`src/hooks/`, `src/blocks/confirm/`) |
38+
| A form: values, validation, submit, field errors | `useForm` (`src/components/form/`), with `validateAsync` for a server-side check |
39+
| A `<form>` element, without the browser's validation popup | `Form` (`src/primitives/form/`) |
40+
| A model save whose Clerk errors should land on form fields | `save` (`src/utils/errors.ts`) in the model, or reject with `FormSubmitError` |
41+
| A confirm step before an action | `useConfirmController` (`src/blocks/confirm/`) with `Confirmation` (`src/blocks/confirmation/`) |
42+
| A delete that needs the user to type a phrase | `useConfirmController` (`src/blocks/confirm/`) with `Destructive` (`src/blocks/destructive/`) |
43+
| An action that may need step-up verification | `useReverificationFlow` (`src/features/reverification/`) in the model, passed to `useConfirmController` |
44+
| A direct action that needs step-up verification | `useReverificationFlow` in the model, with `ReverificationDialog` (`src/blocks/reverification/`) in the view |
45+
| Showing any error to the user | One of the owners above. They call `toLocalizableError` and resolve copy with `useErrorText` |
46+
| Moving focus after a list row is removed | `useListRemovalFocus` (`src/hooks/`) |
47+
| A debounced, abortable async check as the user types | `useDebouncedAsync` (`src/hooks/`) |
48+
| A spinner that should not flash or flicker | `useSpinDelay` (`src/hooks/`) |
49+
| A placeholder for content that is still loading | `Skeleton` (`src/components/skeleton/`), see [Skeletons](docs/skeletons.md) |
50+
| A date shown to the user | `formatDate` (`src/utils/format-date.ts`) |
51+
| A value turned into kebab case, e.g. for a `data-*` attribute | `kebabCase` (`src/utils/kebab-case.ts`) |
52+
| Current time for display labels | `useNow` (`src/hooks/`) |
53+
| Whether enterprise SSO permits adding another identification | `allowsIdentificationCreation` (`src/utils/allows-identification-creation.ts`) |
54+
| An inline message row that animates open and closed | `useHeldMessage`, `useMessageHeight`, `FeedbackBody` (`src/utils/feedback.tsx`) + `src/styles/feedback.styles.ts` |
55+
| Data read from a Clerk resource that should be cached across mounts | A query hook in `src/queries/`, called from the model (`src/queries/use-user-sessions-query.ts`) |
56+
| An item changed in place in an infinite list, kept until the next reload | `replaceInPages` (`src/utils/infinite-pages.ts`), passed to the list's `setData` |
57+
| Siblings that slide when an item is added or removed | `useLayoutAnimation` (`src/primitives/hooks/`) |
58+
| An input that reformats as the user types without moving the caret | `useFormattedInput` (`src/primitives/hooks/`) |
59+
| An interaction with an async lifecycle or two values that move together | A machine in the controller file, via `setup()` (`src/machine/`) |
60+
| Styles several components share | `src/styles/*.styles.ts` |
6161

6262
## Signs you are about to invent a pattern
6363

‎packages/mosaic/docs/controllers.md‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -51,22 +51,24 @@ return {
5151
};
5252
```
5353

54-
When a direct action and a confirmation must not run together, create one
55-
`useActionLock` (`src/hooks/use-action-lock.ts`) and inject it into both owners:
54+
When a direct action and a confirmation must not run together, give both
55+
operations one `usePendingAction` owner:
5656

5757
```ts
58-
const actionLock = useActionLock();
59-
const primary = usePendingAction({ actionLock });
58+
const actions = usePendingAction();
6059
const remove = useConfirmController({
61-
actionLock,
60+
runAction: actions.runExternal,
6261
onConfirm: contact => removalFocus.remove(contact.id),
6362
});
6463
```
6564

66-
Pass `actionLock.isPending` to the section controls' `disabled` props, including
67-
`Confirmation.disabled`. The lock prevents overlapping requests even before React
68-
renders the disabled controls, and stays held until the action settles. Each owner
69-
keeps its existing error handling. `actionLock` is a hook option, not a per-run option.
65+
Run direct actions with `actions.run(key, action)`. Pass `actions.isPending` to
66+
the section controls' `disabled` props, including `Confirmation.disabled`.
67+
`runExternal` returns the accepted promise, or `undefined` while another action
68+
runs. It leaves row keys and inline errors unchanged and preserves rejections
69+
for the confirmation dialog to handle. Both paths block overlapping calls before
70+
React renders and stay pending until the accepted promise settles. Closing a
71+
verification dialog does not release pending while cancellation is still settling.
7072

7173
`run` resolves `true` on success, so the caller can close a dialog or move
7274
focus. To hold pending through an OAuth redirect, await a delay inside the

‎packages/mosaic/src/blocks/confirm/confirm.controller.ts‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,6 @@ import { useMemo } from 'react';
44
import type { DialogHandle } from '../../components/dialog';
55
import { Dialog } from '../../components/dialog';
66
import type { ReverificationController } from '../../features/reverification';
7-
import type { ActionLock } from '../../hooks/use-action-lock';
87
import type { ErrorDescription } from '../../localization';
98
import { useErrorText } from '../../localization';
109
import { setup } from '../../machine/setup';
@@ -86,7 +85,7 @@ export interface ConfirmController<Payload = void> {
8685
}
8786

8887
export interface ConfirmControllerOptions<Payload = void> {
89-
actionLock?: ActionLock;
88+
runAction?: (action: () => Promise<void>) => Promise<void> | undefined;
9089
/** The action the dialog confirms. Resolve to close; reject to keep the dialog open showing why. */
9190
onConfirm: (payload: Payload) => Promise<unknown> | void;
9291
/** The flow `onConfirm` runs under, when the action may need step-up verification. */
@@ -109,7 +108,7 @@ export function useConfirmController<Payload = void>({
109108
onConfirm,
110109
reverification,
111110
errorFallback,
112-
actionLock,
111+
runAction,
113112
}: ConfirmControllerOptions<Payload>): ConfirmController<Payload> {
114113
const handle = useMemo(() => Dialog.createHandle<Payload>(), []);
115114
const [snapshot, send] = useMachine(confirmMachine);
@@ -145,8 +144,8 @@ export function useConfirmController<Payload = void>({
145144
const run = async () => {
146145
await onConfirm(payload);
147146
};
148-
if (actionLock) {
149-
const accepted = actionLock.tryRun(run);
147+
if (runAction) {
148+
const accepted = runAction(run);
150149
if (accepted) {
151150
send({ type: 'CONFIRM', run: () => accepted });
152151
}

‎packages/mosaic/src/features/user-profile/user-profile-email-section/user-profile-email-section.controller.ts‎

Lines changed: 7 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
import { useRef } from 'react';
22

33
import { useConfirmController } from '../../../blocks/confirm';
4-
import { useActionLock } from '../../../hooks/use-action-lock';
54
import { useListRemovalFocus } from '../../../hooks/use-list-removal-focus';
65
import { usePendingAction } from '../../../hooks/use-pending-action';
76
import type { UserProfileEmail } from '../user-profile-contact.types';
@@ -24,16 +23,15 @@ export function useUserProfileEmailSectionController({
2423
onCreate: onCreateEmail,
2524
reverification: createReverification,
2625
});
27-
const actionLock = useActionLock();
28-
const setPrimary = usePendingAction({ actionLock });
26+
const actions = usePendingAction();
2927
const rowRef = useRef<HTMLDivElement>(null);
3028
const removalFocus = useListRemovalFocus({
3129
ids: emails.map(email => email.id),
3230
onRemove: onRemoveEmail,
3331
fallback: () => rowRef.current?.querySelector<HTMLButtonElement>('button:not([disabled])') ?? rowRef.current,
3432
});
3533
const remove = useConfirmController<UserProfileEmail>({
36-
actionLock,
34+
runAction: actions.runExternal,
3735
onConfirm: email => removalFocus.remove(email.id),
3836
reverification: removeReverification,
3937
});
@@ -42,22 +40,22 @@ export function useUserProfileEmailSectionController({
4240
emails,
4341
canAdd: Boolean(onCreateEmail),
4442
verification,
45-
error: setPrimary.error,
46-
isDisabled: actionLock.isPending,
47-
pendingPrimaryId: setPrimary.pendingKey,
43+
error: actions.error,
44+
isDisabled: actions.isPending,
45+
pendingPrimaryId: actions.pendingKey,
4846
rowRef,
4947
registerTrigger: removalFocus.registerTrigger,
5048
remove: onRemoveEmail ? remove : undefined,
5149
finalFocus: removalFocus.finalFocus,
5250
verificationFinalFocus: () => (verification.verifyingId ? removalFocus.trigger(verification.verifyingId) : null),
5351
setPrimaryReverification,
54-
setPrimaryFinalFocus: () => (setPrimary.lastKey ? removalFocus.trigger(setPrimary.lastKey) : null),
52+
setPrimaryFinalFocus: () => (actions.lastKey ? removalFocus.trigger(actions.lastKey) : null),
5553
onVerify: id => {
5654
const email = emails.find(email => email.id === id);
5755
if (email) {
5856
verification.onVerifyEmail(email, getEmailVerifier(id));
5957
}
6058
},
61-
onSetPrimary: id => void setPrimary.run(id, () => onSetPrimaryEmail(id)),
59+
onSetPrimary: id => void actions.run(id, () => onSetPrimaryEmail(id)),
6260
};
6361
}

‎packages/mosaic/src/features/user-profile/user-profile-phone-section/user-profile-phone-section.controller.ts‎

Lines changed: 7 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,6 @@ import { stringToFormattedPhoneString } from '@clerk/shared/phone';
22
import { useRef } from 'react';
33

44
import { useConfirmController } from '../../../blocks/confirm';
5-
import { useActionLock } from '../../../hooks/use-action-lock';
65
import { useListRemovalFocus } from '../../../hooks/use-list-removal-focus';
76
import { usePendingAction } from '../../../hooks/use-pending-action';
87
import type { UserProfilePhone } from '../user-profile-contact.types';
@@ -24,16 +23,15 @@ export function useUserProfilePhoneSectionController({
2423
onCreate: onCreatePhone,
2524
reverification: createReverification,
2625
});
27-
const actionLock = useActionLock();
28-
const setPrimary = usePendingAction({ actionLock });
26+
const actions = usePendingAction();
2927
const rowRef = useRef<HTMLDivElement>(null);
3028
const removalFocus = useListRemovalFocus({
3129
ids: phones.map(phone => phone.id),
3230
onRemove: onRemovePhone,
3331
fallback: () => rowRef.current?.querySelector<HTMLButtonElement>('button:not([disabled])') ?? rowRef.current,
3432
});
3533
const remove = useConfirmController<UserProfilePhone>({
36-
actionLock,
34+
runAction: actions.runExternal,
3735
onConfirm: phone => removalFocus.remove(phone.id),
3836
reverification: removeReverification,
3937
});
@@ -43,22 +41,22 @@ export function useUserProfilePhoneSectionController({
4341
defaultPhoneCountry,
4442
canAdd: Boolean(onCreatePhone),
4543
verification,
46-
error: setPrimary.error,
47-
isDisabled: actionLock.isPending,
48-
pendingPrimaryId: setPrimary.pendingKey,
44+
error: actions.error,
45+
isDisabled: actions.isPending,
46+
pendingPrimaryId: actions.pendingKey,
4947
rowRef,
5048
registerTrigger: removalFocus.registerTrigger,
5149
remove: onRemovePhone ? remove : undefined,
5250
finalFocus: removalFocus.finalFocus,
5351
verificationFinalFocus: () => (verification.verifyingId ? removalFocus.trigger(verification.verifyingId) : null),
5452
setPrimaryReverification,
55-
setPrimaryFinalFocus: () => (setPrimary.lastKey ? removalFocus.trigger(setPrimary.lastKey) : null),
53+
setPrimaryFinalFocus: () => (actions.lastKey ? removalFocus.trigger(actions.lastKey) : null),
5654
onVerify: id => {
5755
const phone = phones.find(phone => phone.id === id);
5856
if (phone) {
5957
verification.onVerifyPhone(phone, getPhoneVerifier(id));
6058
}
6159
},
62-
onSetPrimary: id => void setPrimary.run(id, () => onSetPrimaryPhone(id)),
60+
onSetPrimary: id => void actions.run(id, () => onSetPrimaryPhone(id)),
6361
};
6462
}

0 commit comments

Comments
 (0)