@wordpress/widget-dashboard 0.2.0 → 0.3.1-next.v.202607070741.0

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 inline, plus the
+ * settings trigger that opens the full settings drawer 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,26 +1,5 @@
-.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) {
+/* Outline the whole tile when the body holds keyboard focus; an inner ring is easy to miss. */
+.widgetChrome:has(:focus-visible) {
 	outline: var(--wpds-border-width-focus) solid var(--wpds-color-stroke-focus);
 	outline-offset: 2px;
 }
@@ -30,58 +9,14 @@
 	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.
- */
+/* Fill the tile so placeholder states center in the full height. */
 .widgetChromeContent {
 	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;
 }
@@ -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 );
@@ -200,23 +122,6 @@ 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
@@ -224,30 +129,14 @@ export const WidgetChrome = forwardRef< HTMLDivElement, WidgetChromeProps >(
 					ref={ ref }
 					className={ clsx( styles.widgetChrome, 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. */
+.bleedContent {
+	padding: 0;
+}
+
+.loading {
+	height: 100%;
+}

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

@@ -0,0 +1,138 @@
+/**
+ * External dependencies
+ */
+import clsx from 'clsx';
+import type { ReactNode } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { Spinner } from '@wordpress/components';
+import { Component, Suspense } from '@wordpress/element';
+import { __ } from '@wordpress/i18n';
+// eslint-disable-next-line @wordpress/use-recommended-components
+import { Card, Notice, Stack, VisuallyHidden } from '@wordpress/ui';
+import type { WidgetType } from '@wordpress/widget-primitives';
+
+/**
+ * Internal dependencies
+ */
+import { WidgetHeader } from '../widget-header';
+import { WidgetRender } from '../widget-render';
+import styles from './widget-frame.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;
+	}
+}
+
+/* Centered spinner for resolving and Suspense waits. */
+export function LoadingOverlay() {
+	return (
+		<Stack justify="center" align="center" className={ styles.loading }>
+			<Spinner />
+		</Stack>
+	);
+}
+
+export interface WidgetFrameProps {
+	widget: DashboardWidget< unknown >;
+	widgetType: WidgetType;
+	titleId: string;
+
+	/**
+	 * Inert the body and identity while customizing.
+	 */
+	editMode?: boolean;
+
+	/**
+	 * Toolbar shown beside the identity in the in-card header.
+	 */
+	headerToolbar?: ReactNode;
+}
+
+/**
+ * Shared framing: `presentation` into header + content, with the error/loading
+ * boundaries. Hosts supply the `Card.Root` and their own concerns.
+ *
+ * @param {WidgetFrameProps} props Component props.
+ */
+export function WidgetFrame( {
+	widget,
+	widgetType,
+	titleId,
+	editMode = false,
+	headerToolbar,
+}: WidgetFrameProps ) {
+	// full-bleed hides the header; full-bleed and content-bleed bleed the body.
+	const { presentation } = widgetType;
+	const isHeaderHidden = presentation === 'full-bleed';
+	const isBodyBleeding =
+		presentation === 'full-bleed' || presentation === 'content-bleed';
+
+	const body = (
+		<WidgetErrorBoundary>
+			<Suspense fallback={ <LoadingOverlay /> }>
+				<WidgetRender widget={ widget } widgetType={ widgetType } />
+			</Suspense>
+		</WidgetErrorBoundary>
+	);
+
+	return (
+		<>
+			{ ! isHeaderHidden && (
+				<WidgetHeader
+					showIdentity
+					widgetType={ widgetType }
+					titleId={ titleId }
+					editMode={ editMode }
+				>
+					{ headerToolbar }
+				</WidgetHeader>
+			) }
+
+			<Card.Content
+				className={ clsx(
+					styles.content,
+					isBodyBleeding && styles.bleedContent
+				) }
+				{ ...( editMode ? { inert: 'true' } : {} ) }
+			>
+				{ isHeaderHidden && widgetType.title && (
+					<VisuallyHidden render={ <h2 id={ titleId } /> }>
+						{ widgetType.title }
+					</VisuallyHidden>
+				) }
+				{ body }
+			</Card.Content>
+		</>
+	);
+}

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

@@ -0,0 +1,2 @@
+export { WidgetHeader } from './widget-header';
+export type { WidgetHeaderProps } from './widget-header';