@wordpress/widget-dashboard 0.1.0

package/src/utils/default-grid/default-grid.ts

@@ -0,0 +1,17 @@
+/**
+ * Internal dependencies
+ */
+import type { WidgetGridSettings } from '../../types';
+import { WIDGET_DASHBOARD_COLUMN_COUNT } from '../../types';
+import { DEFAULT_ROW_HEIGHT } from '../row-height-presets';
+
+/**
+ * Canonical default grid settings. Applied by the dashboard when the
+ * consumer omits `gridSettings`, and the baseline hosts should treat as
+ * the factory default when persisting their own copy.
+ */
+export const DEFAULT_GRID: WidgetGridSettings = {
+	model: 'grid',
+	columns: WIDGET_DASHBOARD_COLUMN_COUNT,
+	rowHeight: DEFAULT_ROW_HEIGHT,
+};

package/src/utils/default-grid/index.ts

@@ -0,0 +1 @@
+export { DEFAULT_GRID } from './default-grid';

package/src/utils/grid-model-change/grid-model-change.ts

@@ -0,0 +1,53 @@
+/**
+ * Internal dependencies
+ */
+import { migrateLayout } from '../migrate-layout';
+import type {
+	DashboardWidget,
+	WidgetGridModel,
+	WidgetGridSettings,
+} from '../../types';
+import { WIDGET_DASHBOARD_COLUMN_COUNT } from '../../types';
+
+export function getGridModel( settings: WidgetGridSettings ): WidgetGridModel {
+	return settings.model ?? 'grid';
+}
+
+type ComputeGridModelChangeProps = {
+	layout: DashboardWidget[];
+	gridSettings: WidgetGridSettings;
+	targetModel: WidgetGridModel;
+};
+
+type ComputeGridModelChangeResult = {
+	layout: DashboardWidget[];
+	gridSettings: WidgetGridSettings;
+} | null;
+
+/**
+ * Computes the staged layout and grid settings after a layout-model change.
+ *
+ * @param {ComputeGridModelChangeProps} params Layout, current settings, and target model.
+ * @return {ComputeGridModelChangeResult} Migrated layout and settings, or `null` when the model is unchanged.
+ */
+export function computeGridModelChange( {
+	layout,
+	gridSettings,
+	targetModel,
+}: ComputeGridModelChangeProps ): ComputeGridModelChangeResult {
+	const currentModel = getGridModel( gridSettings );
+
+	if ( currentModel === targetModel ) {
+		return null;
+	}
+
+	return {
+		layout: migrateLayout( layout, currentModel, targetModel, {
+			columns: WIDGET_DASHBOARD_COLUMN_COUNT,
+		} ),
+		gridSettings: {
+			...gridSettings,
+			model: targetModel,
+		} as WidgetGridSettings,
+	};
+}

package/src/utils/grid-model-change/index.ts

@@ -0,0 +1 @@
+export { computeGridModelChange, getGridModel } from './grid-model-change';

package/src/utils/index.ts

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

package/src/utils/migrate-layout/index.ts

@@ -0,0 +1 @@
+export { migrateLayout } from './migrate-layout';

package/src/utils/migrate-layout/migrate-layout.ts

@@ -0,0 +1,156 @@
+/**
+ * Internal dependencies
+ */
+import type {
+	DashboardWidget,
+	GridTilePlacement,
+	MasonryTilePlacement,
+	WidgetGridModel,
+} from '../../types';
+
+interface MigrationContext {
+	/**
+	 * Column count of the currently-mounted grid surface. Used to
+	 * resolve `'full'` widths to a concrete numeric span when going
+	 * from the 2D grid model to masonry. When the surface is in
+	 * responsive mode and the runtime column count is unknown,
+	 * callers should pass a sensible fallback (e.g., the default of
+	 * 6 used by `@wordpress/grid`).
+	 */
+	columns: number;
+}
+
+const FALLBACK_COLUMNS = 6;
+
+/**
+ * Coerces a `'fill'`/`'full'`/numeric width into a concrete numeric
+ * span when migrating from `'grid'` to `'masonry'`. `'fill'` collapses
+ * to a single column; resolving it against per-row remainder would
+ * require either DOM measurement or replicating CSS-Grid's auto-flow
+ * placement, both of which were judged not worth the complexity for
+ * a one-shot migration the user can correct visually in staging.
+ *
+ * @param width         Source width from a grid placement.
+ * @param targetColumns Column count to use for `'full'` widths.
+ */
+function gridWidthToMasonryWidth(
+	width: GridTilePlacement[ 'width' ],
+	targetColumns: number
+): number {
+	if ( width === 'full' ) {
+		return targetColumns;
+	}
+	if ( width === 'fill' || width === undefined ) {
+		return 1;
+	}
+	return width;
+}
+
+/**
+ * Transforms a single placement from the 2D grid shape to the masonry
+ * shape. Drops `height` (masonry derives heights from content),
+ * preserves `order`, leaves `lane` unset so the auto-flow placer
+ * arranges items by source order.
+ *
+ * @param placement Source grid placement.
+ * @param context   Migration context (column count).
+ */
+function migratePlacementGridToMasonry(
+	placement: GridTilePlacement | undefined,
+	context: MigrationContext
+): MasonryTilePlacement {
+	if ( ! placement ) {
+		return {};
+	}
+
+	const next: MasonryTilePlacement = {};
+	const width = gridWidthToMasonryWidth( placement.width, context.columns );
+	if ( width !== 1 ) {
+		next.width = width;
+	}
+	if ( placement.order !== undefined ) {
+		next.order = placement.order;
+	}
+	return next;
+}
+
+/**
+ * Transforms a single placement from the masonry shape to the 2D grid
+ * shape. Preserves the numeric width, drops `lane` (the 2D grid
+ * auto-packs and has no pin-to-column concept), and seeds `height: 1`
+ * since masonry never persisted a height. The user is expected to
+ * resize tiles vertically after the migration.
+ *
+ * @param placement Source masonry placement.
+ */
+function migratePlacementMasonryToGrid(
+	placement: MasonryTilePlacement | undefined
+): GridTilePlacement {
+	if ( ! placement ) {
+		return { height: 1 };
+	}
+
+	const next: GridTilePlacement = { height: 1 };
+	if ( placement.width !== undefined ) {
+		next.width = placement.width;
+	}
+	if ( placement.order !== undefined ) {
+		next.order = placement.order;
+	}
+	return next;
+}
+
+/**
+ * Migrates every widget's `placement` between grid models.
+ *
+ * The two storage shapes overlap on `width` and `order` but diverge
+ * on the rest: 2D grid carries `height` and discriminated string
+ * widths (`'fill'`/`'full'`), lanes carries `lane` and only numeric
+ * widths. Each conversion loses information that the target model
+ * cannot represent. The caller is responsible for surfacing the
+ * result to the user in a way that lets them correct visually.
+ *
+ * When `from === to`, the input is returned unchanged.
+ *
+ * @param widgets Widgets to migrate.
+ * @param from    Source model. `undefined` is treated as `'grid'`.
+ * @param to      Target model.
+ * @param context Information that depends on the live render (today
+ *                only `columns`).
+ */
+export function migrateLayout(
+	widgets: DashboardWidget[],
+	from: WidgetGridModel | undefined,
+	to: WidgetGridModel,
+	context: Partial< MigrationContext > = {}
+): DashboardWidget[] {
+	const resolvedFrom: WidgetGridModel = from ?? 'grid';
+	if ( resolvedFrom === to ) {
+		return widgets;
+	}
+
+	const resolvedContext: MigrationContext = {
+		columns: context.columns ?? FALLBACK_COLUMNS,
+	};
+
+	if ( resolvedFrom === 'grid' && to === 'masonry' ) {
+		return widgets.map( ( widget ) => ( {
+			...widget,
+			placement: migratePlacementGridToMasonry(
+				widget.placement as GridTilePlacement | undefined,
+				resolvedContext
+			),
+		} ) );
+	}
+
+	if ( resolvedFrom === 'masonry' && to === 'grid' ) {
+		return widgets.map( ( widget ) => ( {
+			...widget,
+			placement: migratePlacementMasonryToGrid(
+				widget.placement as MasonryTilePlacement | undefined
+			),
+		} ) );
+	}
+
+	return widgets;
+}

package/src/utils/migrate-layout/test/migrate-layout.test.ts

@@ -0,0 +1,114 @@
+/**
+ * Internal dependencies
+ */
+import { migrateLayout } from '../migrate-layout';
+import type { DashboardWidget } from '../../../types';
+
+function widget( uuid: string, placement: object | undefined = undefined ) {
+	return {
+		uuid,
+		type: 'core/test' as const,
+		placement,
+	} as DashboardWidget;
+}
+
+describe( 'migrateLayout', () => {
+	it( 'returns input unchanged when source and target match', () => {
+		const layout: DashboardWidget[] = [
+			widget( 'a', { width: 2, height: 1 } ),
+		];
+		expect( migrateLayout( layout, 'grid', 'grid' ) ).toBe( layout );
+	} );
+
+	it( 'treats undefined source as grid', () => {
+		const layout: DashboardWidget[] = [
+			widget( 'a', { width: 'full', height: 1 } ),
+		];
+		const migrated = migrateLayout( layout, undefined, 'masonry', {
+			columns: 4,
+		} );
+		expect( migrated[ 0 ].placement ).toEqual( { width: 4 } );
+	} );
+
+	describe( 'grid to masonry', () => {
+		it( "expands 'full' to the target column count", () => {
+			const layout: DashboardWidget[] = [
+				widget( 'a', { width: 'full', height: 1 } ),
+			];
+			const migrated = migrateLayout( layout, 'grid', 'masonry', {
+				columns: 6,
+			} );
+			expect( migrated[ 0 ].placement ).toEqual( { width: 6 } );
+		} );
+
+		it( "collapses 'fill' to a single column", () => {
+			const layout: DashboardWidget[] = [
+				widget( 'a', { width: 'fill', height: 2 } ),
+			];
+			const migrated = migrateLayout( layout, 'grid', 'masonry', {
+				columns: 6,
+			} );
+			expect( migrated[ 0 ].placement ).toEqual( {} );
+		} );
+
+		it( 'preserves numeric width and drops height and explicit width=1', () => {
+			const layout: DashboardWidget[] = [
+				widget( 'a', { width: 3, height: 2, order: 5 } ),
+				widget( 'b', { width: 1, height: 1 } ),
+			];
+			const migrated = migrateLayout( layout, 'grid', 'masonry', {
+				columns: 6,
+			} );
+			expect( migrated[ 0 ].placement ).toEqual( {
+				width: 3,
+				order: 5,
+			} );
+			expect( migrated[ 1 ].placement ).toEqual( {} );
+		} );
+
+		it( 'falls back to a default column count when not provided', () => {
+			const layout: DashboardWidget[] = [
+				widget( 'a', { width: 'full', height: 1 } ),
+			];
+			const migrated = migrateLayout( layout, 'grid', 'masonry' );
+			expect( migrated[ 0 ].placement ).toEqual( { width: 6 } );
+		} );
+
+		it( 'handles widgets without a placement', () => {
+			const layout: DashboardWidget[] = [ widget( 'a' ) ];
+			const migrated = migrateLayout( layout, 'grid', 'masonry' );
+			expect( migrated[ 0 ].placement ).toEqual( {} );
+		} );
+	} );
+
+	describe( 'masonry to grid', () => {
+		it( 'seeds height=1 and preserves width and order', () => {
+			const layout: DashboardWidget[] = [
+				widget( 'a', { width: 2, order: 1 } ),
+			];
+			const migrated = migrateLayout( layout, 'masonry', 'grid' );
+			expect( migrated[ 0 ].placement ).toEqual( {
+				width: 2,
+				height: 1,
+				order: 1,
+			} );
+		} );
+
+		it( 'drops the lane field', () => {
+			const layout: DashboardWidget[] = [
+				widget( 'a', { width: 1, lane: 2 } ),
+			];
+			const migrated = migrateLayout( layout, 'masonry', 'grid' );
+			expect( migrated[ 0 ].placement ).toEqual( {
+				width: 1,
+				height: 1,
+			} );
+		} );
+
+		it( 'handles widgets without a placement', () => {
+			const layout: DashboardWidget[] = [ widget( 'a' ) ];
+			const migrated = migrateLayout( layout, 'masonry', 'grid' );
+			expect( migrated[ 0 ].placement ).toEqual( { height: 1 } );
+		} );
+	} );
+} );

package/src/utils/normalize-grid-settings/index.ts

@@ -0,0 +1 @@
+export { normalizeGridSettings } from './normalize-grid-settings';

package/src/utils/normalize-grid-settings/normalize-grid-settings.ts

@@ -0,0 +1,38 @@
+import type { WidgetGridLayoutSettings, WidgetGridSettings } from '../../types';
+import { snapRowHeight } from '../row-height-presets';
+
+/**
+ * Coerces legacy grid row heights to a dashboard preset. Standard grid
+ * rows always use uniform track sizing so tiles align with the masonry
+ * model boundary.
+ *
+ * @param settings         Grid settings to normalize.
+ * @param defaultRowHeight Fallback row height when none is set.
+ */
+export function normalizeGridSettings(
+	settings: WidgetGridSettings,
+	defaultRowHeight: number
+): WidgetGridSettings {
+	if ( ( settings.model ?? 'grid' ) === 'masonry' ) {
+		return settings;
+	}
+
+	// The guard above cannot narrow the union for TypeScript: `model` is
+	// optional and the check goes through `??`.
+	const gridSettings = settings as WidgetGridLayoutSettings;
+
+	const rowHeight = gridSettings.rowHeight;
+	const resolved =
+		typeof rowHeight === 'number'
+			? snapRowHeight( rowHeight )
+			: defaultRowHeight;
+
+	if ( rowHeight === resolved ) {
+		return settings;
+	}
+
+	return {
+		...gridSettings,
+		rowHeight: resolved,
+	};
+}

package/src/utils/resolve-dashboard-column-count/resolve-dashboard-column-count.ts

@@ -0,0 +1,41 @@
+/**
+ * Internal dependencies
+ */
+import { WIDGET_DASHBOARD_COLUMN_COUNT } from '../../types';
+
+/**
+ * Container width (px) below which the dashboard uses a single column.
+ * Matches `@container widget-dashboard (max-width: …)` in widgets CSS.
+ */
+export const WIDGET_DASHBOARD_CONTAINER_BREAKPOINT_ONE_COLUMN = 600;
+
+/**
+ * Container width (px) below which the dashboard drops from four columns
+ * to two. Above this threshold (and below the four-column cap) the
+ * grid uses {@link WIDGET_DASHBOARD_COLUMN_COUNT}.
+ */
+export const WIDGET_DASHBOARD_CONTAINER_BREAKPOINT_TWO_COLUMNS = 960;
+
+/**
+ * Resolves the dashboard grid column count from the widget surface
+ * container width. Uses discrete steps (4 → 2 → 1), not viewport
+ * media queries.
+ *
+ * @param containerWidth Measured inline size of the dashboard grid container.
+ * @return Column count for {@link @wordpress/grid} surfaces.
+ */
+export function resolveDashboardColumnCount( containerWidth: number ): number {
+	if ( containerWidth <= 0 ) {
+		return WIDGET_DASHBOARD_COLUMN_COUNT;
+	}
+
+	if ( containerWidth < WIDGET_DASHBOARD_CONTAINER_BREAKPOINT_ONE_COLUMN ) {
+		return 1;
+	}
+
+	if ( containerWidth < WIDGET_DASHBOARD_CONTAINER_BREAKPOINT_TWO_COLUMNS ) {
+		return 2;
+	}
+
+	return WIDGET_DASHBOARD_COLUMN_COUNT;
+}

package/src/utils/resolve-dashboard-column-count/test/resolve-dashboard-column-count.test.ts

@@ -0,0 +1,44 @@
+/**
+ * Internal dependencies
+ */
+import {
+	resolveDashboardColumnCount,
+	WIDGET_DASHBOARD_CONTAINER_BREAKPOINT_ONE_COLUMN,
+	WIDGET_DASHBOARD_CONTAINER_BREAKPOINT_TWO_COLUMNS,
+} from '../resolve-dashboard-column-count';
+
+describe( 'resolveDashboardColumnCount', () => {
+	it( 'defaults to four columns before measurement', () => {
+		expect( resolveDashboardColumnCount( 0 ) ).toBe( 4 );
+	} );
+
+	it( 'uses four columns at wide container sizes', () => {
+		expect(
+			resolveDashboardColumnCount(
+				WIDGET_DASHBOARD_CONTAINER_BREAKPOINT_TWO_COLUMNS
+			)
+		).toBe( 4 );
+		expect( resolveDashboardColumnCount( 1200 ) ).toBe( 4 );
+	} );
+
+	it( 'uses two columns between mobile and wide breakpoints', () => {
+		expect(
+			resolveDashboardColumnCount(
+				WIDGET_DASHBOARD_CONTAINER_BREAKPOINT_ONE_COLUMN
+			)
+		).toBe( 2 );
+		expect(
+			resolveDashboardColumnCount(
+				WIDGET_DASHBOARD_CONTAINER_BREAKPOINT_TWO_COLUMNS - 1
+			)
+		).toBe( 2 );
+	} );
+
+	it( 'uses one column below the mobile container breakpoint', () => {
+		expect(
+			resolveDashboardColumnCount(
+				WIDGET_DASHBOARD_CONTAINER_BREAKPOINT_ONE_COLUMN - 1
+			)
+		).toBe( 1 );
+	} );
+} );

package/src/utils/row-height-presets/index.ts

@@ -0,0 +1,8 @@
+export {
+	DEFAULT_ROW_HEIGHT,
+	ROW_HEIGHT_PRESETS,
+	presetToRowHeight,
+	rowHeightToPreset,
+	snapRowHeight,
+} from './row-height-presets';
+export type { RowHeightPreset } from './row-height-presets';

package/src/utils/row-height-presets/row-height-presets.ts

@@ -0,0 +1,43 @@
+export const ROW_HEIGHT_PRESETS = {
+	small: 200,
+	medium: 300,
+	large: 400,
+} as const;
+
+export type RowHeightPreset = keyof typeof ROW_HEIGHT_PRESETS;
+
+export const DEFAULT_ROW_HEIGHT = ROW_HEIGHT_PRESETS.medium;
+
+const PRESET_ENTRIES = Object.entries( ROW_HEIGHT_PRESETS ) as [
+	RowHeightPreset,
+	number,
+][];
+
+/**
+ * Maps a stored pixel height to the nearest preset so legacy freeform
+ * values still resolve to a valid toggle option.
+ *
+ * @param rowHeight Row height in pixels.
+ */
+export function rowHeightToPreset( rowHeight: number ): RowHeightPreset {
+	let closest: RowHeightPreset = 'medium';
+	let minDistance = Infinity;
+
+	for ( const [ preset, value ] of PRESET_ENTRIES ) {
+		const distance = Math.abs( rowHeight - value );
+		if ( distance < minDistance ) {
+			minDistance = distance;
+			closest = preset;
+		}
+	}
+
+	return closest;
+}
+
+export function presetToRowHeight( preset: RowHeightPreset ): number {
+	return ROW_HEIGHT_PRESETS[ preset ];
+}
+
+export function snapRowHeight( rowHeight: number ): number {
+	return presetToRowHeight( rowHeightToPreset( rowHeight ) );
+}

package/src/widget-dashboard.tsx

@@ -0,0 +1,102 @@
+/**
+ * Internal dependencies
+ */
+import { WidgetDashboardProvider } from './context/dashboard-context';
+import { WidgetDashboardUIProvider } from './context/ui-context';
+import { Actions } from './components/actions';
+import { Commands } from './components/commands';
+import { LayoutSettings } from './components/layout-settings';
+import { NoWidgetsState } from './components/no-widgets-state';
+import { ResetConfirmation } from './components/reset-confirmation';
+import { WidgetChrome } from './components/widget-chrome';
+import { WidgetInserter } from './components/widget-inserter';
+import { WidgetSettings } from './components/widget-settings';
+import { Widgets } from './components/widgets';
+import type { WidgetDashboardProps } from './types';
+
+/**
+ * Stateless rendering engine for widget dashboards.
+ *
+ * The consumer owns `layout` and `editMode` state; every mutation fires
+ * `onLayoutChange` with the fully updated array. The engine never queries a
+ * widget store; types flow in via the `widgetTypes` prop.
+ *
+ * ```tsx
+ * import { WidgetDashboard } from '@wordpress/widget-dashboard';
+ *
+ * function MyDashboard() {
+ * 	const [ layout, setLayout ] = useState( defaultLayout );
+ * 	const [ editMode, setEditMode ] = useState( false );
+ * 	return (
+ * 		<WidgetDashboard
+ * 			layout={ layout }
+ * 			onLayoutChange={ setLayout }
+ * 			widgetTypes={ widgetTypes }
+ * 			editMode={ editMode }
+ * 			onEditChange={ setEditMode }
+ * 		>
+ * 			<WidgetDashboard.NoWidgetsState>
+ * 				<p>No widgets yet.</p>
+ * 			</WidgetDashboard.NoWidgetsState>
+ * 			<WidgetDashboard.Actions />
+ * 			<WidgetDashboard.Widgets />
+ * 			<WidgetDashboard.Commands />
+ * 		</WidgetDashboard>
+ * 	);
+ * }
+ * ```
+ *
+ * Children compose the dashboard's triggers and chrome: `Actions`,
+ * `Widgets`, `Commands`, `NoWidgetsState`. The targets they open (the
+ * widget inserter, the layout and widget settings editors, the reset
+ * confirmation) are mounted by the engine and driven by shared UI state, so
+ * a trigger works wherever it is composed without a matching target in the
+ * tree. Omitting `children` renders the default arrangement.
+ */
+export const WidgetDashboard = Object.assign(
+	function WidgetDashboard( {
+		layout,
+		onLayoutChange,
+		onLayoutReset,
+		widgetTypes,
+		isResolvingWidgetTypes,
+		editMode,
+		onEditChange,
+		resolveWidgetModule,
+		gridSettings,
+		onGridSettingsChange,
+		children,
+	}: WidgetDashboardProps ) {
+		return (
+			<WidgetDashboardProvider
+				layout={ layout }
+				onLayoutChange={ onLayoutChange }
+				onLayoutReset={ onLayoutReset }
+				widgetTypes={ widgetTypes }
+				isResolvingWidgetTypes={ isResolvingWidgetTypes }
+				editMode={ editMode }
+				onEditChange={ onEditChange }
+				resolveWidgetModule={ resolveWidgetModule }
+				gridSettings={ gridSettings }
+				onGridSettingsChange={ onGridSettingsChange }
+			>
+				<WidgetDashboardUIProvider>
+					{ children ?? (
+						<>
+							<NoWidgetsState />
+							<Actions />
+							<Widgets />
+							<Commands />
+						</>
+					) }
+
+					<WidgetInserter />
+					<LayoutSettings />
+					<WidgetSettings />
+					<ResetConfirmation />
+				</WidgetDashboardUIProvider>
+			</WidgetDashboardProvider>
+		);
+	},
+	{ Actions, Widgets, WidgetChrome, NoWidgetsState, Commands }
+);

package/src/wordpress-commands.d.ts

@@ -0,0 +1,12 @@
+/*
+ * `@wordpress/commands` ships untyped JavaScript resolved through gitignored
+ * build artifacts; this ambient declaration covers the surface this package
+ * consumes so type builds don't depend on those artifacts existing.
+ */
+declare module '@wordpress/commands' {
+	import type { StoreDescriptor } from '@wordpress/data';
+
+	export function useCommands( commands: unknown[] ): void;
+	export const privateApis: Record< string, unknown >;
+	export const store: StoreDescriptor;
+}