DataViews: Add data picker functionality

packages/dataviews/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Features
+
+- Introduce a new `DataViewsPicker` component. [#70971](https://github.com/WordPress/gutenberg/pull/70971)
+
 ## 8.0.0 (2025-09-03)
 
 ### Breaking changes
@@ -11,6 +15,7 @@
 ### Enhancements
 
 -   DataForm: add description support for the combined fields and show the description in the Card layout ([#71380](https://github.com/WordPress/gutenberg/pull/71380)).
+-   Add support for hiding the `title` in Grid layouts, with the actions menu rendered over the media preview. [#71369](https://github.com/WordPress/gutenberg/pull/71369)
 
 ### Internal
 
@@ -21,10 +26,6 @@
 -   DataViews: Fix incorrect documentation for `defaultLayouts` prop. [#71334](https://github.com/WordPress/gutenberg/pull/71334)
 -   DataViews: Fix mismatched padding on mobile viewports for grid layout [#71455](https://github.com/WordPress/gutenberg/pull/71455)
 
-### Enhancements
-
-- Add support for hiding the `title` in Grid layouts, with the actions menu rendered over the media preview. [#71369](https://github.com/WordPress/gutenberg/pull/71369)
-
 ## 7.0.0 (2025-08-20)
 
 ### Breaking changes

packages/dataviews/README.md

@@ -381,12 +381,16 @@ The list of selected items' ids.
 
 If `selection` and `onChangeSelection` are provided, the `DataViews` component behaves like a controlled component. Otherwise, it behaves like an uncontrolled component.
 
+Note: `DataViews` still requires at least one bulk action to make items selectable.
+
 #### `onChangeSelection`: `function`
 
 Callback that signals the user selected one of more items. It receives the list of selected items' IDs as a parameter.
 
 If `selection` and `onChangeSelection` are provided, the `DataViews` component behaves like a controlled component. Otherwise, it behaves like an uncontrolled component.
 
+Note: `DataViews` still requires at least one bulk action to make items selectable.
+
 #### `isItemClickable`: `function`
 
 A function that determines if a media field or a primary field is clickable. It receives an item as an argument and returns a boolean value indicating whether the item can be clicked.
@@ -496,6 +500,78 @@ Developers don't need to worry about the internal accessibility logic for indivi
 
 `FiltersToggle` controls the visibility of the filters panel, and `Filters` renders the actual filters inside it. They work together and should always be used as a pair. While their internal behavior is accessible by default, how they’re positioned and grouped in custom layouts may affect the overall experience — especially for assistive technologies. Extra care is recommended.
 
+## `DataViewsPicker`
+
+<div class="callout callout-info">At <a href="https://wordpress.github.io/gutenberg/">WordPress Gutenberg's Storybook</a> there's an <a href="https://wordpress.github.io/gutenberg/?path=/docs/dataviews-dataviewspicker--docs">example implementation of the DataviewsPicker component</a>.</div>
+
+### Usage
+
+The `DataViewsPicker` component is very similar to the regular `DataViews` component, but is optimized for selection or picking of items.
+
+The component behaves differently to a regular `DataViews` component in the following ways:
+
+-   The items in the view are rendered using the `listbox` and `option` aria roles.
+-   Holding the `ctrl` or `cmd` key isn't required for multi-selection of items. The entire item can be clicked to select or deselect it.
+-   Individual items do not display any actions. All actions appear in the footer as text buttons.
+-   Selection is maintained across multiple pages when the component is paginated.
+
+There are also a few differences in the implementation:
+
+-   Currently only the `pickerGrid` layout is supported for `DataViewsPicker`. This layout is very similar to the regular `grid` layout.
+-   The picker component is used as a 'controlled' component, so `selection` and `onChangeSelection` should be provided as props. This is so that implementers can access the full range of selected items across pages.
+-   An optional `itemListLabel` prop can be supplied to the `DataViewsPicker` component. This is added as an `aria-label` to the `listbox` element, and should be supplied if there's no heading element associated with the `DataViewsPicker` UI.
+-   The `isItemClickable`, `renderItemLink` and `onClickItem` prop are unsupported for `DataViewsPicker`.
+-   To implement a multi-selection picker, ensure all actions are declared with `supportsBulk: true`. For single selection use `supportsBulk: false`. When a mixture of bulk and non-bulk actions are provided, the component falls back to single selection.
+-   Only the `callback` style of action is supported. `RenderModal` is unsupported.
+-   The `isEligible` callback for actions is unsupported.
+-   The `isPrimary` option for an action is used to render a `primary` variant of `Button` that can be used as a main call to action.
+
+Example:
+
+```jsx
+const Example = () => {
+	// When using DataViewsPicker, `selection` should be managed so that the component is 'controlled'.
+	const [ selection, setSelection ] = useState( [] );
+
+	// Both actions have `supportsBulk: true`, so the `DataViewsPicker` will allow multi-selection.
+	const actions = [
+		{
+			id: 'confirm',
+			label: 'Confirm',
+			isPrimary: true,
+			supportsBulk: true,
+			callback() {
+				window.alert( selection.join( ', ' ) );
+			},
+		},
+		{
+			id: 'cancel',
+			label: 'Cancel',
+			supportsBulk: true,
+			callback() {
+				setSelection( [] );
+			},
+		},
+	];
+
+	return (
+		<DataViewsPicker
+			actions={ actions }
+			data={ data }
+			fields={ fields }
+			view={ view }
+			onChangeView={ onChangeView }
+			defaultLayouts={ defaultLayouts }
+			paginationInfo={ paginationInfo }
+			selection={ selection }
+			onChangeSelection={ setSelection }
+		/>
+	);
+};
+```
+
+### Properties
+
 ## `DataForm`
 
 <div class="callout callout-info">At <a href="https://wordpress.github.io/gutenberg/">WordPress Gutenberg's Storybook</a> there's and <a href="https://wordpress.github.io/gutenberg/?path=/docs/dataviews-dataform--docs">example implementation of the DataForm component</a>.</div>

packages/dataviews/src/components/dataviews-context/index.ts

@@ -57,6 +57,7 @@ type DataViewsContextType< Item > = {
 	config: { perPageSizes: number[] };
 	empty?: ReactNode;
 	hasInfiniteScrollHandler: boolean;
+	itemListLabel?: string;
 };
 
 const DataViewsContext = createContext< DataViewsContextType< any > >( {

packages/dataviews/src/components/dataviews-layout/index.tsx

@@ -36,11 +36,13 @@ export default function DataViewsLayout( { className }: DataViewsLayoutProps ) {
 		onClickItem,
 		isItemClickable,
 		renderItemLink,
+		defaultLayouts,
 		empty = __( 'No results' ),
 	} = useContext( DataViewsContext );
 
-	const ViewComponent = VIEW_LAYOUTS.find( ( v ) => v.type === view.type )
-		?.component as ComponentType< ViewBaseProps< any > >;
+	const ViewComponent = VIEW_LAYOUTS.find(
+		( v ) => v.type === view.type && defaultLayouts[ v.type ]
+	)?.component as ComponentType< ViewBaseProps< any > >;
 
 	return (
 		<ViewComponent

packages/dataviews/src/components/dataviews-picker/footer.tsx

@@ -0,0 +1,207 @@
+/**
+ * WordPress dependencies
+ */
+import {
+	Button,
+	CheckboxControl,
+	__experimentalHStack as HStack,
+} from '@wordpress/components';
+import { useRegistry } from '@wordpress/data';
+import { useContext, useMemo, useState } from '@wordpress/element';
+import { __, sprintf, _n } from '@wordpress/i18n';
+
+/**
+ * Internal dependencies
+ */
+import DataViewsPagination from '../dataviews-pagination';
+import DataViewsContext from '../dataviews-context';
+import type { SetSelection } from '../../private-types';
+import type { Action } from '../../types';
+
+const EMPTY_ARRAY: [] = [];
+
+export function useIsMultiselectPicker< Item >(
+	actions: Action< Item >[] | undefined
+) {
+	return useMemo( () => {
+		return actions?.every( ( action ) => action.supportsBulk );
+	}, [ actions ] );
+}
+
+function BulkSelectionCheckbox< Item >( {
+	selection,
+	selectedItems,
+	onChangeSelection,
+	data,
+	getItemId,
+}: {
+	selection: string[];
+	selectedItems: Item[];
+	onChangeSelection: SetSelection;
+	data: Item[];
+	getItemId: ( item: Item ) => string;
+} ) {
+	const areAllSelected = selectedItems.length === data.length;
+
+	return (
+		<CheckboxControl
+			className="dataviews-view-table-selection-checkbox"
+			__nextHasNoMarginBottom
+			checked={ areAllSelected }
+			indeterminate={ ! areAllSelected && !! selectedItems.length }
+			onChange={ () => {
+				if ( areAllSelected ) {
+					// Deselect all - remove the current page from the total selection.
+					onChangeSelection(
+						selection.filter(
+							( id ) =>
+								! data.some(
+									( item ) => id === getItemId( item )
+								)
+						)
+					);
+				} else {
+					// Select all - merge the current page into the total selection.
+					const selectionSet = new Set( [
+						...selection,
+						...data.map( ( item ) => getItemId( item ) ),
+					] );
+					onChangeSelection( Array.from( selectionSet ) );
+				}
+			} }
+			aria-label={
+				areAllSelected ? __( 'Deselect all' ) : __( 'Select all' )
+			}
+		/>
+	);
+}
+
+function ActionButtons< Item >( {
+	actions,
+	items,
+	selection,
+}: {
+	actions: Action< Item >[];
+	items: Item[];
+	selection: string[];
+} ) {
+	const registry = useRegistry();
+	const [ actionInProgress, setActionInProgress ] = useState< string | null >(
+		null
+	);
+
+	return (
+		<HStack expanded={ false } spacing={ 1 }>
+			{ actions.map( ( action ) => {
+				// Only support actions with callbacks for DataViewsPicker.
+				// This is because many use cases of the picker will be already within modals.
+				if ( ! ( 'callback' in action ) ) {
+					return null;
+				}
+
+				const { id, label, icon, isPrimary, isDestructive, callback } =
+					action;
+
+				const _label =
+					typeof label === 'string' ? label : label( items );
+				const variant = isPrimary ? 'primary' : 'tertiary';
+				const isInProgress = id === actionInProgress;
+
+				return (
+					<Button
+						key={ id }
+						accessibleWhenDisabled
+						icon={ icon }
+						disabled={ isInProgress || ! selection?.length }
+						isBusy={ isInProgress }
+						onClick={ async () => {
+							setActionInProgress( id );
+							await callback( items, {
+								registry,
+							} );
+							setActionInProgress( null );
+						} }
+						size="compact"
+						isDestructive={ isDestructive }
+						variant={ variant }
+					>
+						{ _label }
+					</Button>
+				);
+			} ) }
+		</HStack>
+	);
+}
+
+export function DataViewsPickerFooter() {
+	const {
+		data,
+		selection,
+		onChangeSelection,
+		getItemId,
+		actions = EMPTY_ARRAY,
+	} = useContext( DataViewsContext );
+
+	const selectionCount = selection.length;
+	const isMultiselect = useIsMultiselectPicker( actions );
+
+	const message =
+		selectionCount > 0
+			? sprintf(
+					/* translators: %d: number of items. */
+					_n(
+						'%d Item selected',
+						'%d Items selected',
+						selectionCount
+					),
+					selectionCount
+			  )
+			: sprintf(
+					/* translators: %d: number of items. */
+					_n( '%d Item', '%d Items', data.length ),
+					data.length
+			  );
+
+	const selectedItems = useMemo(
+		() =>
+			data.filter( ( item ) => selection.includes( getItemId( item ) ) ),
+		[ selection, getItemId, data ]
+	);
+
+	return (
+		<HStack
+			expanded={ false }
+			justify="space-between"
+			className="dataviews-footer"
+		>
+			<HStack
+				className="dataviews-picker-footer__bulk-selection"
+				expanded={ false }
+				spacing={ 3 }
+			>
+				{ isMultiselect && (
+					<BulkSelectionCheckbox
+						selection={ selection }
+						selectedItems={ selectedItems }
+						onChangeSelection={ onChangeSelection }
+						data={ data }
+						getItemId={ getItemId }
+					/>
+				) }
+				<span className="dataviews-bulk-actions-footer__item-count">
+					{ message }
+				</span>
+			</HStack>
+			<DataViewsPagination />
+			{ Boolean( actions?.length ) && (
+				<div className="dataviews-picker-footer__actions">
+					<ActionButtons
+						actions={ actions }
+						items={ selectedItems }
+						selection={ selection }
+					/>
+				</div>
+			) }
+		</HStack>
+	);
+}