[toast] Add focus option to move focus to toast on open

docs/src/app/(docs)/react/components/toast/demos/undo/css-modules/index.tsx

@@ -24,6 +24,7 @@ function Form() {
       title: 'Action performed',
       description: 'You can undo this action.',
       type: 'success',
+      focus: true,
       actionProps: {
         children: 'Undo',
         onClick() {

docs/src/app/(docs)/react/components/toast/types.md

@@ -106,6 +106,13 @@ type ToastRootToastObject<Data extends {} = any> = {
   onClose?: () => void;
   /** Callback function to be called when the toast is removed from the list after any animations are complete when closed. */
   onRemove?: () => void;
+  /**
+   * Whether to move focus to the toast when it opens.
+   * When `true`, the previously focused element is saved and restored when the toast closes.
+   * Timers are paused while the toast has focus.
+   * @default false
+   */
+  focus?: boolean;
   /** The props for the action button. */
   actionProps?: Omit<
     React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>,
@@ -565,6 +572,13 @@ type ToastObject<Data extends {}> = {
   onClose?: () => void;
   /** Callback function to be called when the toast is removed from the list after any animations are complete when closed. */
   onRemove?: () => void;
+  /**
+   * Whether to move focus to the toast when it opens.
+   * When `true`, the previously focused element is saved and restored when the toast closes.
+   * Timers are paused while the toast has focus.
+   * @default false
+   */
+  focus?: boolean;
   /** The props for the action button. */
   actionProps?: Omit<
     React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>,
@@ -629,6 +643,13 @@ type ToastManagerAddOptions<Data extends {}> = {
   onClose?: () => void;
   /** Callback function to be called when the toast is removed from the list after any animations are complete when closed. */
   onRemove?: () => void;
+  /**
+   * Whether to move focus to the toast when it opens.
+   * When `true`, the previously focused element is saved and restored when the toast closes.
+   * Timers are paused while the toast has focus.
+   * @default false
+   */
+  focus?: boolean;
   /** The props for the action button. */
   actionProps?: Omit<
     React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>,
@@ -849,6 +870,13 @@ type ToastManagerUpdateOptions<Data extends {}> = {
   onClose?: () => void;
   /** Callback function to be called when the toast is removed from the list after any animations are complete when closed. */
   onRemove?: () => void;
+  /**
+   * Whether to move focus to the toast when it opens.
+   * When `true`, the previously focused element is saved and restored when the toast closes.
+   * Timers are paused while the toast has focus.
+   * @default false
+   */
+  focus?: boolean;
   /** The props for the action button. */
   actionProps?: Omit<
     React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>,

packages/react/src/toast/root/ToastRoot.test.tsx

@@ -746,4 +746,76 @@ describe('<Toast.Root />', () => {
       });
     });
   });
+
+  describe('focus option', () => {
+    it('moves focus to the toast when focus is true', async () => {
+      function AddButton() {
+        const { add } = Toast.useToastManager();
+        return (
+          <button
+            type="button"
+            data-testid="trigger"
+            onClick={() => {
+              add({
+                title: 'Focused toast',
+                focus: true,
+              });
+            }}
+          >
+            add
+          </button>
+        );
+      }
+
+      await render(
+        <Toast.Provider>
+          <AddButton />
+          <Toast.Viewport>
+            <List />
+          </Toast.Viewport>
+        </Toast.Provider>,
+      );
+
+      const trigger = screen.getByTestId('trigger');
+      fireEvent.click(trigger);
+
+      await waitFor(() => {
+        const toastRoot = screen.getByTestId('root');
+        expect(toastRoot).toHaveFocus();
+      });
+    });
+
+    it('does not move focus when focus is not set', async () => {
+      function AddButton() {
+        const { add } = Toast.useToastManager();
+        return (
+          <button
+            type="button"
+            data-testid="trigger"
+            onClick={() => {
+              add({ title: 'Normal toast' });
+            }}
+          >
+            add
+          </button>
+        );
+      }
+
+      await render(
+        <Toast.Provider>
+          <AddButton />
+          <Toast.Viewport>
+            <List />
+          </Toast.Viewport>
+        </Toast.Provider>,
+      );
+
+      const trigger = screen.getByTestId('trigger');
+      fireEvent.click(trigger);
+
+      await waitFor(() => {
+        expect(screen.getByTestId('root')).not.toHaveFocus();
+      });
+    });
+  });
 });

packages/react/src/toast/root/ToastRoot.tsx

@@ -178,6 +178,19 @@ export const ToastRoot = React.forwardRef(function ToastRoot(
 
   useIsoLayoutEffect(recalculateHeight, [recalculateHeight]);
 
+  React.useEffect(() => {
+    if (!toast.focus || !rootRef.current) {
+      return;
+    }
+
+    const doc = ownerDocument(rootRef.current);
+    store.setPrevFocusElement(activeElement(doc) as HTMLElement | null);
+    rootRef.current.focus({ preventScroll: true });
+    store.pauseTimers();
+    store.setFocused(true);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
   function applyDirectionalDamping(deltaX: number, deltaY: number) {
     let newDeltaX = deltaX;
     let newDeltaY = deltaY;

packages/react/src/toast/useToastManager.ts

@@ -86,6 +86,13 @@ export interface ToastObject<Data extends object> {
    * Callback function to be called when the toast is removed from the list after any animations are complete when closed.
    */
   onRemove?: (() => void) | undefined;
+  /**
+   * Whether to move focus to the toast when it opens.
+   * When `true`, the previously focused element is saved and restored when the toast closes.
+   * Timers are paused while the toast has focus.
+   * @default false
+   */
+  focus?: boolean | undefined;
   /**
    * The props for the action button.
    */