@wordpress/widget-dashboard 0.2.0 → 0.3.0

package/src/components/widget-settings/widget-settings-trigger.tsx

@@ -3,7 +3,7 @@
  */
 import { useCallback } from '@wordpress/element';
 import { __ } from '@wordpress/i18n';
-import { cog } from '@wordpress/icons';
+import { moreVertical } from '@wordpress/icons';
 // Dashboard is still experimental.
 // eslint-disable-next-line @wordpress/use-recommended-components
 import { IconButton } from '@wordpress/ui';
@@ -12,13 +12,13 @@ import type { WidgetType } from '@wordpress/widget-primitives';
 /**
  * Internal dependencies
  */
+import { useDashboardInternalContext } from '../../context/dashboard-context';
 import { useDashboardUIContext } from '../../context/ui-context';
-import { getAdminMenuInset } from './utils';
 import type { DashboardWidget } from '../../types';
 
 export interface WidgetSettingsTriggerProps {
 	/**
-	 * The instance whose settings drawer this gear opens.
+	 * The instance whose settings surface this control opens.
 	 */
 	widget: DashboardWidget< unknown >;
 
@@ -30,10 +30,12 @@ export interface WidgetSettingsTriggerProps {
 }
 
 /**
- * Per-instance gear that opens the shared settings drawer by writing the
+ * Per-instance control that toggles the shared settings surface by writing the
  * instance `uuid` to the UI context; the single `WidgetSettings` at the root
- * reacts to it. Returns `null` when the type declares no attributes, so chrome
- * can mount it unconditionally.
+ * reacts to it. Clicking the control of the instance whose settings surface is
+ * already open closes it. Returns `null` when no attribute needs that surface
+ * (none, or all already promoted to the prominent one), so chrome can mount it
+ * unconditionally.
  *
  * @param {WidgetSettingsTriggerProps} props Component props.
  */
@@ -41,56 +43,49 @@ export function WidgetSettingsTrigger( {
 	widget,
 	widgetType,
 }: WidgetSettingsTriggerProps ): React.ReactNode {
-	const {
-		setSettingsWidgetUuid,
-		setSettingsDrawerSide,
-		setSettingsDrawerInset,
-	} = useDashboardUIContext();
+	const { settingsWidgetUuid, setSettingsWidgetUuid } =
+		useDashboardUIContext();
+	const { cancel, flushAutoSave } = useDashboardInternalContext();
 
-	const open = useCallback(
-		( event: React.MouseEvent< HTMLElement > ) => {
-			// Open the drawer on the side away from the widget: compare the
-			// tile's center against the midpoint of the usable content area
-			// (which starts after the admin menu). Past it opens left.
-			const adminMenuInset = getAdminMenuInset();
-			// The gear sits in the grid slot, outside the card, so reach the
-			// tile via the grid item's data hook.
-			const tile = event.currentTarget.closest(
-				'[data-wp-grid-item-key]'
-			);
-			const rect = (
-				tile ?? event.currentTarget
-			).getBoundingClientRect();
-			const widgetCenter = rect.left + rect.width / 2;
-			const contentCenter = ( adminMenuInset + window.innerWidth ) / 2;
-			const side = widgetCenter > contentCenter ? 'left' : 'right';
+	const toggle = useCallback( () => {
+		// Re-clicking the open instance's control closes the settings surface,
+		// discarding staged edits like any other non-Save exit.
+		if ( settingsWidgetUuid === widget.uuid ) {
+			cancel();
+			setSettingsWidgetUuid( null );
+			return;
+		}
+		// Persist any pending prominent-surface edit before opening, so the
+		// settings surface's edits stay isolated and its Cancel discards only
+		// its own changes.
+		flushAutoSave();
+		setSettingsWidgetUuid( widget.uuid );
+	}, [
+		cancel,
+		flushAutoSave,
+		settingsWidgetUuid,
+		setSettingsWidgetUuid,
+		widget.uuid,
+	] );
 
-			setSettingsDrawerSide( side );
-			// A left drawer would otherwise slide over the fixed admin menu;
-			// offset it by the menu width so it lands clear of it.
-			setSettingsDrawerInset( side === 'left' ? adminMenuInset : 0 );
-			setSettingsWidgetUuid( widget.uuid );
-		},
-		[
-			setSettingsDrawerSide,
-			setSettingsDrawerInset,
-			setSettingsWidgetUuid,
-			widget.uuid,
-		]
+	// Surface the settings UI only when there are attributes not already
+	// promoted inline; if every attribute is high-relevance, a second
+	// surface would just repeat the prominent one.
+	const hasNonPromotedAttributes = widgetType.attributes?.some(
+		( attribute ) => attribute.relevance !== 'high'
 	);
-
-	if ( ! widgetType.attributes?.length ) {
+	if ( ! hasNonPromotedAttributes ) {
 		return null;
 	}
 
 	return (
 		<IconButton
-			icon={ cog }
+			icon={ moreVertical }
 			label={ __( 'Widget settings' ) }
 			variant="minimal"
 			tone="neutral"
 			size="compact"
-			onClick={ open }
+			onClick={ toggle }
 		/>
 	);
 }

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

@@ -22,13 +22,14 @@ type WidgetAttributes = Record< string, unknown >;
 /**
  * Side drawer that edits one instance's attributes, mounted once at the
  * dashboard root. It resolves the active instance from `settingsWidgetUuid`
- * in the UI context (set by the per-instance gear), renders the type's
- * declarative `attributes` through `DataForm`, and enters from the edge away
- * from the widget.
+ * in the UI context (set by the per-instance settings trigger), renders the
+ * type's declarative `attributes` through `DataForm`, and enters from the
+ * inline-end edge.
  *
  * Edits write to the staging layer, so they preview live behind the drawer
  * and are published on Save or reverted on any other exit. Available in
- * normal mode only; the gear is hidden while the layout is being edited.
+ * normal mode only; the settings entry point is hidden while the layout is
+ * being edited.
  */
 export function WidgetSettings(): React.ReactNode {
 	const {
@@ -39,12 +40,8 @@ export function WidgetSettings(): React.ReactNode {
 		cancel: cancelStaging,
 		hasUncommittedChanges,
 	} = useDashboardInternalContext();
-	const {
-		settingsWidgetUuid,
-		setSettingsWidgetUuid,
-		settingsDrawerSide,
-		settingsDrawerInset,
-	} = useDashboardUIContext();
+	const { settingsWidgetUuid, setSettingsWidgetUuid } =
+		useDashboardUIContext();
 
 	const open = settingsWidgetUuid !== null;
 
@@ -117,7 +114,7 @@ export function WidgetSettings(): React.ReactNode {
 	const handleOpenChange = useCallback(
 		( nextOpen: boolean ) => {
 			// Any path out of the drawer other than Save discards the
-			// staged edits, matching the layout-settings drawer.
+			// staged edits.
 			if ( ! nextOpen ) {
 				cancelStaging();
 				close();
@@ -126,17 +123,6 @@ export function WidgetSettings(): React.ReactNode {
 		[ cancelStaging, close ]
 	);
 
-	// For a left drawer, clear the fixed admin menu on the inline-start
-	// edge so the drawer lands beside it. The admin bar at the top is
-	// cleared in the CSS module.
-	const popupStyle = useMemo< React.CSSProperties >(
-		() =>
-			settingsDrawerSide === 'left' && settingsDrawerInset > 0
-				? { marginLeft: settingsDrawerInset }
-				: {},
-		[ settingsDrawerSide, settingsDrawerInset ]
-	);
-
 	const hasForm = !! widget && !! widgetType && fields.length > 0;
 
 	if ( ! hasForm ) {
@@ -152,15 +138,11 @@ export function WidgetSettings(): React.ReactNode {
 		<Drawer.Root
 			open={ open }
 			onOpenChange={ handleOpenChange }
-			swipeDirection={ settingsDrawerSide }
+			swipeDirection="right"
 			modal={ false }
 			disablePointerDismissal
 		>
-			<Drawer.Popup
-				size="medium"
-				className={ styles.popup }
-				style={ popupStyle }
-			>
+			<Drawer.Popup size="medium" className={ styles.popup }>
 				<Drawer.Header>
 					<Drawer.Title>{ title }</Drawer.Title>
 					<Drawer.CloseIcon />

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

@@ -1,12 +1,15 @@
-/*
- * Per-tile toolbar shell: anchored top-right (the grid item is the positioned
- * ancestor) with the shared padding and radius. Variants add the background.
- */
-.widgetToolbar {
-	position: absolute;
-	inset-block-start: var(--wpds-dimension-padding-sm);
-	inset-inline-end: var(--wpds-dimension-padding-sm);
-	z-index: 1;
+.widget-toolbar {
 	padding: var(--wpds-dimension-padding-xs);
-	border-radius: var(--wpds-border-radius-md);
+	background: var(--wpds-color-background-surface-neutral-strong);
+}
+
+.elevated {
+	--_wp-widget-dashboard-elevation-xs:
+		0 1px 1px rgba(0, 0, 0, 0.03),
+		0 1px 2px rgba(0, 0, 0, 0.02),
+		0 3px 3px rgba(0, 0, 0, 0.02),
+		0 4px 4px rgba(0, 0, 0, 0.01);
+
+	border: 1px solid var(--wpds-color-stroke-surface-neutral-weak);
+	box-shadow: var(--_wp-widget-dashboard-elevation-xs);
 }

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

@@ -15,30 +15,36 @@ import { Stack } from '@wordpress/ui';
 import styles from './widget-toolbar.module.css';
 
 export interface WidgetToolbarProps {
-	/** Toolbar controls, laid out in one row. */
+	/**
+	 * The active mode's controls.
+	 */
 	children: ReactNode;
 
-	/** Variant surface class (background, reveal). */
-	className?: string;
+	/**
+	 * Lift the toolbar with a shadow while customizing.
+	 */
+	editMode?: boolean;
 }
 
 /**
- * Shared shell for the per-tile action toolbars. Anchors to the tile's
- * top-right corner and lays controls out in the row the header also uses, so
- * a toolbar lines up with the title when they overlap.
+ * The per-tile toolbar chip holding the active mode's controls.
+ * Always visible; lifted with a shadow only while customizing.
  *
  * @param {WidgetToolbarProps} props Component props.
  */
 export function WidgetToolbar( {
 	children,
-	className,
+	editMode = false,
 }: WidgetToolbarProps ): React.ReactNode {
 	return (
 		<Stack
 			direction="row"
 			align="center"
 			gap="xs"
-			className={ clsx( styles.widgetToolbar, className ) }
+			className={ clsx(
+				styles[ 'widget-toolbar' ],
+				editMode && styles.elevated
+			) }
 		>
 			{ children }
 		</Stack>

package/src/components/widgets/widget-resize-handle.module.css

@@ -26,13 +26,13 @@
  * Larger box = hit target; small `::after` = visual only (still uses
  * logical borders so RTL needs no mirroring).
  */
-.handleCorner {
+.handle-corner {
 	width: var(--wpds-dimension-size-sm);
 	height: var(--wpds-dimension-size-sm);
 	cursor: nwse-resize;
 }
 
-.handleCorner::after {
+.handle-corner::after {
 	content: "";
 	position: absolute;
 	bottom: var(--widget-resize-handle-visual-inset);
@@ -54,13 +54,13 @@
 	transform-origin: 100% 100%;
 }
 
-[dir="rtl"] .handleCorner::after {
+[dir="rtl"] .handle-corner::after {
 	transform-origin: 0% 100%;
 }
 
-.handleCorner.resizing::after,
-.handleCorner:hover::after,
-.handleCorner:focus-visible::after {
+.handle-corner.resizing::after,
+.handle-corner:hover::after,
+.handle-corner:focus-visible::after {
 	transform: scale(var(--widget-resize-handle-hover-scale));
 	border-block-end:
 		var(--wpds-border-width-sm) solid
@@ -70,7 +70,7 @@
 		var(--wpds-color-foreground-interactive-brand-active);
 }
 
-.handleHorizontal {
+.handle-horizontal {
 	display: flex;
 	align-items: center;
 	justify-content: center;
@@ -82,7 +82,7 @@
 }
 
 @media not ( prefers-reduced-motion ) {
-	.handleCorner::after {
+	.handle-corner::after {
 		transition:
 			transform var(--wpds-motion-duration-xs)
 			var(--wpds-motion-easing-balanced),
@@ -92,7 +92,7 @@
 			var(--wpds-motion-easing-balanced);
 	}
 
-	.handleHorizontal::after {
+	.handle-horizontal::after {
 		transition:
 			transform var(--wpds-motion-duration-xs)
 			var(--wpds-motion-easing-balanced),
@@ -101,7 +101,7 @@
 	}
 }
 
-.handleHorizontal::after {
+.handle-horizontal::after {
 	content: "";
 	width: var(--wpds-border-width-sm);
 	height: var(--wpds-dimension-size-3xs);
@@ -110,26 +110,26 @@
 	transform-origin: 50% 100%;
 }
 
-.handleHorizontal.resizing::after,
-.handleHorizontal:hover::after,
-.handleHorizontal:focus-visible::after {
+.handle-horizontal.resizing::after,
+.handle-horizontal:hover::after,
+.handle-horizontal:focus-visible::after {
 	transform: scale(var(--widget-resize-handle-hover-scale));
 	background-color: var(--wpds-color-foreground-interactive-brand-active);
 }
 
 @media (forced-colors: active) {
-	.handleCorner::after,
-	.handleCorner.resizing::after,
-	.handleCorner:hover::after,
-	.handleCorner:focus-visible::after {
+	.handle-corner::after,
+	.handle-corner.resizing::after,
+	.handle-corner:hover::after,
+	.handle-corner:focus-visible::after {
 		border-block-end-color: Highlight;
 		border-inline-end-color: Highlight;
 	}
 
-	.handleHorizontal::after,
-	.handleHorizontal.resizing::after,
-	.handleHorizontal:hover::after,
-	.handleHorizontal:focus-visible::after {
+	.handle-horizontal::after,
+	.handle-horizontal.resizing::after,
+	.handle-horizontal:hover::after,
+	.handle-horizontal:focus-visible::after {
 		background-color: Highlight;
 	}
 }

package/src/components/widgets/widget-resize-handle.tsx

@@ -36,7 +36,7 @@ export const WidgetResizeHandle = forwardRef<
 				ref={ ref }
 				className={ clsx(
 					styles.handle,
-					styles.handleHorizontal,
+					styles[ 'handle-horizontal' ],
 					isResizing && styles.resizing
 				) }
 				{ ...listeners }
@@ -50,7 +50,7 @@ export const WidgetResizeHandle = forwardRef<
 			ref={ ref }
 			className={ clsx(
 				styles.handle,
-				styles.handleCorner,
+				styles[ 'handle-corner' ],
 				isResizing && styles.resizing
 			) }
 			{ ...listeners }

package/src/components/widgets/widgets.module.css

@@ -1,11 +1,14 @@
 .grid {
-	/* stylelint-disable-next-line property-no-unknown -- container queries for the dashboard grid surface */
 	container-type: inline-size;
 	container-name: widget-dashboard;
 	width: 100%;
 	/* Placeholder and drag-preview radii: match `.tile` and `@wordpress/ui` Card (`--wpds-border-radius-lg`). */
 	--wp-grid-placeholder-radius: var(--wpds-border-radius-lg);
 	--wp-grid-drag-preview-radius: var(--wpds-border-radius-lg);
+	/* Reserve top paint space so scroll containers do not clip tile focus rings. */
+	--wp-widget-dashboard-tile-focus-offset: 2px;
+	--wp-widget-dashboard-focus-ring-reserve: calc(var(--wpds-border-width-focus) + var(--wp-widget-dashboard-tile-focus-offset));
+	padding-block-start: var(--wp-widget-dashboard-focus-ring-reserve);
 }
 
 .tile {
@@ -14,16 +17,22 @@
 }
 
 /*
- * Edit-mode tiles stay at resting elevation (`xs`) on hover; only the
- * drag preview (`.drag-preview-frame` on `@wordpress/grid`) lifts to `md`.
+ * Edit-mode tiles keep their resting shadow on hover; only the drag preview
+ * (`.drag-preview-frame` on `@wordpress/grid`) uses a stronger shadow.
  */
-.tileEditMode {
-	box-shadow: var(--wpds-elevation-xs);
+.tile-edit-mode {
+	--_wp-widget-dashboard-elevation-xs:
+		0 1px 1px rgba(0, 0, 0, 0.03),
+		0 1px 2px rgba(0, 0, 0, 0.02),
+		0 3px 3px rgba(0, 0, 0, 0.02),
+		0 4px 4px rgba(0, 0, 0, 0.01);
+
+	box-shadow: var(--_wp-widget-dashboard-elevation-xs);
 }
 
-.tileEditMode:focus-visible {
+.tile-edit-mode: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);
 }
 
 /*
@@ -31,13 +40,13 @@
  * `height: 100%` keeps the inner `.tile` height: 100% chain alive
  * (without it, the wrapper auto-sizes and the cloned tile collapses
  * to content height). Drag elevation is owned by the grid
- * `.drag-preview-frame` (`md` while dragging); strip the cloned tile shadow so it
- * does not stack on the frame.
+ * `.drag-preview-frame`; strip the cloned tile shadow so it does not stack on
+ * the frame.
  */
-.dragPreview {
+.drag-preview {
 	height: 100%;
 }
 
-.dragPreview .tile {
+.drag-preview .tile {
 	box-shadow: none;
 }

package/src/components/widgets/widgets.tsx

@@ -21,9 +21,11 @@ import type { WidgetName } from '@wordpress/widget-primitives';
  */
 import { useDashboardInternalContext } from '../../context/dashboard-context';
 import { useDashboardContainerColumnCount } from '../../hooks/use-dashboard-container-column-count';
+import { WidgetAttributeControls } from '../widget-attribute-controls';
 import { WidgetChrome } from '../widget-chrome';
-import { WidgetSettingsToolbar } from '../widget-settings';
-import { WidgetLayoutToolbar } from './widget-layout-toolbar';
+import { WidgetHeader } from '../widget-header';
+import { WidgetLayoutControls } from '../widget-layout-controls';
+import { WidgetToolbar } from '../widget-toolbar';
 import { WidgetResizeHandle } from './widget-resize-handle';
 import styles from './widgets.module.css';
 import type {
@@ -132,37 +134,58 @@ export const Widgets = forwardRef< HTMLDivElement, WidgetsProps >(
 				( type ) => type.name === widget.type
 			);
 			const hasSettings = !! widgetType?.attributes?.length;
+			const isFullBleed = widgetType?.presentation === 'full-bleed';
 
-			// One slot, chosen by mode: layout toolbar while customizing,
-			// settings toolbar otherwise (undefined when nothing to configure).
-			let actionableArea: React.ReactNode;
+			// The active mode's controls: layout while customizing, the
+			// attribute controls (high-relevance fields on the prominent
+			// surface, plus a settings entry point when needed)
+			// otherwise.
+			let controls: React.ReactNode;
 			if ( editMode ) {
-				actionableArea = <WidgetLayoutToolbar widget={ widget } />;
+				controls = <WidgetLayoutControls widget={ widget } />;
 			} else if ( hasSettings && widgetType ) {
-				actionableArea = (
-					<WidgetSettingsToolbar
+				controls = (
+					<WidgetAttributeControls
 						widget={ widget }
 						widgetType={ widgetType }
 					/>
 				);
 			}
 
+			const toolbar = controls ? (
+				<WidgetToolbar editMode={ editMode }>
+					{ controls }
+				</WidgetToolbar>
+			) : undefined;
+
+			// Normal mode hosts the toolbar in the in-card header, beside the
+			// identity. Customize controls and full-bleed widgets need it in
+			// the grid's actionable-area slot instead: the slot sits outside
+			// the draggable card, so the controls stay clickable (in-card they
+			// would be captured by the drag listeners).
+			const inSlot = editMode || isFullBleed;
+			const actionableArea =
+				inSlot && toolbar ? (
+					<WidgetHeader overlay>{ toolbar }</WidgetHeader>
+				) : undefined;
+
 			return (
 				<WidgetChrome
 					key={ widget.uuid }
 					widget={ widget }
 					index={ index }
 					className={ clsx( styles.tile, {
-						[ styles.tileEditMode ]: editMode,
+						[ styles[ 'tile-edit-mode' ] ]: editMode,
 					} ) }
 					actionableArea={ actionableArea }
+					headerToolbar={ ! inSlot ? toolbar : undefined }
 				/>
 			);
 		} );
 
 		const renderDragPreview = useCallback(
 			( { children: clone }: DragPreviewRenderProps ) => (
-				<div className={ styles.dragPreview }>{ clone }</div>
+				<div className={ styles[ 'drag-preview' ] }>{ clone }</div>
 			),
 			[]
 		);