@wordpress/widget-dashboard 0.1.0

package/src/components/commands/commands.tsx

@@ -0,0 +1,182 @@
+/**
+ * WordPress dependencies
+ */
+import { useCallback, useMemo } from '@wordpress/element';
+import { __ } from '@wordpress/i18n';
+import {
+	useCommands,
+	privateApis as commandsPrivateApis,
+} from '@wordpress/commands';
+import {
+	columns,
+	grid,
+	layout as layoutIcon,
+	plus,
+	trash,
+} from '@wordpress/icons';
+
+/**
+ * Internal dependencies
+ */
+import { unlock } from '../../lock-unlock';
+import { useDashboardInternalContext } from '../../context/dashboard-context';
+import { useDashboardUIContext } from '../../context/ui-context';
+import { getGridModel } from '../../utils/grid-model-change';
+import { usePendingWhenEditMode } from './use-pending-when-edit-mode';
+
+const { useCommandContext } = unlock( commandsPrivateApis );
+
+export const DASHBOARD_COMMAND_CONTEXT = 'dashboard';
+
+type CommandCallback = ( options: { close: () => void } ) => void;
+
+/**
+ * Registers dashboard-specific command palette commands and sets the
+ * active command context so they surface under Suggestions by default.
+ */
+export function Commands() {
+	const {
+		editMode,
+		onEditChange,
+		onLayoutReset,
+		gridSettings,
+		canEditGridSettings,
+		commitGridModelChange,
+	} = useDashboardInternalContext();
+
+	const { setInserterOpen, setResetDialogOpen } = useDashboardUIContext();
+
+	useCommandContext( DASHBOARD_COMMAND_CONTEXT );
+
+	const runWhenInEditMode = usePendingWhenEditMode( {
+		editMode,
+		onEditChange,
+	} );
+
+	const gridModel = getGridModel( gridSettings );
+	const isGridLayout = gridModel === 'grid';
+	const isMasonryLayout = gridModel === 'masonry';
+
+	const switchToMasonry = useCallback< CommandCallback >(
+		( { close } ) => {
+			close();
+			commitGridModelChange( 'masonry' );
+		},
+		[ commitGridModelChange ]
+	);
+
+	const switchToGrid = useCallback< CommandCallback >(
+		( { close } ) => {
+			close();
+			commitGridModelChange( 'grid' );
+		},
+		[ commitGridModelChange ]
+	);
+
+	const resetToDefault = useCallback< CommandCallback >(
+		( { close } ) => {
+			close();
+			setResetDialogOpen( true );
+		},
+		[ setResetDialogOpen ]
+	);
+
+	const addWidgets = useCallback< CommandCallback >(
+		( { close } ) => {
+			close();
+			runWhenInEditMode( () => {
+				setInserterOpen( true );
+			} );
+		},
+		[ runWhenInEditMode, setInserterOpen ]
+	);
+
+	const customize = useCallback< CommandCallback >(
+		( { close } ) => {
+			close();
+			onEditChange?.( true );
+		},
+		[ onEditChange ]
+	);
+
+	const commands = useMemo(
+		() => [
+			{
+				name: 'core/dashboard/customize',
+				label: __( 'Customize dashboard' ),
+				icon: layoutIcon,
+				category: 'command',
+				context: DASHBOARD_COMMAND_CONTEXT,
+				keywords: [ __( 'edit' ), __( 'widgets' ), __( 'layout' ) ],
+				disabled: ! onEditChange || editMode,
+				callback: customize,
+			},
+			{
+				name: 'core/dashboard/add-widgets',
+				label: __( 'Add dashboard widgets' ),
+				icon: plus,
+				category: 'command',
+				context: DASHBOARD_COMMAND_CONTEXT,
+				keywords: [ __( 'widgets' ), __( 'inserter' ) ],
+				disabled: ! onEditChange,
+				callback: addWidgets,
+			},
+			{
+				name: 'core/dashboard/switch-to-masonry-layout',
+				label: __( 'Switch dashboard to masonry layout' ),
+				icon: columns,
+				category: 'command',
+				context: DASHBOARD_COMMAND_CONTEXT,
+				keywords: [
+					__( 'layout' ),
+					__( 'layout model' ),
+					__( 'masonry' ),
+				],
+				disabled: ! canEditGridSettings || isMasonryLayout || editMode,
+				callback: switchToMasonry,
+			},
+			{
+				name: 'core/dashboard/switch-to-grid-layout',
+				label: __( 'Switch dashboard to grid layout' ),
+				icon: grid,
+				category: 'command',
+				context: DASHBOARD_COMMAND_CONTEXT,
+				keywords: [
+					__( 'layout' ),
+					__( 'layout model' ),
+					__( 'grid' ),
+					__( 'standard grid' ),
+				],
+				disabled: ! canEditGridSettings || isGridLayout || editMode,
+				callback: switchToGrid,
+			},
+			{
+				name: 'core/dashboard/reset-to-default',
+				label: __( 'Reset dashboard widgets to default' ),
+				icon: trash,
+				category: 'command',
+				context: DASHBOARD_COMMAND_CONTEXT,
+				keywords: [ __( 'reset' ), __( 'default' ) ],
+				disabled: ! onLayoutReset,
+				callback: resetToDefault,
+			},
+		],
+		[
+			onEditChange,
+			editMode,
+			customize,
+			addWidgets,
+			canEditGridSettings,
+			isMasonryLayout,
+			isGridLayout,
+			switchToMasonry,
+			switchToGrid,
+			onLayoutReset,
+			resetToDefault,
+		]
+	);
+
+	useCommands( commands );
+
+	return null;
+}

package/src/components/commands/index.ts

@@ -0,0 +1 @@
+export { Commands, DASHBOARD_COMMAND_CONTEXT } from './commands';

package/src/components/commands/use-pending-when-edit-mode.ts

@@ -0,0 +1,48 @@
+/**
+ * WordPress dependencies
+ */
+import { useCallback, useEffect, useRef } from '@wordpress/element';
+
+type UsePendingWhenEditModeProps = {
+	editMode: boolean;
+	onEditChange?: ( next: boolean ) => void;
+};
+
+type UsePendingWhenEditModeResult = ( action: () => void ) => void;
+
+/**
+ * Runs an action immediately when already in edit mode. Otherwise enables
+ * edit mode and runs the action after edit mode becomes active.
+ *
+ * @param {UsePendingWhenEditModeProps} params Current edit mode and the change handler.
+ * @return {UsePendingWhenEditModeResult} Runs an action, deferring it until edit mode is active.
+ */
+export function usePendingWhenEditMode( {
+	editMode,
+	onEditChange,
+}: UsePendingWhenEditModeProps ): UsePendingWhenEditModeResult {
+	const pendingRef = useRef< ( () => void ) | null >( null );
+	const wasEditingRef = useRef( editMode );
+
+	useEffect( () => {
+		if ( ! wasEditingRef.current && editMode && pendingRef.current ) {
+			const action = pendingRef.current;
+			pendingRef.current = null;
+			action();
+		}
+		wasEditingRef.current = editMode;
+	}, [ editMode ] );
+
+	return useCallback(
+		( action: () => void ) => {
+			if ( editMode ) {
+				action();
+				return;
+			}
+
+			pendingRef.current = action;
+			onEditChange?.( true );
+		},
+		[ editMode, onEditChange ]
+	);
+}

package/src/components/layout-settings/index.ts

@@ -0,0 +1 @@
+export { LayoutSettings } from './layout-settings';

package/src/components/layout-settings/layout-model-edit-field/index.tsx

@@ -0,0 +1,98 @@
+/**
+ * External dependencies
+ */
+import clsx from 'clsx';
+
+/**
+ * WordPress dependencies
+ */
+import type { DataFormControlProps } from '@wordpress/dataviews';
+import { useCallback } from '@wordpress/element';
+/* eslint-disable @wordpress/use-recommended-components */
+import { Button, Fieldset, Stack, Text } from '@wordpress/ui';
+/* eslint-enable @wordpress/use-recommended-components */
+
+/**
+ * Internal dependencies
+ */
+import type { WidgetGridSettings } from '../../../types';
+import { GridThumbnail } from './thumbnail-grid';
+import { MasonryThumbnail } from './thumbnail-masonry';
+import styles from './style.module.css';
+
+interface ModelThumbnailProps {
+	model: string;
+	className?: string;
+}
+
+function ModelThumbnail( {
+	model,
+	className,
+}: ModelThumbnailProps ): React.ReactNode {
+	return model === 'masonry' ? (
+		<MasonryThumbnail className={ className } />
+	) : (
+		<GridThumbnail className={ className } />
+	);
+}
+
+/**
+ * Card-style picker for the layout model: each option (`grid`, `masonry`)
+ * renders as a thumbnail card in a radio group. Wired as the `Edit` control
+ * for the `model` field of the layout settings DataForm.
+ *
+ * @param {DataFormControlProps< WidgetGridSettings >} props DataForm control props.
+ */
+export function LayoutModelEditField( {
+	data,
+	field,
+	onChange,
+}: DataFormControlProps< WidgetGridSettings > ): React.ReactNode {
+	const { getValue, setValue, elements = [] } = field;
+	const value = getValue( { item: data } );
+	const disabled = field.isDisabled( { item: data, field } );
+
+	const onSelect = useCallback(
+		( nextValue: string | number | undefined ) =>
+			onChange( setValue( { item: data, value: nextValue } ) ),
+		[ data, onChange, setValue ]
+	);
+
+	return (
+		<Fieldset.Root>
+			<Fieldset.Legend>{ field.label }</Fieldset.Legend>
+			<Stack direction="row" gap="md" role="radiogroup">
+				{ elements.map( ( option ) => {
+					const isSelected = value === option.value;
+
+					return (
+						<Button
+							key={ String( option.value ) }
+							variant="unstyled"
+							role="radio"
+							aria-checked={ isSelected }
+							disabled={ disabled }
+							className={ clsx( styles.option, {
+								[ styles.optionSelected ]: isSelected,
+							} ) }
+							onClick={ () => onSelect( option.value ) }
+						>
+							<Stack direction="column" gap="sm" align="stretch">
+								<ModelThumbnail
+									model={ String( option.value ) }
+									className={ styles.thumbnail }
+								/>
+								<Text>{ option.label }</Text>
+							</Stack>
+						</Button>
+					);
+				} ) }
+			</Stack>
+			{ typeof field.description === 'string' && (
+				<Fieldset.Description>
+					{ field.description }
+				</Fieldset.Description>
+			) }
+		</Fieldset.Root>
+	);
+}

package/src/components/layout-settings/layout-model-edit-field/style.module.css

@@ -0,0 +1,34 @@
+.option {
+	flex: 1;
+	padding: var(--wpds-dimension-padding-md);
+	border: var(--wpds-border-width-xs) solid var(--wpds-color-stroke-surface-neutral);
+	border-radius: var(--wpds-border-radius-md);
+	background: transparent;
+	color: inherit;
+	cursor: var(--wpds-cursor-control);
+	text-align: center;
+	transition:
+		border-color var(--wpds-motion-duration-sm) var(--wpds-motion-easing-subtle),
+		background-color var(--wpds-motion-duration-sm) var(--wpds-motion-easing-subtle);
+}
+
+.option:hover {
+	border-color: var(--wpds-color-stroke-surface-neutral-strong);
+}
+
+.optionSelected,
+.optionSelected:hover {
+	border-color: var(--wpds-color-stroke-interactive-brand);
+	background-color: color-mix(in srgb, var(--wpds-color-background-surface-brand) 6%, transparent);
+}
+
+.thumbnail {
+	display: block;
+	inline-size: 100%;
+	block-size: auto;
+	color: var(--wpds-color-foreground-content-neutral-weak);
+}
+
+.optionSelected .thumbnail {
+	color: var(--wpds-color-foreground-interactive-brand);
+}

package/src/components/layout-settings/layout-model-edit-field/thumbnail-grid.tsx

@@ -0,0 +1,28 @@
+/**
+ * WordPress dependencies
+ */
+import { SVG, Rect } from '@wordpress/primitives';
+
+interface GridThumbnailProps {
+	className?: string;
+}
+
+export function GridThumbnail( {
+	className,
+}: GridThumbnailProps ): React.ReactNode {
+	return (
+		<SVG
+			className={ className }
+			viewBox="0 0 40 24"
+			fill="currentColor"
+			aria-hidden="true"
+		>
+			<Rect x="2" y="1.25" width="11" height="10" rx="1.5" />
+			<Rect x="14.5" y="1.25" width="11" height="10" rx="1.5" />
+			<Rect x="27" y="1.25" width="11" height="10" rx="1.5" />
+			<Rect x="2" y="12.75" width="11" height="10" rx="1.5" />
+			<Rect x="14.5" y="12.75" width="11" height="10" rx="1.5" />
+			<Rect x="27" y="12.75" width="11" height="10" rx="1.5" />
+		</SVG>
+	);
+}

package/src/components/layout-settings/layout-model-edit-field/thumbnail-masonry.tsx

@@ -0,0 +1,28 @@
+/**
+ * WordPress dependencies
+ */
+import { SVG, Rect } from '@wordpress/primitives';
+
+interface MasonryThumbnailProps {
+	className?: string;
+}
+
+export function MasonryThumbnail( {
+	className,
+}: MasonryThumbnailProps ): React.ReactNode {
+	return (
+		<SVG
+			className={ className }
+			viewBox="0 0 40 24"
+			fill="currentColor"
+			aria-hidden="true"
+		>
+			<Rect x="2" y="0.75" width="11" height="13" rx="1.5" />
+			<Rect x="2" y="15.25" width="11" height="8" rx="1.5" />
+			<Rect x="14.5" y="0.75" width="11" height="8" rx="1.5" />
+			<Rect x="14.5" y="10.25" width="11" height="13" rx="1.5" />
+			<Rect x="27" y="0.75" width="11" height="10" rx="1.5" />
+			<Rect x="27" y="12.25" width="11" height="11" rx="1.5" />
+		</SVG>
+	);
+}

package/src/components/layout-settings/layout-settings.tsx

@@ -0,0 +1,217 @@
+/**
+ * WordPress dependencies
+ */
+import { DataForm } from '@wordpress/dataviews';
+import type { Field, Form } from '@wordpress/dataviews';
+import { useCallback, useEffect } from '@wordpress/element';
+import { __ } from '@wordpress/i18n';
+import { Button, Drawer } from '@wordpress/ui'; // eslint-disable-line @wordpress/use-recommended-components
+
+/**
+ * Internal dependencies
+ */
+import { useDashboardInternalContext } from '../../context/dashboard-context';
+import { useDashboardUIContext } from '../../context/ui-context';
+import { migrateLayout } from '../../utils/migrate-layout';
+import {
+	presetToRowHeight,
+	rowHeightToPreset,
+	type RowHeightPreset,
+} from '../../utils/row-height-presets';
+import {
+	WIDGET_DASHBOARD_COLUMN_COUNT,
+	type WidgetGridLayoutSettings,
+	type WidgetGridModel,
+	type WidgetGridSettings,
+} from '../../types';
+import { LayoutModelEditField } from './layout-model-edit-field';
+
+function getModel( item: WidgetGridSettings ): WidgetGridModel {
+	return item.model ?? 'grid';
+}
+
+function isMasonry( item: WidgetGridSettings ): boolean {
+	return getModel( item ) === 'masonry';
+}
+
+const fields: Field< WidgetGridSettings >[] = [
+	{
+		id: 'model',
+		type: 'text',
+		Edit: LayoutModelEditField,
+		label: __( 'Layout model' ),
+		description: __(
+			'Grid keeps every tile the same height. Masonry lets tiles flow at their own height.'
+		),
+		elements: [
+			{ value: 'grid', label: __( 'Standard grid' ) },
+			{ value: 'masonry', label: __( 'Masonry' ) },
+		],
+		getValue: ( { item } ) => getModel( item ),
+	},
+	{
+		id: 'rowHeight',
+		type: 'text',
+		Edit: 'toggleGroup',
+		label: __( 'Row height' ),
+		description: __( 'Height of each grid row.' ),
+		elements: [
+			{ value: 'small', label: __( 'Small' ) },
+			{ value: 'medium', label: __( 'Medium' ) },
+			{ value: 'large', label: __( 'Large' ) },
+		],
+		getValue: ( { item } ) => {
+			const rowHeight = ( item as WidgetGridLayoutSettings ).rowHeight;
+			if ( typeof rowHeight !== 'number' ) {
+				return 'medium';
+			}
+			return rowHeightToPreset( rowHeight );
+		},
+		setValue: ( { value } ) => ( {
+			rowHeight: presetToRowHeight( value as RowHeightPreset ),
+		} ),
+		isVisible: ( item ) => ! isMasonry( item ),
+	},
+];
+
+const form: Form = {
+	layout: { type: 'regular', labelPosition: 'top' },
+	fields: [ 'model', 'rowHeight' ],
+};
+
+/**
+ * Modal side drawer for grid-level settings (layout model and row height),
+ * mounted by the engine and shown while `layoutSettingsOpen` is set in the
+ * shared UI context. Renders nothing when grid settings are not editable.
+ *
+ * Edits, including Reset, apply to the staging copy and preview live behind
+ * the drawer. Save commits them; Cancel and any other dismissal (X, Escape)
+ * revert them. Either way only grid settings change, so in-progress widget
+ * layout edits survive and customize mode stays active.
+ *
+ * Tile gap is deliberately not exposed; spacing stays a design-system concern.
+ */
+export function LayoutSettings(): React.ReactNode {
+	const {
+		gridSettings,
+		onGridSettingsChange,
+		layout,
+		onLayoutChange,
+		commit,
+		cancel: cancelStaging,
+		resetGridSettings,
+		hasUncommittedChanges,
+		canEditGridSettings,
+		editMode,
+	} = useDashboardInternalContext();
+
+	const { layoutSettingsOpen: open, setLayoutSettingsOpen: onOpenChange } =
+		useDashboardUIContext();
+
+	// Close when customize mode exits, whatever the exit path.
+	useEffect( () => {
+		if ( ! editMode && open ) {
+			onOpenChange( false );
+		}
+	}, [ editMode, open, onOpenChange ] );
+
+	const handleChange = useCallback(
+		( edits: Record< string, unknown > ) => {
+			const nextModel = edits.model as WidgetGridModel | undefined;
+			const currentModel = getModel( gridSettings );
+
+			if ( nextModel && nextModel !== currentModel ) {
+				const migrated = migrateLayout(
+					layout,
+					currentModel,
+					nextModel,
+					{ columns: WIDGET_DASHBOARD_COLUMN_COUNT }
+				);
+				onLayoutChange( migrated );
+			}
+
+			onGridSettingsChange( {
+				...gridSettings,
+				...edits,
+			} as WidgetGridSettings );
+		},
+		[ gridSettings, layout, onGridSettingsChange, onLayoutChange ]
+	);
+
+	const handleCancel = useCallback( () => {
+		cancelStaging( { exitEditMode: false, revertLayout: false } );
+		onOpenChange( false );
+	}, [ cancelStaging, onOpenChange ] );
+
+	const handleSave = useCallback( () => {
+		commit( { exitEditMode: false } );
+		onOpenChange( false );
+	}, [ commit, onOpenChange ] );
+
+	const handleOpenChange = useCallback(
+		( nextOpen: boolean ) => {
+			if ( ! nextOpen && open ) {
+				cancelStaging( { exitEditMode: false, revertLayout: false } );
+			}
+			onOpenChange( nextOpen );
+		},
+		[ open, cancelStaging, onOpenChange ]
+	);
+
+	if ( ! canEditGridSettings ) {
+		return null;
+	}
+
+	return (
+		<Drawer.Root
+			open={ open }
+			onOpenChange={ handleOpenChange }
+			swipeDirection="right"
+		>
+			<Drawer.Popup size="medium" style={ { marginTop: '32px' } }>
+				<Drawer.Header>
+					<Drawer.Title>{ __( 'Layout settings' ) }</Drawer.Title>
+					<Drawer.CloseIcon />
+				</Drawer.Header>
+
+				<Drawer.Content>
+					<DataForm
+						data={ gridSettings }
+						fields={ fields }
+						form={ form }
+						onChange={ handleChange }
+					/>
+				</Drawer.Content>
+
+				<Drawer.Footer>
+					<Button
+						variant="minimal"
+						tone="neutral"
+						size="compact"
+						onClick={ resetGridSettings }
+						style={ { marginInlineEnd: 'auto' } }
+					>
+						{ __( 'Reset' ) }
+					</Button>
+					<Button
+						variant="minimal"
+						tone="brand"
+						size="compact"
+						onClick={ handleCancel }
+					>
+						{ __( 'Cancel' ) }
+					</Button>
+					<Button
+						variant="solid"
+						tone="brand"
+						size="compact"
+						onClick={ handleSave }
+						disabled={ ! hasUncommittedChanges }
+					>
+						{ __( 'Save' ) }
+					</Button>
+				</Drawer.Footer>
+			</Drawer.Popup>
+		</Drawer.Root>
+	);
+}

package/src/components/no-widgets-state/index.ts

@@ -0,0 +1 @@
+export { NoWidgetsState } from './no-widgets-state';

package/src/components/no-widgets-state/no-widgets-state.module.css

@@ -0,0 +1,3 @@
+.root {
+	padding-block-start: calc(var(--wpds-dimension-padding-3xl) * 3.5);
+}