Dashboard: per-instance widget settings drawer

routes/dashboard/widget-dashboard/components/widget-chrome/widget-chrome.module.css

@@ -2,6 +2,17 @@
 	height: 100%;
 }
 
+/*
+ * 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: var(--wpds-border-width-focus) solid var(--wpds-color-stroke-focus-brand);
+	outline-offset: 2px;
+}
+
 .widgetChromeHeaderIcon {
 	display: inline-flex;
 	color: var(--wpds-color-fg-content-neutral);

routes/dashboard/widget-dashboard/components/widget-chrome/widget-chrome.tsx

@@ -90,7 +90,6 @@ function Header( { titleId, widgetType }: HeaderProps ) {
 						<WCIcon icon={ widgetType.icon } />
 					</span>
 				) }
-
 				<Card.Title id={ titleId } render={ <h3 /> }>
 					{ widgetType.title }
 				</Card.Title>
@@ -145,6 +144,7 @@ export const WidgetChrome = forwardRef< HTMLDivElement, WidgetChromeProps >(
 		const isBodyBleeding =
 			presentation === 'full-bleed' || presentation === 'content-bleed';
 		const header = <Header titleId={ titleId } widgetType={ widgetType } />;
+
 		const body = (
 			<WidgetErrorBoundary>
 				<Suspense fallback={ <LoadingOverlay /> }>

routes/dashboard/widget-dashboard/components/widget-settings/index.ts

@@ -0,0 +1,4 @@
+export { WidgetSettings } from './widget-settings';
+export { getWidgetSettingsTitle } from './utils';
+export { WidgetSettingsToolbar } from './widget-settings-toolbar';
+export type { WidgetSettingsToolbarProps } from './widget-settings-toolbar';

routes/dashboard/widget-dashboard/components/widget-settings/utils/get-admin-menu-inset.ts

@@ -0,0 +1,30 @@
+// cspell:ignore adminmenuback
+const ADMIN_MENU_ID = 'adminmenuback';
+
+/**
+ * Width, in pixels, taken up by the WordPress admin menu
+ * (`#adminmenuback`) on the inline-start edge of the viewport.
+ *
+ * The settings drawer portals to the document body and anchors to a
+ * viewport edge, so a left-anchored drawer would slide over the fixed
+ * admin menu. Offsetting the drawer by this value keeps the menu
+ * uncovered (and reachable) instead of raising the drawer's z-index over
+ * it.
+ *
+ * Defensive: returns `0` when the element is absent (outside wp-admin, or
+ * in tests/Storybook), so the drawer just anchors to the viewport edge.
+ *
+ * @return {number} The admin menu's right edge in px, or `0`.
+ */
+export function getAdminMenuInset(): number {
+	if ( typeof document === 'undefined' ) {
+		return 0;
+	}
+
+	const adminMenu = document.getElementById( ADMIN_MENU_ID );
+	if ( ! adminMenu ) {
+		return 0;
+	}
+
+	return Math.max( 0, adminMenu.getBoundingClientRect().right );
+}

routes/dashboard/widget-dashboard/components/widget-settings/utils/get-widget-settings.ts

@@ -0,0 +1,26 @@
+/**
+ * WordPress dependencies
+ */
+import { sprintf, __ } from '@wordpress/i18n';
+
+/**
+ * Internal dependencies
+ */
+import type { WidgetType } from '../../../../widget-types/types';
+
+/**
+ * Localized "<Widget> settings" label, falling back to a generic title
+ * when the type declares none.
+ *
+ * @param {WidgetType} widgetType Type backing the open instance.
+ * @return {string} The drawer/trigger title.
+ */
+export function getWidgetSettingsTitle( widgetType?: WidgetType ): string {
+	return widgetType?.title
+		? sprintf(
+				/* translators: %s: Widget title. */
+				__( '%s settings' ),
+				widgetType.title
+		  )
+		: __( 'Widget settings' );
+}

routes/dashboard/widget-dashboard/components/widget-settings/utils/index.ts

@@ -0,0 +1,2 @@
+export { getAdminMenuInset } from './get-admin-menu-inset';
+export { getWidgetSettingsTitle } from './get-widget-settings';

routes/dashboard/widget-dashboard/components/widget-settings/widget-settings-toolbar.module.css

@@ -0,0 +1,25 @@
+/* Translucent surface so the gear stays legible over any widget background. */
+.widgetSettingsToolbar {
+	background: color-mix(in srgb, var(--wpds-color-bg-surface-neutral) 40%, transparent);
+	opacity: 0;
+	pointer-events: none;
+}
+
+/*
+ * Revealed on tile hover or focus. Hidden with opacity, not display, so the
+ * gear stays in the tab order and `:focus-within` surfaces it for keyboard
+ * users. The matched ancestor is the grid item, shared by the slot and card.
+ */
+:global([data-wp-grid-item-key]):hover .widgetSettingsToolbar,
+:global([data-wp-grid-item-key]):focus-within .widgetSettingsToolbar {
+	opacity: 1;
+	pointer-events: auto;
+}
+
+@media not ( prefers-reduced-motion ) {
+	.widgetSettingsToolbar {
+		transition:
+			opacity var(--wpds-motion-duration-sm)
+			var(--wpds-motion-easing-subtle);
+	}
+}

routes/dashboard/widget-dashboard/components/widget-settings/widget-settings-toolbar.tsx

@@ -0,0 +1,43 @@
+/**
+ * Internal dependencies
+ */
+import { WidgetToolbar } from '../widget-toolbar';
+import { WidgetSettingsTrigger } from './widget-settings-trigger';
+import styles from './widget-settings-toolbar.module.css';
+import type { DashboardWidget, WidgetType } from '../../types';
+
+export interface WidgetSettingsToolbarProps {
+	/** The instance whose settings this toolbar configures. */
+	widget: DashboardWidget< unknown >;
+
+	/** The instance's widget type, for the trigger label and guard. */
+	widgetType: WidgetType;
+}
+
+/**
+ * Normal-mode per-tile toolbar: the gear that opens the settings drawer.
+ * Lives in the grid's `actionableArea` slot, so it shows for every
+ * `presentation`. Returns `null` when the type has no attributes.
+ *
+ * @param {WidgetSettingsToolbarProps} props            Component props.
+ * @param {DashboardWidget}            props.widget     Instance to edit.
+ * @param {WidgetType}                 props.widgetType Type backing it.
+ * @return {React.ReactNode} The settings toolbar, or `null`.
+ */
+export function WidgetSettingsToolbar( {
+	widget,
+	widgetType,
+}: WidgetSettingsToolbarProps ): React.ReactNode {
+	if ( ! widgetType.attributes?.length ) {
+		return null;
+	}
+
+	return (
+		<WidgetToolbar className={ styles.widgetSettingsToolbar }>
+			<WidgetSettingsTrigger
+				widget={ widget }
+				widgetType={ widgetType }
+			/>
+		</WidgetToolbar>
+	);
+}

routes/dashboard/widget-dashboard/components/widget-settings/widget-settings-trigger.tsx

@@ -0,0 +1,100 @@
+/**
+ * WordPress dependencies
+ */
+import { useCallback } from '@wordpress/element';
+import { __ } from '@wordpress/i18n';
+import { cog } from '@wordpress/icons';
+// Dashboard is still experimental.
+// eslint-disable-next-line @wordpress/use-recommended-components
+import { IconButton } from '@wordpress/ui';
+
+/**
+ * Internal dependencies
+ */
+import { useDashboardUIContext } from '../../context/ui-context';
+import { getAdminMenuInset } from './utils';
+import type { DashboardWidget, WidgetType } from '../../types';
+
+export interface WidgetSettingsTriggerProps {
+	/**
+	 * The instance whose settings drawer this gear opens.
+	 */
+	widget: DashboardWidget< unknown >;
+
+	/**
+	 * The instance's widget type, used for the accessible label and the
+	 * attributes guard.
+	 */
+	widgetType: WidgetType;
+}
+
+/**
+ * Per-instance gear that opens the shared settings drawer for its widget
+ * by writing the instance `uuid` to the dashboard UI context. The single
+ * `WidgetSettings` drawer at the root reacts to that change.
+ *
+ * Returns `null` when the type declares no attributes, so chrome can mount
+ * it unconditionally.
+ *
+ * @param {WidgetSettingsTriggerProps} props            Component props.
+ * @param {DashboardWidget}            props.widget     Instance to edit.
+ * @param {WidgetType}                 props.widgetType Type backing it.
+ * @return {React.ReactNode} The gear button, or `null`.
+ */
+export function WidgetSettingsTrigger( {
+	widget,
+	widgetType,
+}: WidgetSettingsTriggerProps ): React.ReactNode {
+	const {
+		setSettingsWidgetUuid,
+		setSettingsDrawerSide,
+		setSettingsDrawerInset,
+	} = useDashboardUIContext();
+
+	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';
+
+			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,
+		]
+	);
+
+	if ( ! widgetType.attributes?.length ) {
+		return null;
+	}
+
+	return (
+		<IconButton
+			icon={ cog }
+			label={ __( 'Widget settings' ) }
+			variant="minimal"
+			tone="neutral"
+			size="compact"
+			onClick={ open }
+		/>
+	);
+}

routes/dashboard/widget-dashboard/components/widget-settings/widget-settings.module.css

@@ -0,0 +1,8 @@
+/*
+ * Clear the WP Admin admin bar. Its height varies (32/46px) and it is absent
+ * in some contexts (e.g. the site editor), so use the WP Admin token and
+ * default to 0.
+ */
+.popup {
+	margin-block-start: var(--wp-admin--admin-bar--height, 0);
+}