fix(mosaic): suppress stale invitation success UI (#10551)

Author: austincalvelage

.changeset/tidy-invitation-completion.md

@@ -0,0 +1,5 @@
+---
+'@clerk/mosaic': patch
+---
+
+Suppress organization invitation success notifications when the members panel closes or the active organization or session changes before the invitation finishes.

packages/mosaic/AGENTS.md

@@ -34,7 +34,7 @@ Most problems a feature hits already have a shared answer. Find the row for your
 | Problem                                                                  | Use                                                                                                               |
 | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
 | An async action from a button or row: pending, an error, one lock        | `usePendingAction` (`src/hooks/`)                                                                                 |
-| A form: values, validation, submit, field errors                         | `useForm` (`src/components/form/`), with `validateAsync` for a server-side check                                  |
+| A form: values, validation, submit, field errors, success UI             | `useForm` (`src/components/form/`), with `validateAsync` for server checks and `onSuccess` for mounted success UI |
 | A `<form>` element, without the browser's validation popup               | `Form` (`src/primitives/form/`)                                                                                   |
 | A model save whose Clerk errors should land on form fields               | `save` (`src/utils/errors.ts`) in the model, or reject with `FormSubmitError`                                     |
 | A confirm step before an action                                          | `useConfirmController` (`src/blocks/confirm/`) with `Confirmation` (`src/blocks/confirmation/`)                   |

packages/mosaic/ARCHITECTURE.md

@@ -457,10 +457,8 @@ export function useUserProfileEditUsernameController({ username = '', required =
   const form = useForm({
     initialValues: { username },
     canSubmit: values => values.username !== username && (!required || values.username !== ''),
-    onSubmit: async values => {
-      await onSubmit(values.username);
-      setIsOpen(false);
-    },
+    onSubmit: values => onSubmit(values.username),
+    onSuccess: () => setIsOpen(false),
   });
 
   const onOpenChange = (open: boolean) => {

packages/mosaic/docs/controllers.md

@@ -121,13 +121,26 @@ boolean spelled long. `useUserProfileEditUsernameController` holds `isOpen` in
 const [isOpen, setIsOpen] = useState(false);
 const form = useForm({
   initialValues: { username },
-  onSubmit: async values => {
-    await onSubmit(values.username);
-    setIsOpen(false);
-  },
+  onSubmit: values => onSubmit(values.username),
+  onSuccess: () => setIsOpen(false),
 });
 ```
 
+Keep mutations and required revalidation in `onSubmit`. Put success UI, such as
+closing the dialog or showing a toast, in the optional synchronous
+`onSuccess(result, submittedValues)` callback. The result type comes from
+`onSubmit`. The callback and values belong to the submission that started the
+request. The form machine delivers success only while its actor is mounted.
+Rejection and cancelled reverification skip the callback.
+
+The callback runs during the completion transition, before `isSubmitting` clears.
+Use it to close or display UI, not to reset or resubmit the form. A resolved
+`onSubmit` counts as success even if it returned early. Prevent no-op submissions
+with `canSubmit`, or return a result that lets `onSuccess` distinguish them.
+Unmount suppression does not cancel the underlying request. Identity changes
+must unmount the form, for example through the composing component's React key,
+if they should discard its completion UI.
+
 The choice is invisible from outside — the controller returns plain props either
 way, so the view and its tests are unaffected, and swapping one for the other
 later is a change to one file. Don't front-load a machine for a flow that has

packages/mosaic/src/components/form/__tests__/use-form.test.ts

@@ -1,5 +1,7 @@
 import { ClerkRuntimeError } from '@clerk/shared/error';
 import { act, renderHook } from '@testing-library/react';
+import { createElement, StrictMode, useEffect, useLayoutEffect } from 'react';
+import { flushSync } from 'react-dom';
 import { describe, expect, expectTypeOf, it, vi } from 'vitest';
 
 import { deferred, tick } from '../../../__tests__/async';
@@ -66,6 +68,131 @@ describe('useForm', () => {
     expect(result.current.error).toBeUndefined();
   });
 
+  it('reports the exact result and submitted values once using the callback captured at submit', async () => {
+    const request = deferred<{ id: string }>();
+    const onSuccess = vi.fn();
+    const replacement = vi.fn();
+    const { result, rerender } = renderHook(
+      ({ onSuccess }) => useForm({ initialValues: { username: 'alex' }, onSubmit: () => request.promise, onSuccess }),
+      { initialProps: { onSuccess } },
+    );
+    act(() => result.current.setValue('username', 'alexc'));
+    const submittedValues = result.current.values;
+    act(() => result.current.submit());
+    act(() => result.current.submit());
+    rerender({ onSuccess: replacement });
+    const saved = { id: 'saved' };
+    await act(async () => {
+      request.resolve(saved);
+      await tick();
+    });
+    expect(onSuccess).toHaveBeenCalledExactlyOnceWith(saved, submittedValues);
+    expect(onSuccess.mock.calls[0]?.[0]).toBe(saved);
+    expect(onSuccess.mock.calls[0]?.[1]).toBe(submittedValues);
+    expect(replacement).not.toHaveBeenCalled();
+    expect(result.current.isSubmitting).toBe(false);
+  });
+
+  it.each([
+    new FormSubmitError({ message: 'Could not save' }),
+    new ClerkRuntimeError('User cancelled attempted verification', { code: 'reverification_cancelled' }),
+  ])('does not report success when submission rejects with %s', async failure => {
+    const onSuccess = vi.fn();
+    const { result } = renderHook(() =>
+      useForm({
+        initialValues: { username: 'alex' },
+        onSubmit: () => Promise.reject(failure),
+        onSuccess,
+      }),
+    );
+    await act(async () => {
+      result.current.submit();
+      await tick();
+    });
+    expect(onSuccess).not.toHaveBeenCalled();
+    expect(result.current.isSubmitting).toBe(false);
+  });
+
+  it('does not report success after unmounting a pending form', async () => {
+    const request = deferred<void>();
+    const onSuccess = vi.fn();
+    const { result, unmount } = renderHook(() =>
+      useForm({
+        initialValues: { username: 'alex' },
+        onSubmit: () => request.promise,
+        onSuccess,
+      }),
+    );
+    act(() => result.current.submit());
+    unmount();
+    await act(async () => {
+      request.resolve();
+      await tick();
+    });
+    expect(onSuccess).not.toHaveBeenCalled();
+  });
+
+  it('suppresses success when the request settles during unmount layout cleanup', async () => {
+    const request = deferred<void>();
+    const onSuccess = vi.fn();
+    const { result, unmount } = renderHook(() => {
+      const form = useForm({ initialValues: { username: 'alex' }, onSubmit: () => request.promise, onSuccess });
+      useLayoutEffect(() => () => request.resolve(), []);
+      return form;
+    });
+    act(() => result.current.submit());
+    unmount();
+    await act(tick);
+    expect(onSuccess).not.toHaveBeenCalled();
+  });
+
+  it('reports success once when StrictMode replays effects during submission', async () => {
+    const request = deferred<void>();
+    const onSubmit = vi.fn(() => request.promise);
+    const onEffect = vi.fn();
+    const onSuccess = vi.fn();
+    renderHook(
+      () => {
+        const form = useForm({ initialValues: { username: 'alex' }, onSubmit, onSuccess });
+        const { submit } = form;
+        useEffect(() => {
+          onEffect();
+          submit();
+        }, [submit]);
+        return form;
+      },
+      { wrapper: ({ children }) => createElement(StrictMode, null, children) },
+    );
+    expect(onEffect).toHaveBeenCalledTimes(2);
+    await act(async () => {
+      request.resolve();
+      await tick();
+    });
+    expect(onSubmit).toHaveBeenCalledOnce();
+    expect(onSuccess).toHaveBeenCalledOnce();
+  });
+
+  it('allows success to synchronously unmount the form before pending clears', async () => {
+    const request = deferred<void>();
+    const onSuccess = vi.fn(() => {
+      expect(result.current.isSubmitting).toBe(true);
+      flushSync(() => unmount());
+    });
+    const { result, unmount } = renderHook(() =>
+      useForm({
+        initialValues: { username: 'alex' },
+        onSubmit: () => request.promise,
+        onSuccess,
+      }),
+    );
+    act(() => result.current.submit());
+    await act(async () => {
+      request.resolve();
+      await tick();
+    });
+    expect(onSuccess).toHaveBeenCalledOnce();
+  });
+
   it('submits a value set in the same tick', () => {
     const onSubmit = vi.fn(resolved);
     const { result } = renderHook(() => useForm({ initialValues: { code: '' }, onSubmit }));

packages/mosaic/src/components/form/form.machine.ts

@@ -41,7 +41,7 @@ export interface AsyncFieldState {
 export interface FormDeps<TValues extends object> {
   initialValues: TValues;
   fields: FieldsConfig<TValues> | undefined;
-  onSubmit: (values: TValues) => Promise<unknown>;
+  onSubmit: (values: TValues) => Promise<() => void>;
   canSubmit: (values: TValues) => boolean;
   fallbackMessage: string;
   errorText: (error: LocalizableError) => string;
@@ -251,7 +251,7 @@ export function createFormMachine<TValues extends object>(deps: FormDeps<TValues
         invoke: fromPromise(async ctx => ctx.onSubmit(ctx.values), {
           onDone: {
             target: 'editing',
-            actions: assign(() => ({ error: undefined })),
+            actions: [assign(() => ({ error: undefined })), (_, event) => event.output()],
           },
           onError: [
             {

packages/mosaic/src/components/form/use-form.test-d.ts

@@ -0,0 +1,33 @@
+import { expectTypeOf, test } from 'vitest';
+
+import type { UseFormOptions, UseFormResult } from './use-form';
+import { useForm } from './use-form';
+
+test('infers success result and submitted values from the submission', () => {
+  useForm({
+    initialValues: { username: 'alex' },
+    onSubmit: values => Promise.resolve({ id: values.username, count: 1 }),
+    onSuccess: (result, submittedValues) => {
+      expectTypeOf(result).toEqualTypeOf<{ id: string; count: number }>();
+      expectTypeOf(submittedValues).toEqualTypeOf<{ username: string }>();
+    },
+  });
+});
+
+test('preserves explicit values generics and options without a success callback', () => {
+  const options: UseFormOptions<{ username: string }> = {
+    initialValues: { username: 'alex' },
+    onSubmit: () => Promise.resolve({ id: 'saved' }),
+  };
+  expectTypeOf(useForm<{ username: string }>(options)).toEqualTypeOf<UseFormResult<{ username: string }>>();
+});
+
+test('infers a void result for submissions without a return value', () => {
+  useForm({
+    initialValues: { username: 'alex' },
+    onSubmit: () => Promise.resolve(),
+    onSuccess: result => {
+      expectTypeOf(result).toEqualTypeOf<void>();
+    },
+  });
+});

packages/mosaic/src/components/form/use-form.ts

@@ -8,10 +8,11 @@ import type { FieldsConfig, FormContext, FormEvent } from './form.machine';
 import { createFormMachine, fieldConfig, fieldFeedback, firstInvalid, initialOf, isValid } from './form.machine';
 import type { FieldFeedback } from './form-submit-error';
 
-export interface UseFormOptions<TValues extends object> {
+export interface UseFormOptions<TValues extends object, TResult = unknown> {
   initialValues: TValues;
   fields?: FieldsConfig<TValues>;
-  onSubmit: (values: TValues) => Promise<unknown>;
+  onSubmit: (values: TValues) => Promise<TResult>;
+  onSuccess?: (result: TResult, submittedValues: TValues) => void;
   canSubmit?: (values: TValues) => boolean;
   errorFallback?: string;
 }
@@ -82,7 +83,9 @@ type ElementRef = (element: HTMLElement | null) => void;
 
 const always = () => true;
 
-export function useForm<TValues extends object>(options: UseFormOptions<TValues>): UseFormResult<TValues> {
+export function useForm<TValues extends object, TResult = unknown>(
+  options: UseFormOptions<TValues, TResult>,
+): UseFormResult<TValues> {
   const id = useId();
   const m = useMessages('form');
   const errorText = useErrorText();
@@ -92,7 +95,11 @@ export function useForm<TValues extends object>(options: UseFormOptions<TValues>
   const deps = {
     initialValues: options.initialValues,
     fields: options.fields,
-    onSubmit: options.onSubmit,
+    onSubmit: async (submittedValues: TValues) => {
+      const { onSubmit, onSuccess } = options;
+      const result = await onSubmit(submittedValues);
+      return () => onSuccess?.(result, submittedValues);
+    },
     canSubmit: options.canSubmit ?? always,
     fallbackMessage: options.errorFallback ?? m.error,
     errorText,

packages/mosaic/src/features/api-keys/create-api-key.controller.ts

@@ -49,13 +49,16 @@ export function useCreateAPIKeyController({
       if (expiration === null) {
         return;
       }
-      setSecret(
-        await onCreate({
-          name: name.trim(),
-          description: description.trim() || undefined,
-          expiresAt: getExpirationDate(expiration, new Date()),
-        }),
-      );
+      return onCreate({
+        name: name.trim(),
+        description: description.trim() || undefined,
+        expiresAt: getExpirationDate(expiration, new Date()),
+      });
+    },
+    onSuccess: secret => {
+      if (secret !== undefined) {
+        setSecret(secret);
+      }
     },
   });