@wordpress/widget-dashboard 0.2.0 → 0.3.0

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

@@ -1,12 +1,12 @@
-.editActionsEnter,
-.editActionsExit {
+.edit-actions-enter,
+.edit-actions-exit {
 	display: inline-flex;
 	align-items: center;
 	gap: var(--wp--preset--spacing--20);
 	transform-origin: right center;
 }
 
-.editActionsDivider {
+.edit-actions-divider {
 	flex-shrink: 0;
 	align-self: center;
 	width: 1px;
@@ -15,16 +15,16 @@
 }
 
 @media not ( prefers-reduced-motion ) {
-	.editActionsEnter,
-	.editActionsExit {
+	.edit-actions-enter,
+	.edit-actions-exit {
 		will-change: opacity, transform;
 	}
 
-	.editActionsEnter {
+	.edit-actions-enter {
 		animation: actions-slide-in var(--wpds-motion-duration-md) var(--wpds-motion-easing-expressive) forwards;
 	}
 
-	.editActionsExit {
+	.edit-actions-exit {
 		animation: actions-fold-out var(--wpds-motion-duration-sm) var(--wpds-motion-easing-balanced) forwards;
 	}
 

package/src/components/actions/actions.tsx

@@ -4,7 +4,7 @@
 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 { 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';
@@ -35,7 +35,6 @@ export function Actions(): React.ReactNode {
 		commit,
 		cancel: cancelStaging,
 		hasUncommittedChanges,
-		canEditGridSettings,
 	} = useDashboardInternalContext();
 
 	const [ isEditActionsMounted, setIsEditActionsMounted ] =
@@ -62,8 +61,7 @@ export function Actions(): React.ReactNode {
 		return () => clearTimeout( exitTimeout );
 	}, [ editMode, isEditActionsMounted ] );
 
-	const { setInserterOpen, setLayoutSettingsOpen, setResetDialogOpen } =
-		useDashboardUIContext();
+	const { setInserterOpen, 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(
@@ -87,10 +85,6 @@ export function Actions(): React.ReactNode {
 		commit();
 	}, [ commit ] );
 
-	const openLayoutSettings = useCallback( () => {
-		setLayoutSettingsOpen( true );
-	}, [ setLayoutSettingsOpen ] );
-
 	const menuItems: ActionsMenuItem[] = [
 		{
 			label: __( 'Reset to default' ),
@@ -111,8 +105,8 @@ export function Actions(): React.ReactNode {
 					gap="sm"
 					className={
 						isExitingEditActions
-							? styles.editActionsExit
-							: styles.editActionsEnter
+							? styles[ 'edit-actions-exit' ]
+							: styles[ 'edit-actions-enter' ]
 					}
 				>
 					<Button
@@ -125,22 +119,8 @@ export function Actions(): React.ReactNode {
 						{ __( '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 }
+						className={ styles[ 'edit-actions-divider' ] }
 						aria-hidden="true"
 					/>
 

package/src/components/commands/commands.tsx

@@ -7,13 +7,7 @@ import {
 	useCommands,
 	privateApis as commandsPrivateApis,
 } from '@wordpress/commands';
-import {
-	columns,
-	grid,
-	layout as layoutIcon,
-	plus,
-	trash,
-} from '@wordpress/icons';
+import { layout as layoutIcon, plus, trash } from '@wordpress/icons';
 
 /**
  * Internal dependencies
@@ -21,7 +15,6 @@ import {
 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 );
@@ -35,14 +28,8 @@ type CommandCallback = ( options: { close: () => void } ) => void;
  * active command context so they surface under Suggestions by default.
  */
 export function Commands() {
-	const {
-		editMode,
-		onEditChange,
-		onLayoutReset,
-		gridSettings,
-		canEditGridSettings,
-		commitGridModelChange,
-	} = useDashboardInternalContext();
+	const { editMode, onEditChange, onLayoutReset } =
+		useDashboardInternalContext();
 
 	const { setInserterOpen, setResetDialogOpen } = useDashboardUIContext();
 
@@ -53,26 +40,6 @@ export function Commands() {
 		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();
@@ -121,35 +88,6 @@ export function Commands() {
 				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' ),
@@ -166,11 +104,6 @@ export function Commands() {
 			editMode,
 			customize,
 			addWidgets,
-			canEditGridSettings,
-			isMasonryLayout,
-			isGridLayout,
-			switchToMasonry,
-			switchToGrid,
 			onLayoutReset,
 			resetToDefault,
 		]

package/src/components/widget-attribute-controls/index.ts

@@ -0,0 +1 @@
+export { WidgetAttributeControls } from './widget-attribute-controls';

package/src/components/widget-attribute-controls/widget-attribute-controls.tsx

@@ -0,0 +1,108 @@
+/**
+ * WordPress dependencies
+ */
+import { DataForm } from '@wordpress/dataviews';
+import type { Field, Form } from '@wordpress/dataviews';
+import { useCallback, useMemo } from '@wordpress/element';
+import type { WidgetType } from '@wordpress/widget-primitives';
+
+/**
+ * Internal dependencies
+ */
+import { useDashboardInternalContext } from '../../context/dashboard-context';
+import { WidgetSettingsTrigger } from '../widget-settings';
+import type { DashboardWidget } from '../../types';
+
+type WidgetAttributes = Record< string, unknown >;
+
+type WidgetAttributeControlsProps = {
+	/**
+	 * The instance whose attributes these controls edit.
+	 */
+	widget: DashboardWidget< unknown >;
+
+	/**
+	 * The instance's widget type, source of the attribute schema.
+	 */
+	widgetType: WidgetType;
+};
+
+/**
+ * Normal-mode controls: the `relevance: 'high'` attributes on a prominent
+ * surface, plus a settings entry point when needed. Inline controls appear
+ * only for the high-relevance fields; edits stage live and auto-save on the
+ * dashboard's shared debounce.
+ *
+ * @param {WidgetAttributeControlsProps} props Component props.
+ */
+export function WidgetAttributeControls( {
+	widget,
+	widgetType,
+}: WidgetAttributeControlsProps ): React.ReactNode {
+	const { layout, onLayoutChange, scheduleAutoSave } =
+		useDashboardInternalContext();
+
+	const fields = useMemo< Field< WidgetAttributes >[] >(
+		() =>
+			( widgetType.attributes ?? [] ).filter(
+				( attribute ) => attribute.relevance === 'high'
+			) as Field< WidgetAttributes >[],
+		[ widgetType.attributes ]
+	);
+
+	// A `row` top-level layout lays the controls out horizontally; each field
+	// carries `labelPosition: 'none'` so the control renders bare.
+	const form = useMemo< Form >(
+		() => ( {
+			layout: { type: 'row', alignment: 'center' },
+			fields: fields.map( ( field ) => ( {
+				id: field.id,
+				layout: { type: 'regular', labelPosition: 'none' },
+			} ) ),
+		} ),
+		[ fields ]
+	);
+
+	const handleChange = useCallback(
+		( edits: Record< string, unknown > ) => {
+			onLayoutChange(
+				layout.map( ( instance ) =>
+					instance.uuid === widget.uuid
+						? {
+								...instance,
+								attributes: {
+									...( instance.attributes as object ),
+									...edits,
+								},
+						  }
+						: instance
+				)
+			);
+
+			scheduleAutoSave();
+		},
+		[ layout, onLayoutChange, widget.uuid, scheduleAutoSave ]
+	);
+
+	const data = ( widget.attributes ??
+		widgetType.example?.attributes ??
+		{} ) as WidgetAttributes;
+
+	return (
+		<>
+			{ fields.length > 0 && (
+				<DataForm< WidgetAttributes >
+					data={ data }
+					fields={ fields }
+					form={ form }
+					onChange={ handleChange }
+				/>
+			) }
+
+			<WidgetSettingsTrigger
+				widget={ widget }
+				widgetType={ widgetType }
+			/>
+		</>
+	);
+}

package/src/components/widget-chrome/widget-chrome.module.css

@@ -1,87 +1,22 @@
-.widgetChrome {
-	height: 100%;
-
-	/*
-	 * Isolate the widget body from the surrounding layout. In a fixed-row
-	 * grid the tile height comes from its row span, but a body taller than
-	 * the tile lets its intrinsic size feed the grid item's `min-height: auto`
-	 * and overflow the cell, adding scroll space below the grid. Layout
-	 * containment severs that propagation so the body stays within the tile
-	 * and scrolls internally. It contains layout only, not size or paint, so
-	 * the masonry surface still measures the tile from its content and the
-	 * tile elevation is not clipped.
-	 */
-	contain: layout;
-}
-
-/*
- * When keyboard focus lands on the widget's own content (a link or control
- * the render module draws), outline the whole tile so Tab users can tell
- * which widget holds focus, since an inner ring alone is easy to miss. Scoped
- * to content focus, and to `:focus-visible` so a mouse click doesn't draw it.
- */
-.widgetChrome:has(.widgetChromeContent :focus-visible) {
+/* Outward tile focus ring; paint space reserved on `.grid`. */
+.widget-chrome:has(:focus-visible) {
 	outline: var(--wpds-border-width-focus) solid var(--wpds-color-stroke-focus);
-	outline-offset: 2px;
+	outline-offset: var(--wp-widget-dashboard-tile-focus-offset, 2px);
 }
 
-.widgetChromeHeaderIcon {
+.widget-chrome-header-icon {
 	display: inline-flex;
 	color: var(--wpds-color-foreground-content-neutral);
 }
 
-/*
- * Scroll container for the widget body. The card root clips its own overflow
- * and the header is a fixed-size flex sibling, so confining the scroll to this
- * element is what keeps the header pinned while the body scrolls.
- */
-.widgetChromeContent {
+/* Fill the tile so placeholder states center in the full height. */
+.widget-chrome-content {
 	flex: 1;
 	height: 100%;
-	overflow-y: auto;
-
-	/*
-	 * As a flex item, the content area defaults to `min-height: auto`, which
-	 * lets tall widget content expand it past the height the card allots
-	 * instead of staying bounded. Pinning the min sizes to 0 keeps the area
-	 * within its slot so a widget's own `overflow` scrolls internally rather
-	 * than pushing past the card.
-	 */
 	min-width: 0;
 	min-height: 0;
 }
 
-/*
- * Bleed block edges: zero the content's block padding so the body fills the
- * card top to bottom. The top is ours to flush (a full-bleed widget hides its
- * header in a position:absolute VisuallyHidden node that stays the card's
- * :first-child and blocks Card.FullBleed's top-flush rule). The bottom pairs
- * with the `margin-block-end: 0` on the bleed scroll wrapper below.
- */
-.widgetChromeContentBleed {
-	padding-block: 0;
-}
-
-/*
- * Scroll container for a bleeding body. Card.FullBleed only does the edge
- * breakout (negative margins) and declares no height or overflow, so the scroll
- * container must be re-established here, on the wrapper that spans the card
- * edges, so the scrollbar tracks the edge and the header stays pinned.
- *
- * Card.FullBleed also adds `margin-block-end: calc(var(--wp-ui-card-padding) *
- * -1)` to cancel the content's bottom padding; that padding is zeroed above, so
- * neutralize the margin. Left in, it pulls the wrapper's box short of the body,
- * surfacing as a phantom scrollbar on a content-driven tile or a bottom inset
- * on a fixed-height one.
- */
-.widgetChromeBleedScroll {
-	height: 100%;
-	overflow-y: auto;
-	margin-block-end: 0;
-}
-
-.loading,
 .unavailable {
 	height: 100%;
 }
-

package/src/components/widget-chrome/widget-chrome.tsx

@@ -7,69 +7,20 @@ import type { ReactNode } from 'react';
 /**
  * WordPress dependencies
  */
-import { Spinner } from '@wordpress/components';
-import {
-	Component,
-	Suspense,
-	forwardRef,
-	useId,
-	useMemo,
-} from '@wordpress/element';
+import { forwardRef, useId, useMemo } from '@wordpress/element';
 import { __ } from '@wordpress/i18n';
 import { plugins } from '@wordpress/icons';
-// eslint-disable-next-line @wordpress/use-recommended-components
-import { Card, Icon, Stack, Notice, Text, VisuallyHidden } from '@wordpress/ui';
-import type { WidgetType } from '@wordpress/widget-primitives';
+import { Card, Icon, Stack, Text } from '@wordpress/ui';
 
 /**
  * Internal dependencies
  */
 import { useDashboardInternalContext } from '../../context/dashboard-context';
 import { WidgetContextProvider } from '../../context/widget-context';
-import { WidgetRender } from '../widget-render';
+import { LoadingOverlay, WidgetFrame } from '../widget-frame';
 import styles from './widget-chrome.module.css';
 import type { DashboardWidget } from '../../types';
 
-interface ErrorBoundaryProps {
-	children: ReactNode;
-}
-
-interface ErrorBoundaryState {
-	hasError: boolean;
-}
-
-class WidgetErrorBoundary extends Component<
-	ErrorBoundaryProps,
-	ErrorBoundaryState
-> {
-	state: ErrorBoundaryState = { hasError: false };
-
-	static getDerivedStateFromError(): ErrorBoundaryState {
-		return { hasError: true };
-	}
-
-	render() {
-		if ( this.state.hasError ) {
-			return (
-				<Notice.Root intent="error">
-					<Notice.Description>
-						{ __( 'This widget encountered an error.' ) }
-					</Notice.Description>
-				</Notice.Root>
-			);
-		}
-		return this.props.children;
-	}
-}
-
-function LoadingOverlay() {
-	return (
-		<Stack justify="center" align="center" className={ styles.loading }>
-			<Spinner />
-		</Stack>
-	);
-}
-
 interface UnavailableWidgetProps {
 	widgetTypeName: string;
 }
@@ -79,13 +30,13 @@ function UnavailableWidget( { widgetTypeName }: UnavailableWidgetProps ) {
 		<>
 			<Card.Header>
 				<span
-					className={ styles.widgetChromeHeaderIcon }
+					className={ styles[ 'widget-chrome-header-icon' ] }
 					aria-hidden="true"
 				>
 					<Icon icon={ plugins } />
 				</span>
 			</Card.Header>
-			<Card.Content className={ styles.widgetChromeContent }>
+			<Card.Content className={ styles[ 'widget-chrome-content' ] }>
 				<Stack
 					direction="column"
 					justify="center"
@@ -101,56 +52,27 @@ function UnavailableWidget( { widgetTypeName }: UnavailableWidgetProps ) {
 	);
 }
 
-interface HeaderProps {
-	titleId: string;
-	widgetType: WidgetType;
-}
-
-function Header( { titleId, widgetType }: HeaderProps ) {
-	if ( ! widgetType.title ) {
-		return null;
-	}
-
-	return (
-		<Card.Header>
-			<Stack direction="row" align="center" gap="sm">
-				{ widgetType.icon && (
-					<span
-						className={ styles.widgetChromeHeaderIcon }
-						aria-hidden="true"
-					>
-						<Icon icon={ widgetType.icon } />
-					</span>
-				) }
-				<Card.Title id={ titleId } render={ <h2 /> }>
-					{ widgetType.title }
-				</Card.Title>
-			</Stack>
-		</Card.Header>
-	);
-}
-
 export interface WidgetChromeProps {
 	widget: DashboardWidget< unknown >;
 	index: number;
 	/**
-	 * Lifted by the surrounding `@wordpress/grid` surface into a sibling
-	 * slot of the grid item; not rendered by `WidgetChrome` itself.
-	 * Living outside `Card.Root` is what keeps these controls interactive
-	 * while edit mode applies `inert` to the chrome.
+	 * Lifted by `@wordpress/grid` into a sibling slot outside `Card.Root`,
+	 * for full-bleed widgets with no in-card header to host the toolbar.
 	 */
 	actionableArea?: ReactNode;
+	/**
+	 * Toolbar rendered in the in-card header (framed and content-bleed).
+	 */
+	headerToolbar?: ReactNode;
 	className?: string;
 }
 
 /**
- * Per-instance wrapper. Owns the chrome around a widget instance: identity
- * context, header (title + icon), edit-mode `inert` attribute, and the
- * error/loading boundaries that keep neighbours mounted when one widget fails
- * or is still resolving.
+ * Dashboard chrome: wraps `WidgetFrame` in the grid tile's `Card.Root`, owning
+ * the missing and resolving states.
  */
 export const WidgetChrome = forwardRef< HTMLDivElement, WidgetChromeProps >(
-	function WidgetChrome( { widget, index, className }, ref ) {
+	function WidgetChrome( { widget, index, className, headerToolbar }, ref ) {
 		const { widgetTypes, isResolvingWidgetTypes, editMode } =
 			useDashboardInternalContext();
 		const widgetType = widgetTypes.find( ( t ) => t.name === widget.type );
@@ -172,12 +94,15 @@ export const WidgetChrome = forwardRef< HTMLDivElement, WidgetChromeProps >(
 						<Card.Root
 							render={ <section /> }
 							ref={ ref }
-							className={ clsx( styles.widgetChrome, className ) }
+							className={ clsx(
+								styles[ 'widget-chrome' ],
+								className
+							) }
 							aria-busy="true"
 							aria-label={ __( 'Loading' ) }
 						>
 							<Card.Content
-								className={ styles.widgetChromeContent }
+								className={ styles[ 'widget-chrome-content' ] }
 							>
 								<LoadingOverlay />
 							</Card.Content>
@@ -191,7 +116,10 @@ export const WidgetChrome = forwardRef< HTMLDivElement, WidgetChromeProps >(
 					<Card.Root
 						render={ <section /> }
 						ref={ ref }
-						className={ clsx( styles.widgetChrome, className ) }
+						className={ clsx(
+							styles[ 'widget-chrome' ],
+							className
+						) }
 						aria-label={ __( 'Missing widget' ) }
 					>
 						<UnavailableWidget widgetTypeName={ widget.type } />
@@ -200,54 +128,21 @@ export const WidgetChrome = forwardRef< HTMLDivElement, WidgetChromeProps >(
 			);
 		}
 
-		// `presentation` encodes two independent axes. `full-bleed` hides
-		// the header; both `full-bleed` and `content-bleed` let the body
-		// break out of the content padding.
-		const { presentation } = widgetType;
-		const isHeaderHidden = presentation === 'full-bleed';
-		const isBodyBleeding =
-			presentation === 'full-bleed' || presentation === 'content-bleed';
-		const header = <Header titleId={ titleId } widgetType={ widgetType } />;
-
-		const body = (
-			<WidgetErrorBoundary>
-				<Suspense fallback={ <LoadingOverlay /> }>
-					<WidgetRender widget={ widget } widgetType={ widgetType } />
-				</Suspense>
-			</WidgetErrorBoundary>
-		);
-
 		return (
 			<WidgetContextProvider value={ contextValue }>
 				<Card.Root
 					render={ <section /> }
 					ref={ ref }
-					className={ clsx( styles.widgetChrome, className ) }
+					className={ clsx( styles[ 'widget-chrome' ], className ) }
 					aria-labelledby={ widgetType.title ? titleId : undefined }
-					{ ...( editMode ? { inert: 'true' } : {} ) }
 				>
-					{ isHeaderHidden ? (
-						<VisuallyHidden>{ header }</VisuallyHidden>
-					) : (
-						header
-					) }
-
-					<Card.Content
-						className={ clsx(
-							styles.widgetChromeContent,
-							isBodyBleeding && styles.widgetChromeContentBleed
-						) }
-					>
-						{ isBodyBleeding ? (
-							<Card.FullBleed
-								className={ styles.widgetChromeBleedScroll }
-							>
-								{ body }
-							</Card.FullBleed>
-						) : (
-							body
-						) }
-					</Card.Content>
+					<WidgetFrame
+						widget={ widget }
+						widgetType={ widgetType }
+						titleId={ titleId }
+						editMode={ editMode }
+						headerToolbar={ headerToolbar }
+					/>
 				</Card.Root>
 			</WidgetContextProvider>
 		);

package/src/components/widget-frame/index.ts

@@ -0,0 +1,2 @@
+export { WidgetFrame, LoadingOverlay } from './widget-frame';
+export type { WidgetFrameProps } from './widget-frame';

package/src/components/widget-frame/widget-frame.module.css

@@ -0,0 +1,17 @@
+/* Scroll viewport that fills the tile height; min:0 bounds tall content. */
+.content {
+	flex: 1;
+	height: 100%;
+	overflow-y: auto;
+	min-width: 0;
+	min-height: 0;
+}
+
+/* Bleeding body reaches the card borders. Card exposes no padding-less section. */
+.bleed-content {
+	padding: 0;
+}
+
+.loading {
+	height: 100%;
+}