@wordpress/widget-dashboard 0.1.0

package/build-types/utils/resolve-dashboard-column-count/resolve-dashboard-column-count.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Container width (px) below which the dashboard uses a single column.
+ * Matches `@container widget-dashboard (max-width: …)` in widgets CSS.
+ */
+export declare 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 declare 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 declare function resolveDashboardColumnCount(containerWidth: number): number;
+//# sourceMappingURL=resolve-dashboard-column-count.d.ts.map

package/build-types/utils/resolve-dashboard-column-count/resolve-dashboard-column-count.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-dashboard-column-count.d.ts","sourceRoot":"","sources":["../../../src/utils/resolve-dashboard-column-count/resolve-dashboard-column-count.ts"],"names":[],"mappings":"AAKA;;;GAGG;AACH,eAAO,MAAM,gDAAgD,MAAM,CAAC;AAEpE;;;;GAIG;AACH,eAAO,MAAM,iDAAiD,MAAM,CAAC;AAErE;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAE,cAAc,EAAE,MAAM,GAAI,MAAM,CAc5E"}

package/build-types/utils/row-height-presets/index.d.ts

@@ -0,0 +1,3 @@
+export { DEFAULT_ROW_HEIGHT, ROW_HEIGHT_PRESETS, presetToRowHeight, rowHeightToPreset, snapRowHeight, } from './row-height-presets';
+export type { RowHeightPreset } from './row-height-presets';
+//# sourceMappingURL=index.d.ts.map

package/build-types/utils/row-height-presets/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/row-height-presets/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,GACb,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC"}

package/build-types/utils/row-height-presets/row-height-presets.d.ts

@@ -0,0 +1,17 @@
+export declare const ROW_HEIGHT_PRESETS: {
+    readonly small: 200;
+    readonly medium: 300;
+    readonly large: 400;
+};
+export type RowHeightPreset = keyof typeof ROW_HEIGHT_PRESETS;
+export declare const DEFAULT_ROW_HEIGHT: 300;
+/**
+ * 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 declare function rowHeightToPreset(rowHeight: number): RowHeightPreset;
+export declare function presetToRowHeight(preset: RowHeightPreset): number;
+export declare function snapRowHeight(rowHeight: number): number;
+//# sourceMappingURL=row-height-presets.d.ts.map

package/build-types/utils/row-height-presets/row-height-presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"row-height-presets.d.ts","sourceRoot":"","sources":["../../../src/utils/row-height-presets/row-height-presets.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB;aAC9B,KAAK,EAAE,GAAG;aACV,MAAM,EAAE,GAAG;aACX,KAAK,EAAE,GAAG;CACD,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,kBAAkB,CAAC;AAE9D,eAAO,MAAM,kBAAkB,KAA4B,CAAC;AAO5D;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAE,SAAS,EAAE,MAAM,GAAI,eAAe,CAatE;AAED,wBAAgB,iBAAiB,CAAE,MAAM,EAAE,eAAe,GAAI,MAAM,CAEnE;AAED,wBAAgB,aAAa,CAAE,SAAS,EAAE,MAAM,GAAI,MAAM,CAEzD"}

package/build-types/widget-dashboard.d.ts

@@ -0,0 +1,51 @@
+import { Actions } from './components/actions';
+import { Commands } from './components/commands';
+import { NoWidgetsState } from './components/no-widgets-state';
+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 declare const WidgetDashboard: (({ layout, onLayoutChange, onLayoutReset, widgetTypes, isResolvingWidgetTypes, editMode, onEditChange, resolveWidgetModule, gridSettings, onGridSettingsChange, children, }: WidgetDashboardProps) => import("react").JSX.Element) & {
+    Actions: typeof Actions;
+    Widgets: import("react").ForwardRefExoticComponent<import("./components/widgets/widgets").WidgetsProps & import("react").RefAttributes<HTMLDivElement>>;
+    WidgetChrome: import("react").ForwardRefExoticComponent<import("./components/widget-chrome/widget-chrome").WidgetChromeProps & import("react").RefAttributes<HTMLDivElement>>;
+    NoWidgetsState: typeof NoWidgetsState;
+    Commands: typeof Commands;
+};
+//# sourceMappingURL=widget-dashboard.d.ts.map

package/build-types/widget-dashboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-dashboard.d.ts","sourceRoot":"","sources":["../src/widget-dashboard.tsx"],"names":[],"mappings":"AAKA,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEjD,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAM/D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,eAAe,gLAaxB,oBAAoB;;;;;;CAiCvB,CAAC"}

package/package.json

@@ -0,0 +1,90 @@
+{
+	"name": "@wordpress/widget-dashboard",
+	"version": "0.1.0",
+	"description": "Stateless rendering engine for widget dashboards: the WidgetDashboard compound component and its grid-settings kit.",
+	"author": "The WordPress Contributors",
+	"license": "GPL-2.0-or-later",
+	"keywords": [
+		"wordpress",
+		"gutenberg",
+		"widgets",
+		"dashboard",
+		"grid"
+	],
+	"homepage": "https://github.com/WordPress/gutenberg/tree/HEAD/packages/widget-dashboard/README.md",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/WordPress/gutenberg.git",
+		"directory": "packages/widget-dashboard"
+	},
+	"bugs": {
+		"url": "https://github.com/WordPress/gutenberg/issues"
+	},
+	"engines": {
+		"node": ">=20.10.0",
+		"npm": ">=10.2.3"
+	},
+	"files": [
+		"src",
+		"build",
+		"build-module",
+		"build-types",
+		"*.md"
+	],
+	"main": "build/index.cjs",
+	"module": "build-module/index.mjs",
+	"exports": {
+		".": {
+			"types": "./build-types/index.d.ts",
+			"import": "./build-module/index.mjs",
+			"default": "./build/index.cjs"
+		},
+		"./package.json": "./package.json"
+	},
+	"wpScript": false,
+	"types": "build-types",
+	"sideEffects": [
+		"src/**/*.module.css"
+	],
+	"dependencies": {
+		"@wordpress/commands": "^1.49.0",
+		"@wordpress/components": "^36.0.0",
+		"@wordpress/compose": "^8.2.0",
+		"@wordpress/data": "^10.49.0",
+		"@wordpress/dataviews": "^17.0.0",
+		"@wordpress/element": "^8.1.0",
+		"@wordpress/grid": "^0.1.0",
+		"@wordpress/i18n": "^6.22.0",
+		"@wordpress/icons": "^15.0.0",
+		"@wordpress/primitives": "^4.49.0",
+		"@wordpress/private-apis": "^1.49.0",
+		"@wordpress/style-runtime": "^0.5.0",
+		"@wordpress/ui": "^0.16.0",
+		"@wordpress/viewport": "^6.49.0",
+		"@wordpress/widget-primitives": "^0.1.0",
+		"clsx": "^2.1.1",
+		"fast-deep-equal": "^3.1.3",
+		"uuid": "^14.0.0"
+	},
+	"devDependencies": {
+		"@testing-library/dom": "^10.4.1",
+		"@testing-library/jest-dom": "^6.9.1",
+		"@testing-library/react": "^16.3.2",
+		"@testing-library/user-event": "^14.6.1",
+		"@types/jest": "^29.5.14"
+	},
+	"peerDependencies": {
+		"@types/react": "^18.3.27",
+		"react": "^18.0.0",
+		"react-dom": "^18.0.0"
+	},
+	"peerDependenciesMeta": {
+		"@types/react": {
+			"optional": true
+		}
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"gitHead": "0e7112a4f4fde4ea15bd9060489b8f6fe11eb6ca"
+}

package/src/components/actions/actions.module.css

@@ -0,0 +1,54 @@
+.editActionsEnter,
+.editActionsExit {
+	display: inline-flex;
+	align-items: center;
+	gap: var(--wp--preset--spacing--20);
+	transform-origin: right center;
+}
+
+.editActionsDivider {
+	flex-shrink: 0;
+	align-self: center;
+	width: 1px;
+	height: var(--wpds-dimension-size-2xs);
+	background-color: var(--wpds-color-stroke-surface-neutral);
+}
+
+@media not ( prefers-reduced-motion ) {
+	.editActionsEnter,
+	.editActionsExit {
+		will-change: opacity, transform;
+	}
+
+	.editActionsEnter {
+		animation: actions-slide-in var(--wpds-motion-duration-md) var(--wpds-motion-easing-expressive) forwards;
+	}
+
+	.editActionsExit {
+		animation: actions-fold-out var(--wpds-motion-duration-sm) var(--wpds-motion-easing-balanced) forwards;
+	}
+
+	@keyframes actions-slide-in {
+		from {
+			opacity: 0;
+			transform: translateX(12px) scaleX(0.92);
+		}
+
+		to {
+			opacity: 1;
+			transform: translateX(0) scaleX(1);
+		}
+	}
+
+	@keyframes actions-fold-out {
+		from {
+			opacity: 1;
+			transform: translateX(0) scaleX(1);
+		}
+
+		to {
+			opacity: 0;
+			transform: translateX(12px) scaleX(0.92);
+		}
+	}
+}

package/src/components/actions/actions.tsx

@@ -0,0 +1,180 @@
+/**
+ * WordPress dependencies
+ */
+import { useSelect } from '@wordpress/data';
+import { useCallback, useEffect, useState } from '@wordpress/element';
+import { __ } from '@wordpress/i18n';
+import { layout as layoutIcon, plus } from '@wordpress/icons';
+import { store as viewportStore } from '@wordpress/viewport';
+// eslint-disable-next-line @wordpress/use-recommended-components
+import { Button, Stack } from '@wordpress/ui';
+
+/**
+ * Internal dependencies
+ */
+import { useDashboardInternalContext } from '../../context/dashboard-context';
+import { useDashboardUIContext } from '../../context/ui-context';
+import { ActionsMenu } from '../actions-menu';
+import type { ActionsMenuItem } from '../actions-menu';
+import styles from './actions.module.css';
+
+/**
+ * Edit toolbar for the dashboard. In customize mode it surfaces Add widget,
+ * Layout settings (when grid settings are editable), Cancel, and Done;
+ * otherwise a single Customize button. Buttons and the overflow menu are
+ * triggers that flip the shared UI state the overlays react to.
+ *
+ * Returns `null` when mounted without `onEditChange`, so hosts that don't
+ * expose edit mode can keep `Actions` in their tree unconditionally.
+ */
+export function Actions(): React.ReactNode {
+	const {
+		editMode,
+		onEditChange,
+		onLayoutReset,
+		commit,
+		cancel: cancelStaging,
+		hasUncommittedChanges,
+		canEditGridSettings,
+	} = useDashboardInternalContext();
+
+	const [ isEditActionsMounted, setIsEditActionsMounted ] =
+		useState( editMode );
+	const [ isExitingEditActions, setIsExitingEditActions ] = useState( false );
+
+	useEffect( () => {
+		if ( editMode ) {
+			setIsEditActionsMounted( true );
+			setIsExitingEditActions( false );
+			return;
+		}
+
+		if ( ! isEditActionsMounted ) {
+			return;
+		}
+
+		setIsExitingEditActions( true );
+		const exitTimeout = setTimeout( () => {
+			setIsEditActionsMounted( false );
+			setIsExitingEditActions( false );
+		}, 220 );
+
+		return () => clearTimeout( exitTimeout );
+	}, [ editMode, isEditActionsMounted ] );
+
+	const { setInserterOpen, setLayoutSettingsOpen, setResetDialogOpen } =
+		useDashboardUIContext();
+	// @TODO: switch to using Admin UI declaratively for mobile viewport support once available.
+	// https://github.com/WordPress/gutenberg/issues/77628
+	const isMobileViewport = useSelect(
+		( select ) => select( viewportStore ).isViewportMatch( '< small' ),
+		[]
+	);
+
+	const handleEditMode = useCallback( () => {
+		onEditChange?.( ! editMode );
+	}, [ editMode, onEditChange ] );
+
+	const insert = useCallback( () => {
+		setInserterOpen( true );
+	}, [ setInserterOpen ] );
+
+	const cancel = useCallback( () => {
+		cancelStaging();
+	}, [ cancelStaging ] );
+
+	const done = useCallback( () => {
+		commit();
+	}, [ commit ] );
+
+	const openLayoutSettings = useCallback( () => {
+		setLayoutSettingsOpen( true );
+	}, [ setLayoutSettingsOpen ] );
+
+	const menuItems: ActionsMenuItem[] = [
+		{
+			label: __( 'Reset to default' ),
+			onClick: () => setResetDialogOpen( true ),
+			disabled: ! onLayoutReset,
+		},
+	];
+
+	if ( ! onEditChange ) {
+		return null;
+	}
+
+	return (
+		<Stack direction="row" gap="sm">
+			{ isEditActionsMounted ? (
+				<Stack
+					direction="row"
+					gap="sm"
+					className={
+						isExitingEditActions
+							? styles.editActionsExit
+							: styles.editActionsEnter
+					}
+				>
+					<Button
+						variant="minimal"
+						tone="brand"
+						size="compact"
+						onClick={ insert }
+					>
+						{ ! isMobileViewport && <Button.Icon icon={ plus } /> }
+						{ __( 'Add widget' ) }
+					</Button>
+
+					{ canEditGridSettings && (
+						<Button
+							variant="minimal"
+							tone="brand"
+							size="compact"
+							onClick={ openLayoutSettings }
+						>
+							{ ! isMobileViewport && (
+								<Button.Icon icon={ layoutIcon } />
+							) }
+							{ __( 'Layout settings' ) }
+						</Button>
+					) }
+
+					<div
+						className={ styles.editActionsDivider }
+						aria-hidden="true"
+					/>
+
+					<Button
+						variant="minimal"
+						tone="brand"
+						size="compact"
+						onClick={ cancel }
+					>
+						{ __( 'Cancel' ) }
+					</Button>
+
+					<Button
+						variant="solid"
+						tone="brand"
+						size="compact"
+						onClick={ done }
+						disabled={ ! hasUncommittedChanges }
+					>
+						{ __( 'Done' ) }
+					</Button>
+				</Stack>
+			) : (
+				<Button
+					variant="minimal"
+					tone="brand"
+					size="compact"
+					onClick={ handleEditMode }
+				>
+					{ __( 'Customize' ) }
+				</Button>
+			) }
+
+			<ActionsMenu items={ menuItems } />
+		</Stack>
+	);
+}

package/src/components/actions/index.ts

@@ -0,0 +1 @@
+export { Actions } from './actions';

package/src/components/actions-menu/actions-menu.tsx

@@ -0,0 +1,104 @@
+/**
+ * WordPress dependencies
+ */
+import { privateApis as componentsPrivateApis } from '@wordpress/components';
+import { __ } from '@wordpress/i18n';
+import { moreVertical } from '@wordpress/icons';
+// eslint-disable-next-line @wordpress/use-recommended-components
+import { Button, IconButton, Tooltip } from '@wordpress/ui';
+
+/**
+ * Internal dependencies
+ */
+import { unlock } from '../../lock-unlock';
+
+const { Menu } = unlock( componentsPrivateApis );
+
+export interface ActionsMenuItem {
+	label: string;
+	onClick: () => void;
+	disabled?: boolean;
+	/**
+	 * Shown on hover when the item is disabled (for example, to explain
+	 * why the action is unavailable).
+	 */
+	disabledTooltip?: string;
+}
+
+interface ActionsMenuProps {
+	items: ActionsMenuItem[];
+}
+
+function ActionsMenuEntry( { item }: { item: ActionsMenuItem } ) {
+	const showDisabledTooltip = item.disabled && item.disabledTooltip;
+
+	const menuItem = (
+		<Menu.Item
+			disabled={ item.disabled }
+			onClick={ item.onClick }
+			render={ <Button variant="minimal" tone="neutral" /> }
+		>
+			{ item.label }
+		</Menu.Item>
+	);
+
+	if ( ! showDisabledTooltip ) {
+		return menuItem;
+	}
+
+	return (
+		<Tooltip.Root>
+			<Tooltip.Trigger
+				render={
+					<Menu.Item
+						disabled={ item.disabled }
+						onClick={ item.onClick }
+						render={ <Button variant="minimal" tone="neutral" /> }
+					/>
+				}
+			>
+				{ item.label }
+			</Tooltip.Trigger>
+			<Tooltip.Popup positioner={ <Tooltip.Positioner side="bottom" /> }>
+				{ item.disabledTooltip }
+			</Tooltip.Popup>
+		</Tooltip.Root>
+	);
+}
+
+/**
+ * Renders the dashboard's overflow menu: a three-dots trigger surfacing
+ * secondary actions. Returns `null` when there are no items.
+ *
+ * @param {ActionsMenuProps} props Component props.
+ */
+export function ActionsMenu( { items }: ActionsMenuProps ): React.ReactNode {
+	if ( items.length === 0 ) {
+		return null;
+	}
+
+	return (
+		<Menu>
+			<Menu.TriggerButton
+				render={
+					<IconButton
+						icon={ moreVertical }
+						label={ __( 'More options' ) }
+						variant="minimal"
+						tone="brand"
+						size="compact"
+					/>
+				}
+			/>
+			<Menu.Popover>
+				<Tooltip.Provider delay={ 0 }>
+					<Menu.Group>
+						{ items.map( ( item, index ) => (
+							<ActionsMenuEntry key={ index } item={ item } />
+						) ) }
+					</Menu.Group>
+				</Tooltip.Provider>
+			</Menu.Popover>
+		</Menu>
+	);
+}

package/src/components/actions-menu/index.ts

@@ -0,0 +1,2 @@
+export { ActionsMenu } from './actions-menu';
+export type { ActionsMenuItem } from './actions-menu';