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

package/src/components/widget-header/widget-header-infotip.tsx

@@ -0,0 +1,82 @@
+/**
+ * WordPress dependencies
+ */
+import { createInterpolateElement } from '@wordpress/element';
+import { __ } from '@wordpress/i18n';
+import { info } from '@wordpress/icons';
+// eslint-disable-next-line @wordpress/use-recommended-components
+import { Icon, Link, Popover, Stack, VisuallyHidden } from '@wordpress/ui';
+
+/**
+ * Internal dependencies
+ */
+import styles from './widget-header.module.css';
+
+export interface WidgetInfotipProps {
+	/**
+	 * Help content to display; may carry `<em>`/`<strong>`.
+	 */
+	content: string;
+
+	/**
+	 * Links rendered after the content.
+	 */
+	links?: {
+		label: string;
+		href: string;
+	}[];
+}
+
+/**
+ * Header infotip: a click-open popover holding the widget type's help note.
+ *
+ * @param {WidgetInfotipProps} props Component props.
+ */
+export function WidgetInfotip( {
+	content,
+	links,
+}: WidgetInfotipProps ): React.ReactNode {
+	return (
+		<Popover.Root modal="trap-focus">
+			<Popover.Trigger
+				aria-label={ __( 'More information' ) }
+				className={ styles.help }
+			>
+				<Icon icon={ info } size={ 20 } />
+			</Popover.Trigger>
+
+			<Popover.Popup
+				className={ styles.popoverPopup }
+				positioner={ <Popover.Positioner side="top" align="start" /> }
+			>
+				<Popover.Arrow />
+				<VisuallyHidden render={ <Popover.Title /> }>
+					{ __( 'More information' ) }
+				</VisuallyHidden>
+
+				<Stack direction="column" align="start" gap="sm">
+					<Popover.Description>
+						{ createInterpolateElement( content, {
+							em: <em />,
+							strong: <strong />,
+						} ) }
+					</Popover.Description>
+
+					{ links && links.length > 0 && (
+						<Stack direction="row" align="start" gap="sm">
+							{ links.map( ( link ) => (
+								<Link
+									key={ link.href }
+									href={ link.href }
+									className={ styles.link }
+								>
+									{ link.label }
+								</Link>
+							) ) }
+						</Stack>
+					) }
+				</Stack>
+			</Popover.Popup>
+		</Popover.Root>
+	);
+}

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

@@ -0,0 +1,76 @@
+/**
+ * Tile header row: identity leads, toolbar trails, on one line.
+ */
+.widgetHeader {
+	display: flex;
+	align-items: center;
+	gap: var(--wpds-dimension-gap-sm);
+}
+
+/**
+ * Identity and toolbar share one box so they stay aligned.
+ */
+.identity,
+.toolbar {
+	display: flex;
+	align-items: center;
+	height: var(--wpds-dimension-size-lg);
+}
+
+/**
+ * Shrink a long title instead of pushing the toolbar out.
+ */
+.identity {
+	min-width: 0;
+}
+
+.icon {
+	display: inline-flex;
+	color: var(--wpds-color-foreground-content-neutral);
+}
+
+.popoverPopup {
+	max-width: 300px;
+}
+
+/**
+ * Infotip trigger: a bare icon button beside the title.
+ */
+.help {
+	display: inline-flex;
+	align-items: center;
+	padding: 0;
+	border: 0;
+	background: none;
+	color: var(--wpds-color-foreground-content-neutral-weak);
+	cursor: var(--wpds-cursor-control);
+}
+
+/**
+ * Divide adjacent links in the infotip.
+ */
+.link + .link {
+	border-inline-start: var(--wpds-border-width-xs) solid var(--wpds-color-stroke-surface-neutral);
+	padding-inline-start: var(--wpds-dimension-gap-sm);
+}
+
+.toolbar {
+	margin-inline-start: auto;
+}
+
+/**
+ * Floats over the tile, click-through except the toolbar; re-declares the card
+ * padding var (outside Card.Root).
+ */
+.overlay {
+	position: absolute;
+	inset-block-start: 0;
+	inset-inline: 0;
+	z-index: 1;
+	pointer-events: none;
+	--wp-ui-card-padding: var(--wpds-dimension-padding-2xl);
+}
+
+.overlay .toolbar {
+	pointer-events: auto;
+}

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

@@ -0,0 +1,101 @@
+/**
+ * External dependencies
+ */
+import clsx from 'clsx';
+import type { ReactNode } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { Card, Icon, Stack } from '@wordpress/ui';
+import type { WidgetType } from '@wordpress/widget-primitives';
+
+/**
+ * Internal dependencies
+ */
+import { WidgetInfotip } from './widget-header-infotip';
+import styles from './widget-header.module.css';
+
+export interface WidgetHeaderProps {
+	/**
+	 * Widget type, source of the icon, title, and help note shown as
+	 * identity.
+	 */
+	widgetType?: WidgetType;
+
+	/**
+	 * Id linking the title to the tile's labelled region.
+	 */
+	titleId?: string;
+
+	/**
+	 * Render the icon + title cluster on the leading edge.
+	 */
+	showIdentity?: boolean;
+
+	/**
+	 * Float over the tile instead of sitting in the card flow.
+	 */
+	overlay?: boolean;
+
+	/**
+	 * Inert the identity while customizing, so it does not capture interaction.
+	 */
+	editMode?: boolean;
+
+	/**
+	 * Toolbar placed on the trailing edge.
+	 */
+	children?: ReactNode;
+}
+
+/**
+ * Tile header row: identity (icon + title) and a toolbar on one line. Rendered
+ * in the card flow, or as an `overlay` in the grid slot for full-bleed widgets
+ * that have no in-card header.
+ *
+ * @param {WidgetHeaderProps} props Component props.
+ */
+export function WidgetHeader( {
+	widgetType,
+	titleId,
+	showIdentity = false,
+	overlay = false,
+	editMode = false,
+	children,
+}: WidgetHeaderProps ): React.ReactNode {
+	return (
+		<Card.Header
+			className={ clsx( styles.widgetHeader, overlay && styles.overlay ) }
+		>
+			{ showIdentity && widgetType?.title && (
+				<Stack
+					direction="row"
+					align="center"
+					gap="sm"
+					className={ styles.identity }
+					{ ...( editMode ? { inert: 'true' } : {} ) }
+				>
+					{ widgetType.icon && (
+						<span className={ styles.icon } aria-hidden="true">
+							<Icon icon={ widgetType.icon } />
+						</span>
+					) }
+
+					<Card.Title id={ titleId } render={ <h2 /> }>
+						{ widgetType.title }
+					</Card.Title>
+
+					{ widgetType.help && (
+						<WidgetInfotip
+							content={ widgetType.help.content }
+							links={ widgetType.help.links }
+						/>
+					) }
+				</Stack>
+			) }
+
+			{ children && <div className={ styles.toolbar }>{ children }</div> }
+		</Card.Header>
+	);
+}

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

@@ -0,0 +1,2 @@
+export { WidgetLayoutControls } from './widget-layout-controls';
+export type { WidgetLayoutControlsProps } from './widget-layout-controls';

package/src/components/{widgets/widget-layout-toolbar.tsx → widget-layout-controls/widget-layout-controls.tsx}

@@ -4,7 +4,6 @@
 import { privateApis as componentsPrivateApis } from '@wordpress/components';
 import { __ } from '@wordpress/i18n';
 import { moreVertical, trash } from '@wordpress/icons';
-// Dashboard is still experimental.
 // eslint-disable-next-line @wordpress/use-recommended-components
 import { IconButton } from '@wordpress/ui';
 
@@ -13,8 +12,6 @@ import { IconButton } from '@wordpress/ui';
  */
 import { unlock } from '../../lock-unlock';
 import { useDashboardInternalContext } from '../../context/dashboard-context';
-import { WidgetToolbar } from '../widget-toolbar';
-import styles from './widget-layout-toolbar.module.css';
 import type { DashboardWidget, GridTilePlacement } from '../../types';
 
 const { Menu } = unlock( componentsPrivateApis );
@@ -24,21 +21,21 @@ type NamedGridWidth = Exclude<
 	number
 >;
 
-export interface WidgetLayoutToolbarProps {
-	/** The instance this toolbar manages within the layout. */
+export interface WidgetLayoutControlsProps {
+	/**
+	 * The instance these controls manage within the layout.
+	 */
 	widget: DashboardWidget< unknown >;
 }
 
 /**
- * Customize-mode per-tile toolbar: a width menu and removal, editing the
- * widget's place in the layout. Lives in the grid's `actionableArea` slot, so
- * it stays interactive while the card is `inert`.
+ * Customize-mode controls: width menu and removal.
  *
- * @param {WidgetLayoutToolbarProps} props Component props.
+ * @param {WidgetLayoutControlsProps} props Component props.
  */
-export function WidgetLayoutToolbar( {
+export function WidgetLayoutControls( {
 	widget,
-}: WidgetLayoutToolbarProps ): React.ReactNode {
+}: WidgetLayoutControlsProps ): React.ReactNode {
 	const { layout, onLayoutChange } = useDashboardInternalContext();
 	const width = widget.placement?.width;
 
@@ -70,7 +67,7 @@ export function WidgetLayoutToolbar( {
 	};
 
 	return (
-		<WidgetToolbar className={ styles.widgetLayoutToolbar }>
+		<>
 			<Menu>
 				<Menu.TriggerButton
 					render={
@@ -83,6 +80,7 @@ export function WidgetLayoutToolbar( {
 						/>
 					}
 				/>
+
 				<Menu.Popover>
 					<Menu.Group>
 						<Menu.GroupLabel>{ __( 'Width' ) }</Menu.GroupLabel>
@@ -105,6 +103,7 @@ export function WidgetLayoutToolbar( {
 					</Menu.Group>
 				</Menu.Popover>
 			</Menu>
+
 			<IconButton
 				icon={ trash }
 				label={ __( 'Remove' ) }
@@ -113,6 +112,6 @@ export function WidgetLayoutToolbar( {
 				tone="neutral"
 				onClick={ onRemove }
 			/>
-		</WidgetToolbar>
+		</>
 	);
 }

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

@@ -3,7 +3,7 @@
  */
 import { DataViewsPicker, filterSortAndPaginate } from '@wordpress/dataviews';
 import type { Field, View } from '@wordpress/dataviews';
-import { Suspense, useMemo, useState } from '@wordpress/element';
+import { useMemo, useState } from '@wordpress/element';
 import { __ } from '@wordpress/i18n';
 import type { WidgetType } from '@wordpress/widget-primitives';
 
@@ -12,8 +12,7 @@ import type { WidgetType } from '@wordpress/widget-primitives';
  */
 import { useDashboardInternalContext } from '../../context/dashboard-context';
 import { createDashboardWidget } from '../../utils/create-dashboard-widget';
-import { WidgetRender } from '../widget-render';
-import styles from './widget-picker.module.css';
+import { WidgetPreviewChrome } from '../widget-preview-chrome';
 
 const DEFAULT_VIEW: View = {
 	type: 'pickerGrid',
@@ -21,6 +20,8 @@ const DEFAULT_VIEW: View = {
 	search: '',
 	mediaField: 'preview',
 	titleField: 'title',
+	// Larger default tile than the built-in 230.
+	layout: { previewSize: 290 },
 };
 
 const getItemId = ( item: WidgetType ) => item.name;
@@ -31,13 +32,7 @@ function WidgetPreview( { item }: { item: WidgetType } ) {
 		[ item ]
 	);
 
-	return (
-		<div className={ styles.preview } { ...{ inert: '' } }>
-			<Suspense fallback={ null }>
-				<WidgetRender widget={ exampleWidget } widgetType={ item } />
-			</Suspense>
-		</div>
-	);
+	return <WidgetPreviewChrome widget={ exampleWidget } widgetType={ item } />;
 }
 
 const fields: Field< WidgetType >[] = [

package/src/components/widget-preview-chrome/index.ts

@@ -0,0 +1,2 @@
+export { WidgetPreviewChrome } from './widget-preview-chrome';
+export type { WidgetPreviewChromeProps } from './widget-preview-chrome';

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

@@ -0,0 +1,22 @@
+/* Fills the tile and clips the render; inert + click-transparent so the tile owns interaction. */
+.viewport {
+	position: absolute;
+	inset: 0;
+	overflow: hidden;
+	border-radius: var(--wpds-border-radius-md);
+	background: var(--wpds-color-background-surface-neutral-weak);
+	pointer-events: none;
+	user-select: none;
+}
+
+/* Grid stretches the card to fill the tile regardless of the card's own height. */
+.canvas {
+	display: grid;
+	width: 100%;
+	height: 100%;
+}
+
+.card {
+	height: 100%;
+	min-height: 0;
+}

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

@@ -0,0 +1,65 @@
+/**
+ * WordPress dependencies
+ */
+import { useId, useMemo } from '@wordpress/element';
+import { Card } from '@wordpress/ui';
+import type { WidgetType } from '@wordpress/widget-primitives';
+
+/**
+ * Internal dependencies
+ */
+import { WidgetContextProvider } from '../../context/widget-context';
+import { WidgetFrame } from '../widget-frame';
+import styles from './widget-preview-chrome.module.css';
+import type { DashboardWidget } from '../../types';
+
+export interface WidgetPreviewChromeProps {
+	widget: DashboardWidget< unknown >;
+	widgetType: WidgetType;
+	index?: number;
+}
+
+/**
+ * Catalog host-chrome: the faithful `WidgetFrame` in a viewport that scales the
+ * card to fill the tile at any zoom; inert so the picker owns selection.
+ *
+ * @param {WidgetPreviewChromeProps} props Component props.
+ */
+export function WidgetPreviewChrome( {
+	widget,
+	widgetType,
+	index = 0,
+}: WidgetPreviewChromeProps ) {
+	const titleId = useId();
+
+	const contextValue = useMemo(
+		() => ( {
+			uuid: widget.uuid,
+			name: widget.type,
+			index,
+		} ),
+		[ widget.uuid, widget.type, index ]
+	);
+
+	return (
+		<WidgetContextProvider value={ contextValue }>
+			<div className={ styles.viewport } { ...{ inert: '' } }>
+				<div className={ styles.canvas }>
+					<Card.Root
+						render={ <section /> }
+						className={ styles.card }
+						aria-labelledby={
+							widgetType.title ? titleId : undefined
+						}
+					>
+						<WidgetFrame
+							widget={ widget }
+							widgetType={ widgetType }
+							titleId={ titleId }
+						/>
+					</Card.Root>
+				</div>
+			</div>
+		</WidgetContextProvider>
+	);
+}

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

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

package/src/components/widget-settings/utils/index.ts

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

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,8 +12,8 @@ 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 {
@@ -30,10 +30,11 @@ export interface WidgetSettingsTriggerProps {
 }
 
 /**
- * Per-instance gear that opens the shared settings drawer by writing the
+ * Per-instance gear that toggles the shared settings drawer 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 gear of the instance whose drawer is already
+ * open closes it. Returns `null` when no attribute needs the drawer (none, or
+ * all already promoted inline), so chrome can mount it unconditionally.
  *
  * @param {WidgetSettingsTriggerProps} props Component props.
  */
@@ -41,56 +42,48 @@ 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 gear closes the drawer, discarding
+		// staged edits like any other non-Save exit.
+		if ( settingsWidgetUuid === widget.uuid ) {
+			cancel();
+			setSettingsWidgetUuid( null );
+			return;
+		}
+		// Persist any pending inline edit before opening, so the drawer's edits
+		// stay isolated and its Cancel discards only the drawer's 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 drawer only when there are attributes not already promoted
+	// inline; if every attribute is high-relevance, the drawer would just
+	// repeat the toolbar.
+	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

@@ -23,8 +23,8 @@ 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.
+ * 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
@@ -39,12 +39,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 +113,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 +122,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 +137,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 />