@wordpress/widget-dashboard 0.1.0

package/src/test/widget-inserter.test.tsx

@@ -0,0 +1,210 @@
+/**
+ * External dependencies
+ */
+import '@testing-library/jest-dom';
+import { render, screen, waitFor, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import type { ComponentType } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+import type {
+	ResolveWidgetModule,
+	WidgetRenderProps,
+	WidgetType,
+} from '@wordpress/widget-primitives';
+
+/**
+ * Internal dependencies
+ */
+import { WidgetDashboard } from '../widget-dashboard';
+import type { DashboardWidget } from '../types';
+
+function PreviewWidget( {
+	attributes,
+}: WidgetRenderProps< { label?: string } > ) {
+	return <div data-testid="widget-content">{ attributes?.label ?? '—' }</div>;
+}
+
+const widgetTypes: WidgetType[] = [
+	{
+		apiVersion: 1,
+		name: 'wordpress/welcome',
+		title: 'Welcome',
+		renderModule: 'welcome-module',
+		example: { attributes: { label: 'welcome-example' } },
+	},
+	{
+		apiVersion: 1,
+		name: 'wordpress/notes',
+		title: 'Notes',
+		renderModule: 'notes-module',
+		example: { attributes: { label: 'notes-example' } },
+	},
+];
+
+const resolveWidgetModule: ResolveWidgetModule = async () => ( {
+	default: PreviewWidget as ComponentType< WidgetRenderProps< unknown > >,
+} );
+
+interface HarnessProps {
+	initialLayout?: DashboardWidget[];
+	onLayoutChange?: ( layout: DashboardWidget[] ) => void;
+}
+
+function Harness( {
+	initialLayout = [],
+	onLayoutChange: onChange,
+}: HarnessProps ) {
+	const [ layout, setLayout ] =
+		useState< DashboardWidget[] >( initialLayout );
+	const [ editMode, setEditMode ] = useState( true );
+
+	return (
+		<WidgetDashboard
+			layout={ layout }
+			onLayoutChange={ ( next ) => {
+				setLayout( next );
+				onChange?.( next );
+			} }
+			widgetTypes={ widgetTypes }
+			editMode={ editMode }
+			onEditChange={ setEditMode }
+			resolveWidgetModule={ resolveWidgetModule }
+		/>
+	);
+}
+
+describe( 'WidgetDashboard.WidgetInserter', () => {
+	it( 'is hidden until the "Add widget" trigger is clicked', () => {
+		render( <Harness /> );
+		expect(
+			screen.queryByRole( 'dialog', { name: 'Add widget' } )
+		).not.toBeInTheDocument();
+	} );
+
+	it( 'opens after clicking the "Add widget" trigger', async () => {
+		const user = userEvent.setup();
+		render( <Harness /> );
+
+		await user.click(
+			screen.getByRole( 'button', { name: 'Add widget' } )
+		);
+
+		expect(
+			await screen.findByRole( 'dialog', { name: 'Add widget' } )
+		).toBeInTheDocument();
+	} );
+
+	it( 'inserts the selected widget type into the layout on Done', async () => {
+		const user = userEvent.setup();
+		const onLayoutChange = jest.fn();
+		render( <Harness onLayoutChange={ onLayoutChange } /> );
+
+		await user.click(
+			screen.getByRole( 'button', { name: 'Add widget' } )
+		);
+
+		const dialog = await screen.findByRole( 'dialog', {
+			name: 'Add widget',
+		} );
+		const options = within( dialog ).getAllByRole( 'option' );
+		expect( options ).toHaveLength( widgetTypes.length );
+
+		await user.click( options[ 0 ] );
+		await user.click(
+			within( dialog ).getByRole( 'button', { name: 'Select' } )
+		);
+
+		// Inserts stay in staging until Done.
+		expect( onLayoutChange ).not.toHaveBeenCalled();
+
+		await waitFor( () =>
+			expect(
+				screen.queryByRole( 'dialog', { name: 'Add widget' } )
+			).not.toBeInTheDocument()
+		);
+
+		await user.click( screen.getByRole( 'button', { name: 'Done' } ) );
+
+		expect( onLayoutChange ).toHaveBeenCalledTimes( 1 );
+		const [ updated ] = onLayoutChange.mock.calls[ 0 ];
+		expect( updated ).toHaveLength( 1 );
+		expect( updated[ 0 ] ).toMatchObject( {
+			type: 'wordpress/welcome',
+			attributes: { label: 'welcome-example' },
+		} );
+		expect( updated[ 0 ].uuid ).toEqual( expect.any( String ) );
+	} );
+
+	it( 'inserts multiple widgets via multi-select in a single layout change', async () => {
+		const user = userEvent.setup();
+		const onLayoutChange = jest.fn();
+		render( <Harness onLayoutChange={ onLayoutChange } /> );
+
+		await user.click(
+			screen.getByRole( 'button', { name: 'Add widget' } )
+		);
+
+		const dialog = await screen.findByRole( 'dialog', {
+			name: 'Add widget',
+		} );
+		const options = within( dialog ).getAllByRole( 'option' );
+
+		await user.click( options[ 0 ] );
+		await user.click( options[ 1 ] );
+
+		await user.click(
+			within( dialog ).getByRole( 'button', { name: 'Select' } )
+		);
+
+		await user.click( screen.getByRole( 'button', { name: 'Done' } ) );
+
+		expect( onLayoutChange ).toHaveBeenCalledTimes( 1 );
+		const [ updated ] = onLayoutChange.mock.calls[ 0 ];
+		expect( updated ).toHaveLength( 2 );
+		expect( updated.map( ( w: DashboardWidget ) => w.type ) ).toEqual( [
+			'wordpress/welcome',
+			'wordpress/notes',
+		] );
+	} );
+
+	it( 'preserves existing widgets when appending new ones', async () => {
+		const user = userEvent.setup();
+		const onLayoutChange = jest.fn();
+		const existing: DashboardWidget = {
+			uuid: 'existing-1',
+			type: 'wordpress/welcome',
+			attributes: { label: 'kept' },
+			placement: { width: 1, height: 1 },
+		};
+
+		render(
+			<Harness
+				initialLayout={ [ existing ] }
+				onLayoutChange={ onLayoutChange }
+			/>
+		);
+
+		await user.click(
+			screen.getByRole( 'button', { name: 'Add widget' } )
+		);
+
+		const dialog = await screen.findByRole( 'dialog', {
+			name: 'Add widget',
+		} );
+		await user.click( within( dialog ).getAllByRole( 'option' )[ 1 ] );
+		await user.click(
+			within( dialog ).getByRole( 'button', { name: 'Select' } )
+		);
+
+		await user.click( screen.getByRole( 'button', { name: 'Done' } ) );
+
+		const [ updated ] = onLayoutChange.mock.calls[ 0 ];
+		expect( updated ).toHaveLength( 2 );
+		expect( updated[ 0 ] ).toEqual( existing );
+		expect( updated[ 1 ] ).toMatchObject( { type: 'wordpress/notes' } );
+	} );
+} );

package/src/test/widget-settings.test.tsx

@@ -0,0 +1,199 @@
+/**
+ * External dependencies
+ */
+import '@testing-library/jest-dom';
+import { render, screen, waitFor, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import type { ComponentType } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+import type {
+	ResolveWidgetModule,
+	WidgetRenderProps,
+	WidgetType,
+} from '@wordpress/widget-primitives';
+
+/**
+ * Internal dependencies
+ */
+import { WidgetDashboard } from '../widget-dashboard';
+import type { DashboardWidget } from '../types';
+
+type Attrs = { greeting: string };
+
+function TestWidget( {
+	attributes,
+}: WidgetRenderProps< { greeting?: string } > ) {
+	return <p data-testid="greeting">{ attributes?.greeting ?? '' }</p>;
+}
+
+const widgetTypes: WidgetType[] = [
+	{
+		apiVersion: 1,
+		name: 'test/greet',
+		title: 'Greet',
+		renderModule: 'greet-module',
+		attributes: [ { id: 'greeting', label: 'Greeting', type: 'text' } ],
+		example: { attributes: { greeting: 'hi' } },
+	},
+];
+
+const resolveWidgetModule: ResolveWidgetModule = async () => ( {
+	default: TestWidget as ComponentType< WidgetRenderProps< unknown > >,
+} );
+
+const initialLayout: DashboardWidget< Attrs >[] = [
+	{
+		uuid: 'w1',
+		type: 'test/greet',
+		attributes: { greeting: 'hello' },
+		placement: { width: 2, height: 2 },
+	},
+];
+
+function Harness( {
+	onLayoutChange,
+}: {
+	onLayoutChange?: ( layout: DashboardWidget[] ) => void;
+} ) {
+	const [ layout, setLayout ] =
+		useState< DashboardWidget[] >( initialLayout );
+	const [ editMode, setEditMode ] = useState( false );
+
+	return (
+		<WidgetDashboard
+			layout={ layout }
+			onLayoutChange={ ( next ) => {
+				setLayout( next );
+				onLayoutChange?.( next );
+			} }
+			widgetTypes={ widgetTypes }
+			editMode={ editMode }
+			onEditChange={ setEditMode }
+			resolveWidgetModule={ resolveWidgetModule }
+		/>
+	);
+}
+
+describe( 'WidgetDashboard widget settings', () => {
+	it( 'surfaces a per-instance settings gear in normal mode', async () => {
+		render( <Harness /> );
+
+		expect( await screen.findByTestId( 'greeting' ) ).toBeInTheDocument();
+		expect(
+			screen.getByRole( 'button', { name: 'Widget settings' } )
+		).toBeInTheDocument();
+	} );
+
+	it( 'hides the gear while the layout is being edited', async () => {
+		const user = userEvent.setup();
+		render( <Harness /> );
+		await screen.findByTestId( 'greeting' );
+
+		await user.click( screen.getByRole( 'button', { name: 'Customize' } ) );
+
+		expect(
+			screen.queryByRole( 'button', { name: 'Widget settings' } )
+		).not.toBeInTheDocument();
+	} );
+
+	it( 'stages attribute edits behind the drawer and publishes them on Save', async () => {
+		const user = userEvent.setup();
+		const onLayoutChange = jest.fn();
+		render( <Harness onLayoutChange={ onLayoutChange } /> );
+		await screen.findByTestId( 'greeting' );
+
+		await user.click(
+			screen.getByRole( 'button', { name: 'Widget settings' } )
+		);
+
+		const dialog = await screen.findByRole( 'dialog', {
+			name: 'Greet settings',
+		} );
+
+		const input = within( dialog ).getByRole( 'textbox' );
+		await user.clear( input );
+		await user.type( input, 'updated' );
+
+		// The live preview behind the drawer reflects the staged edit…
+		expect( screen.getByTestId( 'greeting' ) ).toHaveTextContent(
+			'updated'
+		);
+		// …but nothing is published until Save.
+		expect( onLayoutChange ).not.toHaveBeenCalled();
+
+		await user.click(
+			within( dialog ).getByRole( 'button', { name: 'Save' } )
+		);
+
+		expect( onLayoutChange ).toHaveBeenCalledTimes( 1 );
+		const [ updated ] = onLayoutChange.mock.calls[ 0 ];
+		expect( updated[ 0 ] ).toMatchObject( {
+			uuid: 'w1',
+			type: 'test/greet',
+			attributes: { greeting: 'updated' },
+		} );
+
+		await waitFor( () =>
+			expect(
+				screen.queryByRole( 'dialog', { name: 'Greet settings' } )
+			).not.toBeInTheDocument()
+		);
+	} );
+
+	it( 'discards staged edits when the drawer is dismissed', async () => {
+		const user = userEvent.setup();
+		const onLayoutChange = jest.fn();
+		render( <Harness onLayoutChange={ onLayoutChange } /> );
+		await screen.findByTestId( 'greeting' );
+
+		await user.click(
+			screen.getByRole( 'button', { name: 'Widget settings' } )
+		);
+		const dialog = await screen.findByRole( 'dialog', {
+			name: 'Greet settings',
+		} );
+		const input = within( dialog ).getByRole( 'textbox' );
+		await user.clear( input );
+		await user.type( input, 'updated' );
+
+		await user.click(
+			within( dialog ).getByRole( 'button', { name: 'Cancel' } )
+		);
+
+		expect( onLayoutChange ).not.toHaveBeenCalled();
+		expect( screen.getByTestId( 'greeting' ) ).toHaveTextContent( 'hello' );
+	} );
+
+	it( 'shows no gear for a type that declares no attributes', async () => {
+		render(
+			<WidgetDashboard
+				layout={ [
+					{
+						uuid: 'w1',
+						type: 'test/plain',
+						placement: { width: 1, height: 1 },
+					},
+				] }
+				onLayoutChange={ () => {} }
+				widgetTypes={ [
+					{
+						apiVersion: 1,
+						name: 'test/plain',
+						title: 'Plain',
+						renderModule: 'greet-module',
+					},
+				] }
+				resolveWidgetModule={ resolveWidgetModule }
+			/>
+		);
+		await screen.findByTestId( 'greeting' );
+
+		expect(
+			screen.queryByRole( 'button', { name: /settings/i } )
+		).not.toBeInTheDocument();
+	} );
+} );

package/src/types.ts

@@ -0,0 +1,260 @@
+/**
+ * Dashboard-specific types: `DashboardWidget`, grid settings, and the
+ * `WidgetDashboard` prop bag.
+ *
+ * The widget contract types (`WidgetName`, `WidgetType`, `WidgetRenderProps`,
+ * `ResolveWidgetModule`) live in `@wordpress/widget-primitives` and are
+ * imported from there directly; this module does not re-export them.
+ */
+
+/**
+ * External dependencies
+ */
+import type { ReactNode } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import type {
+	DashboardGridLayoutItem,
+	DashboardLanesLayoutItem,
+} from '@wordpress/grid';
+import type {
+	WidgetName,
+	WidgetType,
+	ResolveWidgetModule,
+} from '@wordpress/widget-primitives';
+
+export type GridTilePlacement = Omit< DashboardGridLayoutItem, 'key' >;
+export type MasonryTilePlacement = Omit< DashboardLanesLayoutItem, 'key' >;
+
+/**
+ * Storage shape for a widget's placement.
+ *
+ * Structurally a union of every supported per-model shape, but the
+ * intended invariant is stronger than the type suggests: every
+ * placement in a given layout must match the shape of the currently
+ * active `gridSettings.model`. `migrateLayout` is the only correct
+ * way to transition placements across model changes; the render
+ * layer is allowed to trust the active model and treat each
+ * placement as the matching shape.
+ *
+ * The type system cannot enforce that invariant on its own (there is
+ * no discriminator on the placement itself), so consider this union a
+ * declaration of which shapes are *valid*, not which shape any given
+ * placement happens to be at runtime.
+ */
+export type DashboardTilePlacement = GridTilePlacement | MasonryTilePlacement;
+
+/**
+ * A widget placed on the dashboard.
+ *
+ * A `WidgetType` describes the blueprint. A `DashboardWidget` is a
+ * concrete placement of that type on a specific dashboard: its unique
+ * id, the type it references, user-configured attributes, and its
+ * `placement` in the grid.
+ */
+export interface DashboardWidget< Item = unknown > {
+	/**
+	 * Unique instance identifier.
+	 */
+	uuid: string;
+
+	/**
+	 * Widget type name — must match a `WidgetType.name` in `widgetTypes`.
+	 */
+	type: WidgetName;
+
+	/**
+	 * User-configured attributes for this instance.
+	 */
+	attributes?: Item;
+
+	/**
+	 * Grid-model-specific placement (column/row spans, ordering,
+	 * etc.). Must match the shape implied by the dashboard's active
+	 * `gridSettings.model`; see `DashboardTilePlacement` for the
+	 * invariant and `migrateLayout` for the transition mechanism.
+	 */
+	placement?: DashboardTilePlacement;
+}
+
+/**
+ * Identity of a widget within the rendering tree. Returned by
+ * `useWidgetContext()`; `null` when called outside a widget render subtree.
+ */
+export interface WidgetContextValue {
+	/**
+	 * Widget instance id.
+	 */
+	uuid: string;
+
+	/**
+	 * Widget type name.
+	 */
+	name: WidgetName;
+
+	/**
+	 * Index of the widget in the `layout` array.
+	 */
+	index: number;
+}
+
+/**
+ * Identifier for the active grid model. Drives which `@wordpress/grid`
+ * surface the dashboard mounts and which per-model settings the
+ * `WidgetGridSettings` union admits.
+ *
+ * Model names describe user-facing concepts. The mapping to the
+ * underlying `@wordpress/grid` component is an implementation detail
+ * resolved in the render layer; `'masonry'` is rendered today through
+ * `DashboardLanes` (skyline placement) but could swap to a future
+ * native `display: grid-lanes` path without affecting the model name.
+ */
+export type WidgetGridModel = 'grid' | 'masonry';
+
+/**
+ * Maximum column count for the widget dashboard on wide containers.
+ * Not exposed in layout settings; container width steps the count down
+ * to two and one column at fixed breakpoints.
+ */
+export const WIDGET_DASHBOARD_COLUMN_COUNT = 4;
+
+/**
+ * Settings common to every grid model. Column count is resolved from
+ * the dashboard container width (see
+ * `utils/resolve-dashboard-column-count`). `columns` and `minColumnWidth`
+ * on this type remain for persisted payloads and `@wordpress/grid`
+ * compatibility; the dashboard ignores user-facing values for both.
+ *
+ * `spacing` is intentionally absent: the gap between tiles is
+ * presentational and lives with the design-system theme/density, not
+ * with per-dashboard settings. The grid surface keeps the prop for
+ * programmatic overrides, but the dashboard does not propagate it.
+ */
+interface BaseWidgetGridSettings {
+	/**
+	 * Target column count (cap). The dashboard always uses
+	 * {@link WIDGET_DASHBOARD_COLUMN_COUNT}; persisted values are ignored.
+	 */
+	columns?: number;
+
+	/**
+	 * Per-tile minimum width in pixels. Unused by the dashboard; column
+	 * count is derived from container width instead.
+	 */
+	minColumnWidth?: number;
+}
+
+/**
+ * 2D packed grid settings. Items declare explicit width and height
+ * spans; rows use a uniform track height via `rowHeight`.
+ */
+export interface WidgetGridLayoutSettings extends BaseWidgetGridSettings {
+	model?: 'grid';
+
+	/**
+	 * Row height in pixels (`200` small, `300` medium, `400` large). Every
+	 * tile in a row fills the row vertically.
+	 */
+	rowHeight?: number;
+}
+
+/**
+ * Masonry settings. Heights are content-driven; resize is
+ * horizontal-only. `flowTolerance` tunes how aggressively the placer
+ * preserves source order vs. minimizing empty regions.
+ */
+export interface WidgetMasonryLayoutSettings extends BaseWidgetGridSettings {
+	model: 'masonry';
+
+	/**
+	 * Pixel tolerance for source-order tiebreaking when two candidate
+	 * columns have similar baselines.
+	 */
+	flowTolerance?: number;
+}
+
+/**
+ * Discriminated union of supported grid-model configurations.
+ *
+ * When `model` is omitted the dashboard treats the settings as the
+ * 2D packed grid (`'grid'`) for backwards compatibility with the
+ * pre-union shape.
+ */
+export type WidgetGridSettings =
+	| WidgetGridLayoutSettings
+	| WidgetMasonryLayoutSettings;
+
+/**
+ * Props for `WidgetDashboard`.
+ *
+ * The consumer owns the committed layout state; the dashboard maintains
+ * a staging copy internally for in-progress edits, and `onLayoutChange`
+ * fires only when the user commits via the Done action.
+ */
+export interface WidgetDashboardProps {
+	/**
+	 * Widget instances to render. Consumer owns this state.
+	 */
+	layout: DashboardWidget[];
+
+	/**
+	 * Called when the user commits in-progress edits via the Done action.
+	 * Receives the full layout array as it should be persisted. In-progress
+	 * mutations (reorder, resize, add, remove, attribute edits) accumulate
+	 * in the dashboard's internal staging layer and do not fire this
+	 * callback until commit.
+	 */
+	onLayoutChange: ( layout: DashboardWidget[] ) => void;
+
+	/**
+	 * Called when the layout is reset to the default.
+	 */
+	onLayoutReset?: () => void;
+
+	/**
+	 * Widget types available for rendering. The dashboard never queries a
+	 * store directly — consumers scope and filter via this prop.
+	 */
+	widgetTypes: WidgetType[];
+
+	/**
+	 * When true, widget types are still loading. Instances whose type is
+	 * not yet in `widgetTypes` show a loading state instead of missing.
+	 */
+	isResolvingWidgetTypes?: boolean;
+
+	/**
+	 * Whether the dashboard is in edit mode (enables drag/resize).
+	 */
+	editMode?: boolean;
+
+	/**
+	 * Called when edit mode toggles via `WidgetDashboard.Actions`.
+	 */
+	onEditChange?: ( next: boolean ) => void;
+
+	/**
+	 * Overrides the default `import()` resolution of
+	 * `WidgetType.renderModule`. Useful for tests, Storybook, or future
+	 * remote-URL loading.
+	 */
+	resolveWidgetModule?: ResolveWidgetModule;
+
+	/**
+	 * Grid model configuration. See `WidgetGridSettings` for the shape.
+	 */
+	gridSettings?: WidgetGridSettings;
+
+	/**
+	 * Called when the user commits in-progress grid-settings edits via
+	 * the Done action. The dashboard maintains a staging copy of
+	 * settings internally; mutations stay local until commit. When
+	 * omitted, the `Layout settings` button in the customize toolbar is
+	 * hidden, since there is nowhere to persist the change.
+	 */
+	onGridSettingsChange?: ( gridSettings: WidgetGridSettings ) => void;
+
+	children?: ReactNode;
+}

package/src/utils/create-dashboard-widget/create-dashboard-widget.ts

@@ -0,0 +1,43 @@
+/**
+ * External dependencies
+ */
+import { v4 as uuid } from 'uuid';
+
+/**
+ * WordPress dependencies
+ */
+import type { WidgetType } from '@wordpress/widget-primitives';
+
+/**
+ * Internal dependencies
+ */
+import type { DashboardWidget, GridTilePlacement } from '../../types';
+
+const DEFAULT_PLACEMENT: GridTilePlacement = {
+	width: 1,
+	height: 2,
+	order: 0,
+};
+
+/**
+ * Create a new dashboard widget from a widget type.
+ *
+ * Generates a unique id and applies default placement. If no initial
+ * attributes are provided, falls back to the type's `example.attributes`
+ * (matching the `widget.json` schema).
+ *
+ * @param widgetType        Source widget type.
+ * @param initialAttributes Initial attributes; default to the type's example.
+ */
+export function createDashboardWidget< T >(
+	widgetType: WidgetType,
+	initialAttributes?: T
+): DashboardWidget< T > {
+	return {
+		uuid: uuid(),
+		type: widgetType.name,
+		attributes:
+			initialAttributes ?? ( widgetType.example?.attributes as T ),
+		placement: DEFAULT_PLACEMENT,
+	};
+}

package/src/utils/create-dashboard-widget/index.ts

@@ -0,0 +1 @@
+export { createDashboardWidget } from './create-dashboard-widget';