ActionModal: Add support for customisable focusOnMount (WordPress#69609)

yogeshbhutkar · yogeshbhutkar · ciampo · chriszarate · commit 5a95a457f8dd · 2025-07-01T09:28:00.000-06:00
* feat: support customisable `focusOnMount`

* fix: ensure `focusOnMount` defaults to true in ActionModal

* feat: add `modalFocusOnMount` property to all eligible actions

* feat: add `modalFocusOnMount` property to ActionModal fixture

Co-authored-by: yogeshbhutkar &lt;yogeshbhutkar@git.wordpress.org&gt;
Co-authored-by: ciampo &lt;mciampini@git.wordpress.org&gt;
Co-authored-by: t-hamano &lt;wildworks@git.wordpress.org&gt;
Co-authored-by: himanshupathak95 &lt;abcd95@git.wordpress.org&gt;
Co-authored-by: afercia &lt;afercia@git.wordpress.org&gt;
Co-authored-by: oandregal &lt;oandregal@git.wordpress.org&gt;
diff --git a/packages/dataviews/README.md b/packages/dataviews/README.md
@@ -722,6 +722,23 @@ Example:
 }
 ```
 
+### `modalFocusOnMount`
+
+Specifies the focus on mount property of the modal.
+
+-	Type: `boolean` | `string`
+-	Optional
+-	Default: `true`
+-	One of: `true` | `false` | `'firstElement'` | `'firstContentElement'`
+
+Example:
+
+```js
+{
+	modalFocusOnMount: 'firstContentElement';
+}
+```
+
 ## Fields API
 
 ### `id`
diff --git a/packages/dataviews/src/components/dataviews-item-actions/index.tsx b/packages/dataviews/src/components/dataviews-item-actions/index.tsx
@@ -110,7 +110,7 @@ export function ActionModal< Item >( {
 			title={ action.modalHeader || label }
 			__experimentalHideHeader={ !! action.hideModalHeader }
 			onRequestClose={ closeModal }
-			focusOnMount="firstContentElement"
+			focusOnMount={ action.modalFocusOnMount ?? true }
 			size={ action.modalSize || 'medium' }
 			overlayClassName={ `dataviews-action-modal dataviews-action-modal__${ kebabCase(
 				action.id
diff --git a/packages/dataviews/src/components/dataviews/stories/fixtures.tsx b/packages/dataviews/src/components/dataviews/stories/fixtures.tsx
@@ -582,6 +582,7 @@ export const actions: Action< SpaceObject >[] = [
 		isPrimary: true,
 		icon: trash,
 		hideModalHeader: true,
+		modalFocusOnMount: 'firstContentElement',
 		RenderModal: ( { items, closeModal } ) => {
 			return (
 				<VStack spacing="5">
diff --git a/packages/dataviews/src/types.ts b/packages/dataviews/src/types.ts
@@ -8,6 +8,11 @@ import type { ReactElement, ComponentType } from 'react';
  */
 import type { SetSelection } from './private-types';
 
+/**
+ * WordPress dependencies
+ */
+import type { useFocusOnMount } from '@wordpress/compose';
+
 export type SortDirection = 'asc' | 'desc';
 
 /**
@@ -470,6 +475,13 @@ export interface ActionModal< Item > extends ActionBase< Item > {
 	 * @default 'medium'
 	 */
 	modalSize?: 'small' | 'medium' | 'large' | 'fill';
+
+	/**
+	 * The focus on mount property of the modal.
+	 */
+	modalFocusOnMount?:
+		| Parameters< typeof useFocusOnMount >[ 0 ]
+		| 'firstContentElement';
 }
 
 export interface ActionButton< Item > extends ActionBase< Item > {
diff --git a/packages/editor/src/components/post-actions/set-as-homepage.js b/packages/editor/src/components/post-actions/set-as-homepage.js
@@ -160,6 +160,7 @@ export const useSetAsHomepageAction = () => {
 
 				return true;
 			},
+			modalFocusOnMount: 'firstContentElement',
 			RenderModal: SetAsHomepageModal,
 		} ),
 		[ pageForPosts, pageOnFront ]
diff --git a/packages/editor/src/components/post-actions/set-as-posts-page.js b/packages/editor/src/components/post-actions/set-as-posts-page.js
@@ -157,6 +157,7 @@ export const useSetAsPostsPageAction = () => {
 
 				return true;
 			},
+			modalFocusOnMount: 'firstContentElement',
 			RenderModal: SetAsPostsPageModal,
 		} ),
 		[ pageForPosts, pageOnFront ]
diff --git a/packages/fields/src/actions/delete-post.tsx b/packages/fields/src/actions/delete-post.tsx
@@ -47,6 +47,7 @@ const deletePostAction: Action< Template | TemplatePart | Pattern > = {
 	},
 	supportsBulk: true,
 	hideModalHeader: true,
+	modalFocusOnMount: 'firstContentElement',
 	RenderModal: ( { items, closeModal, onActionPerformed } ) => {
 		const [ isBusy, setIsBusy ] = useState( false );
 		const isResetting = items.every(
diff --git a/packages/fields/src/actions/duplicate-pattern.tsx b/packages/fields/src/actions/duplicate-pattern.tsx
@@ -21,6 +21,7 @@ const duplicatePattern: Action< Pattern > = {
 	label: _x( 'Duplicate', 'action label' ),
 	isEligible: ( item ) => item.type !== 'wp_template_part',
 	modalHeader: _x( 'Duplicate pattern', 'action label' ),
+	modalFocusOnMount: 'firstContentElement',
 	RenderModal: ( { items, closeModal } ) => {
 		const [ item ] = items;
 		const duplicatedProps = useDuplicatePatternProps( {
diff --git a/packages/fields/src/actions/duplicate-post.tsx b/packages/fields/src/actions/duplicate-post.tsx
@@ -33,6 +33,7 @@ const duplicatePost: Action< BasePost > = {
 	isEligible( { status } ) {
 		return status !== 'trash';
 	},
+	modalFocusOnMount: 'firstContentElement',
 	RenderModal: ( { items, closeModal, onActionPerformed } ) => {
 		const [ item, setItem ] = useState< BasePost >( {
 			...items[ 0 ],
diff --git a/packages/fields/src/actions/duplicate-template-part.tsx b/packages/fields/src/actions/duplicate-template-part.tsx
@@ -24,6 +24,7 @@ const duplicateTemplatePart: Action< TemplatePart > = {
 	label: _x( 'Duplicate', 'action label' ),
 	isEligible: ( item ) => item.type === 'wp_template_part',
 	modalHeader: _x( 'Duplicate template part', 'action label' ),
+	modalFocusOnMount: 'firstContentElement',
 	RenderModal: ( { items, closeModal } ) => {
 		const [ item ] = items;
 		const blocks = useMemo( () => {
diff --git a/packages/fields/src/actions/permanently-delete-post.tsx b/packages/fields/src/actions/permanently-delete-post.tsx
@@ -35,6 +35,7 @@ const permanentlyDeletePost: Action< PostWithPermissions > = {
 		return status === 'trash' && permissions?.delete;
 	},
 	hideModalHeader: true,
+	modalFocusOnMount: 'firstContentElement',
 	RenderModal: ( { items, closeModal, onActionPerformed } ) => {
 		const [ isBusy, setIsBusy ] = useState( false );
 		const { createSuccessNotice, createErrorNotice } =
diff --git a/packages/fields/src/actions/rename-post.tsx b/packages/fields/src/actions/rename-post.tsx
@@ -35,6 +35,7 @@ const { PATTERN_TYPES } = unlock( patternsPrivateApis );
 const renamePost: Action< PostWithPermissions > = {
 	id: 'rename-post',
 	label: __( 'Rename' ),
+	modalFocusOnMount: 'firstContentElement',
 	isEligible( post ) {
 		if ( post.status === 'trash' ) {
 			return false;
diff --git a/packages/fields/src/actions/reorder-page.tsx b/packages/fields/src/actions/reorder-page.tsx
@@ -119,6 +119,7 @@ const reorderPage: Action< BasePost > = {
 	isEligible( { status } ) {
 		return status !== 'trash';
 	},
+	modalFocusOnMount: 'firstContentElement',
 	RenderModal: ReorderModal,
 };
 
diff --git a/packages/fields/src/actions/reset-post.tsx b/packages/fields/src/actions/reset-post.tsx
@@ -189,6 +189,7 @@ const resetPostAction: Action< Template | TemplatePart > = {
 	icon: backup,
 	supportsBulk: true,
 	hideModalHeader: true,
+	modalFocusOnMount: 'firstContentElement',
 	RenderModal: ( { items, closeModal, onActionPerformed } ) => {
 		const [ isBusy, setIsBusy ] = useState( false );
 
diff --git a/packages/fields/src/actions/trash-post.tsx b/packages/fields/src/actions/trash-post.tsx
@@ -39,6 +39,7 @@ const trashPost: Action< PostWithPermissions > = {
 	},
 	supportsBulk: true,
 	hideModalHeader: true,
+	modalFocusOnMount: 'firstContentElement',
 	RenderModal: ( { items, closeModal, onActionPerformed } ) => {
 		const [ isBusy, setIsBusy ] = useState( false );
 		const { createSuccessNotice, createErrorNotice } =
