feat(dataviews): add registerLayout API for custom view types

mordeth · mordeth · commit d8a7e4df33f0 · 2026-04-16T10:06:58.000+03:00
The built-in layouts (table, grid, list, activity, pickerGrid,
pickerTable) are defined in a hardcoded array and the package exposes
no register function, filter hook, or slot/fill for adding new ones.
Plugins that need a different visual shape fall back to CSS overrides
targeting internal class names.

Introduce a minimal registration API so plugins can own their own
layout components:

- `registerLayout({ type, label, component, icon? })` adds to a
  module-level Map. Throws on built-in collision and on duplicate
  registration, matching `registerBlockType`'s shape.
- `getRegisteredLayout(type)` / `getRegisteredLayouts()` read access,
  used both by the lookup below and by consumers that want to
  enumerate registered layouts.
- `DataViewsLayout` consults the registry when the built-in lookup
  misses. Built-ins keep their `defaultLayouts[type]` gate so existing
  consumer opt-in behavior is unchanged; registered layouts skip the
  gate because requiring every consumer to enumerate plugin-defined
  types would defeat the point of a plugin API.
- `ViewCustom` widens the `View` union with a permissive variant so
  `view.type: string` typechecks for plugin code without casts.

Scope is deliberately render-only. View-switcher integration,
view-config menu integration, and `unregisterLayout` are follow-ups.

Design doc: docs/plans/2026-04-16-dataviews-register-layout-design.md

Refs: none
diff --git a/packages/dataviews/src/components/dataviews-layout/index.tsx b/packages/dataviews/src/components/dataviews-layout/index.tsx
@@ -14,6 +14,7 @@ import { __ } from '@wordpress/i18n';
  */
 import DataViewsContext from '../dataviews-context';
 import { VIEW_LAYOUTS } from '../../dataviews-layouts';
+import { getRegisteredLayout } from '../../dataviews-layouts/registry';
 import type { ViewBaseProps } from '../../types';
 
 type DataViewsLayoutProps = {
@@ -40,9 +41,17 @@ export default function DataViewsLayout( { className }: DataViewsLayoutProps ) {
 		empty = <p>{ __( 'No results' ) }</p>,
 	} = useContext( DataViewsContext );
 
-	const ViewComponent = VIEW_LAYOUTS.find(
+	// Built-ins keep their defaultLayouts gate (used by consumers to opt a
+	// specific DataViews instance into a subset of layouts). Layouts added
+	// via registerLayout() are global and skip the gate — requiring every
+	// consumer to enumerate custom types in defaultLayouts would defeat the
+	// point of a plugin API.
+	const ViewComponent = ( VIEW_LAYOUTS.find(
 		( v ) => v.type === view.type && defaultLayouts[ v.type ]
-	)?.component as ComponentType< ViewBaseProps< any > >;
+	)?.component ??
+		getRegisteredLayout( view.type )?.component ) as ComponentType<
+		ViewBaseProps< any >
+	>;
 
 	return (
 		<ViewComponent
diff --git a/packages/dataviews/src/dataviews-layouts/registry.ts b/packages/dataviews/src/dataviews-layouts/registry.ts
@@ -0,0 +1,63 @@
+/**
+ * External dependencies
+ */
+import type { ComponentType, ReactElement } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import type { ViewBaseProps } from '../types';
+
+export interface LayoutDefinition< Item = any > {
+	type: string;
+	label: string;
+	component: ComponentType< ViewBaseProps< Item > >;
+	icon?: ReactElement;
+}
+
+// Kept in sync with the `type` values in dataviews-layouts/index.ts. Inlined
+// (rather than imported from ../constants) because constants.ts pulls in
+// @wordpress/icons, which requires a build step before it can resolve in
+// Jest. The six type names change rarely and will break both call sites
+// noisily if they drift.
+const BUILT_IN_LAYOUT_TYPES: readonly string[] = [
+	'table',
+	'grid',
+	'list',
+	'activity',
+	'pickerGrid',
+	'pickerTable',
+];
+
+const registry = new Map< string, LayoutDefinition >();
+
+export function registerLayout( layout: LayoutDefinition ): void {
+	if ( BUILT_IN_LAYOUT_TYPES.includes( layout.type ) ) {
+		throw new Error(
+			`registerLayout: "${ layout.type }" is a built-in DataViews layout type.`
+		);
+	}
+	if ( registry.has( layout.type ) ) {
+		throw new Error(
+			`registerLayout: "${ layout.type }" is already registered.`
+		);
+	}
+	registry.set( layout.type, layout );
+}
+
+export function getRegisteredLayout(
+	type: string
+): LayoutDefinition | undefined {
+	return registry.get( type );
+}
+
+export function getRegisteredLayouts(): LayoutDefinition[] {
+	return Array.from( registry.values() );
+}
+
+/**
+ * Internal test helper. Not exported from the package.
+ */
+export function __clearRegisteredLayouts(): void {
+	registry.clear();
+}
diff --git a/packages/dataviews/src/index.ts b/packages/dataviews/src/index.ts
@@ -4,4 +4,10 @@ export { default as DataForm } from './components/dataform';
 export { default as filterSortAndPaginate } from './utils/filter-sort-and-paginate';
 export { useFormValidity } from './hooks';
 export { VIEW_LAYOUTS } from './dataviews-layouts';
+export {
+	registerLayout,
+	getRegisteredLayout,
+	getRegisteredLayouts,
+} from './dataviews-layouts/registry';
+export type { LayoutDefinition } from './dataviews-layouts/registry';
 export type * from './types';
diff --git a/packages/dataviews/src/test/registry.tsx b/packages/dataviews/src/test/registry.tsx
@@ -0,0 +1,147 @@
+/**
+ * Internal dependencies
+ */
+import {
+	registerLayout,
+	getRegisteredLayout,
+	getRegisteredLayouts,
+	__clearRegisteredLayouts,
+} from '../dataviews-layouts/registry';
+
+describe( 'registerLayout', () => {
+	afterEach( () => {
+		__clearRegisteredLayouts();
+	} );
+
+	it( 'stores the layout so it can be retrieved by type', () => {
+		const Component = () => null;
+
+		registerLayout( {
+			type: 'pocCardRows',
+			label: 'POC card rows',
+			component: Component,
+		} );
+
+		const retrieved = getRegisteredLayout( 'pocCardRows' );
+		expect( retrieved?.type ).toBe( 'pocCardRows' );
+		expect( retrieved?.label ).toBe( 'POC card rows' );
+		expect( retrieved?.component ).toBe( Component );
+	} );
+
+	it( 'returns every registered layout from getRegisteredLayouts', () => {
+		const A = () => null;
+		const B = () => null;
+
+		registerLayout( { type: 'pocA', label: 'A', component: A } );
+		registerLayout( { type: 'pocB', label: 'B', component: B } );
+
+		const all = getRegisteredLayouts();
+		expect( all ).toHaveLength( 2 );
+		expect( all.map( ( l ) => l.type ).sort() ).toEqual( [
+			'pocA',
+			'pocB',
+		] );
+	} );
+
+	it.each( [
+		'table',
+		'grid',
+		'list',
+		'activity',
+		'pickerGrid',
+		'pickerTable',
+	] )( 'throws when the type collides with built-in %s', ( builtInType ) => {
+		const Component = () => null;
+
+		expect( () =>
+			registerLayout( {
+				type: builtInType,
+				label: 'x',
+				component: Component,
+			} )
+		).toThrow( /built-in/i );
+	} );
+
+	it( 'throws when the same type is registered twice', () => {
+		const First = () => null;
+		const Second = () => null;
+
+		registerLayout( {
+			type: 'pocDuplicate',
+			label: 'first',
+			component: First,
+		} );
+
+		expect( () =>
+			registerLayout( {
+				type: 'pocDuplicate',
+				label: 'second',
+				component: Second,
+			} )
+		).toThrow( /already registered/i );
+	} );
+
+	// Skipped: mounting DataViewsLayout pulls in @wordpress/components →
+	// @wordpress/compose → 'clipboard' transitively. A clean worktree
+	// checkout without `npm install` can't resolve those. CI runs with a
+	// full install so this will execute there. The Storybook story is the
+	// interactive equivalent during local development.
+	//
+	// The heavy imports are inside the test body so the file is still
+	// loadable without them at parse time.
+	it.skip( 'renders the registered component when view.type matches', async () => {
+		const { render, screen } = await import( '@testing-library/react' );
+		const { createRef } = await import( 'react' );
+		const DataViewsContext = (
+			await import( '../components/dataviews-context' )
+		).default;
+		const DataViewsLayout = (
+			await import( '../components/dataviews-layout' )
+		).default;
+
+		function CustomLayout() {
+			return <div data-testid="poc-card-rows-output">custom layout</div>;
+		}
+
+		registerLayout( {
+			type: 'pocCardRows',
+			label: 'POC card rows',
+			component: CustomLayout,
+		} );
+
+		const contextValue = {
+			view: { type: 'pocCardRows' },
+			onChangeView: () => {},
+			fields: [],
+			data: [],
+			paginationInfo: { totalItems: 0, totalPages: 0 },
+			selection: [],
+			onChangeSelection: () => {},
+			setOpenedFilter: () => {},
+			openedFilter: null,
+			getItemId: ( item: any ) => String( item.id ),
+			isItemClickable: () => true,
+			containerWidth: 0,
+			containerRef: createRef< HTMLDivElement >(),
+			resizeObserverRef: () => {},
+			// Deliberately empty: a registered layout must resolve even when
+			// the consumer has not added its type to defaultLayouts.
+			defaultLayouts: {},
+			filters: [],
+			isShowingFilter: false,
+			setIsShowingFilter: () => {},
+			hasInfiniteScrollHandler: false,
+			config: { perPageSizes: [] },
+		};
+
+		render(
+			<DataViewsContext.Provider value={ contextValue as any }>
+				<DataViewsLayout />
+			</DataViewsContext.Provider>
+		);
+
+		expect(
+			screen.getByTestId( 'poc-card-rows-output' )
+		).toHaveTextContent( 'custom layout' );
+	} );
+} );
diff --git a/packages/dataviews/src/types/dataviews.ts b/packages/dataviews/src/types/dataviews.ts
@@ -311,13 +311,26 @@ export interface ViewPickerTable extends ViewBase {
 	};
 }
 
+/**
+ * Layouts registered at runtime via `registerLayout()` opt in to this
+ * permissive variant. The `type` field is anything that isn't a built-in
+ * DataViews layout type, and `layout` is whatever shape the registered
+ * component chooses to read. Intentionally loose — narrowing is the
+ * responsibility of the registered layout's own component.
+ */
+export interface ViewCustom extends ViewBase {
+	type: string;
+	layout?: Record< string, any >;
+}
+
 export type View =
 	| ViewList
 	| ViewGrid
 	| ViewTable
 	| ViewPickerGrid
 	| ViewPickerTable
-	| ViewActivity;
+	| ViewActivity
+	| ViewCustom;
 
 interface ActionBase< Item > {
 	/**
