@wordpress/widget-dashboard 0.2.0 → 0.3.0

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[ 'bleed-content' ]
+				) }
+				{ ...( 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';

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[ 'popover-popup' ] }
+				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,59 @@
+/* Tile header row: identity leads, toolbar trails. */
+.widget-header {
+	display: flex;
+	align-items: center;
+	gap: var(--wpds-dimension-gap-sm);
+}
+
+.identity,
+.toolbar {
+	display: flex;
+	align-items: center;
+	height: var(--wpds-dimension-size-lg);
+}
+
+.identity {
+	min-width: 0;
+}
+
+.icon {
+	display: inline-flex;
+	color: var(--wpds-color-foreground-content-neutral);
+}
+
+.popover-popup {
+	max-width: 300px;
+}
+
+.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);
+}
+
+.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; re-declares card padding 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,104 @@
+/**
+ * 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[ 'widget-header' ],
+				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';