@wordpress/widget-dashboard 0.1.0

package/src/components/no-widgets-state/no-widgets-state.tsx

@@ -0,0 +1,56 @@
+/**
+ * External dependencies
+ */
+import type { ReactNode } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+import { home } from '@wordpress/icons';
+import { EmptyState, Stack } from '@wordpress/ui';
+
+/**
+ * Internal dependencies
+ */
+import { useDashboardInternalContext } from '../../context/dashboard-context';
+import styles from './no-widgets-state.module.css';
+
+export interface NoWidgetsStateProps {
+	children?: ReactNode;
+}
+
+/**
+ * Empty-state placeholder shown while the dashboard `layout` has no widgets.
+ * Pair it with `WidgetDashboard.Widgets` so it stands in for the grid until
+ * widgets are added. Falls back to a built-in placeholder; pass `children` to
+ * override.
+ *
+ * @param {NoWidgetsStateProps} props Component props.
+ */
+export function NoWidgetsState( {
+	children,
+}: NoWidgetsStateProps ): React.ReactNode {
+	const { layout } = useDashboardInternalContext();
+	if ( layout.length > 0 ) {
+		return null;
+	}
+
+	return (
+		<Stack justify="center" align="center" className={ styles.root }>
+			{ children ?? (
+				<EmptyState.Root>
+					<EmptyState.Icon icon={ home } />
+					<EmptyState.Title>
+						{ __( 'Your dashboard is empty' ) }
+					</EmptyState.Title>
+					<EmptyState.Description>
+						{ __(
+							'Add widgets to start customizing your dashboard.'
+						) }
+					</EmptyState.Description>
+				</EmptyState.Root>
+			) }
+		</Stack>
+	);
+}

package/src/components/reset-confirmation/index.ts

@@ -0,0 +1 @@
+export { ResetConfirmation } from './reset-confirmation';

package/src/components/reset-confirmation/reset-confirmation.tsx

@@ -0,0 +1,44 @@
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+// eslint-disable-next-line @wordpress/use-recommended-components
+import { AlertDialog } from '@wordpress/ui';
+
+/**
+ * Internal dependencies
+ */
+import { useDashboardInternalContext } from '../../context/dashboard-context';
+import { useDashboardUIContext } from '../../context/ui-context';
+
+/**
+ * Confirmation prompt for resetting the dashboard to its default layout,
+ * mounted by the engine and shown while `resetDialogOpen` is set in the
+ * shared UI context. Confirming runs `onLayoutReset` and leaves customize
+ * mode.
+ */
+export function ResetConfirmation(): React.ReactNode {
+	const { onLayoutReset, onEditChange } = useDashboardInternalContext();
+	const { resetDialogOpen, setResetDialogOpen } = useDashboardUIContext();
+
+	return (
+		<AlertDialog.Root
+			open={ resetDialogOpen }
+			onOpenChange={ setResetDialogOpen }
+			onConfirm={ async () => {
+				await onLayoutReset?.();
+				onEditChange?.( false );
+				setResetDialogOpen( false );
+			} }
+		>
+			<AlertDialog.Popup
+				intent="irreversible"
+				title={ __( 'Reset dashboard to default?' ) }
+				description={ __(
+					'All customizations will be permanently lost.'
+				) }
+				confirmButtonText={ __( 'Reset' ) }
+			/>
+		</AlertDialog.Root>
+	);
+}

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

@@ -0,0 +1 @@
+export { WidgetChrome } from './widget-chrome';

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

@@ -0,0 +1,87 @@
+.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: var(--wpds-border-width-focus) solid var(--wpds-color-stroke-focus);
+	outline-offset: 2px;
+}
+
+.widgetChromeHeaderIcon {
+	display: inline-flex;
+	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.
+ */
+.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

@@ -0,0 +1,255 @@
+/**
+ * External dependencies
+ */
+import clsx from 'clsx';
+import type { ReactNode } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { Spinner } from '@wordpress/components';
+import {
+	Component,
+	Suspense,
+	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';
+
+/**
+ * Internal dependencies
+ */
+import { useDashboardInternalContext } from '../../context/dashboard-context';
+import { WidgetContextProvider } from '../../context/widget-context';
+import { WidgetRender } from '../widget-render';
+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;
+}
+
+function UnavailableWidget( { widgetTypeName }: UnavailableWidgetProps ) {
+	return (
+		<>
+			<Card.Header>
+				<span
+					className={ styles.widgetChromeHeaderIcon }
+					aria-hidden="true"
+				>
+					<Icon icon={ plugins } />
+				</span>
+			</Card.Header>
+			<Card.Content className={ styles.widgetChromeContent }>
+				<Stack
+					direction="column"
+					justify="center"
+					align="center"
+					gap="md"
+					className={ styles.unavailable }
+				>
+					<Text>{ __( 'Widget is no longer available.' ) }</Text>
+					<Text render={ <code /> }>{ widgetTypeName }</Text>
+				</Stack>
+			</Card.Content>
+		</>
+	);
+}
+
+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.
+	 */
+	actionableArea?: 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.
+ */
+export const WidgetChrome = forwardRef< HTMLDivElement, WidgetChromeProps >(
+	function WidgetChrome( { widget, index, className }, ref ) {
+		const { widgetTypes, isResolvingWidgetTypes, editMode } =
+			useDashboardInternalContext();
+		const widgetType = widgetTypes.find( ( t ) => t.name === widget.type );
+		const titleId = useId();
+
+		const contextValue = useMemo(
+			() => ( {
+				uuid: widget.uuid,
+				name: widget.type,
+				index,
+			} ),
+			[ widget.uuid, widget.type, index ]
+		);
+
+		if ( ! widgetType ) {
+			if ( isResolvingWidgetTypes ) {
+				return (
+					<WidgetContextProvider value={ contextValue }>
+						<Card.Root
+							render={ <section /> }
+							ref={ ref }
+							className={ clsx( styles.widgetChrome, className ) }
+							aria-busy="true"
+							aria-label={ __( 'Loading' ) }
+						>
+							<Card.Content
+								className={ styles.widgetChromeContent }
+							>
+								<LoadingOverlay />
+							</Card.Content>
+						</Card.Root>
+					</WidgetContextProvider>
+				);
+			}
+
+			return (
+				<WidgetContextProvider value={ contextValue }>
+					<Card.Root
+						render={ <section /> }
+						ref={ ref }
+						className={ clsx( styles.widgetChrome, className ) }
+						aria-label={ __( 'Missing widget' ) }
+					>
+						<UnavailableWidget widgetTypeName={ widget.type } />
+					</Card.Root>
+				</WidgetContextProvider>
+			);
+		}
+
+		// `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
+					render={ <section /> }
+					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>
+				</Card.Root>
+			</WidgetContextProvider>
+		);
+	}
+);

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

@@ -0,0 +1 @@
+export { WidgetInserter } from './widget-inserter';

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

@@ -0,0 +1,70 @@
+/**
+ * WordPress dependencies
+ */
+import { useCallback } from '@wordpress/element';
+import { __ } from '@wordpress/i18n';
+// eslint-disable-next-line @wordpress/use-recommended-components
+import { Dialog } from '@wordpress/ui';
+import type { WidgetType } from '@wordpress/widget-primitives';
+
+/**
+ * Internal dependencies
+ */
+import { useDashboardInternalContext } from '../../context/dashboard-context';
+import { useDashboardUIContext } from '../../context/ui-context';
+import { createDashboardWidget } from '../../utils/create-dashboard-widget';
+import { WidgetPicker } from '../widget-picker';
+
+/**
+ * Modal widget inserter, mounted by the engine and shown while `inserterOpen`
+ * is set in the shared UI context. Selecting widgets appends them to the
+ * layout and closes the dialog.
+ */
+export function WidgetInserter() {
+	const { layout, onLayoutChange } = useDashboardInternalContext();
+	const { inserterOpen, setInserterOpen } = useDashboardUIContext();
+
+	const insertWidgets = useCallback(
+		( widgetTypes: WidgetType[] ) => {
+			if ( widgetTypes.length > 0 ) {
+				const newWidgets = widgetTypes.map( ( widgetType ) =>
+					createDashboardWidget( widgetType )
+				);
+				onLayoutChange( [ ...layout, ...newWidgets ] );
+			}
+
+			setInserterOpen( false );
+		},
+		[ layout, onLayoutChange, setInserterOpen ]
+	);
+
+	if ( ! inserterOpen ) {
+		return null;
+	}
+
+	return (
+		<Dialog.Root open={ inserterOpen } onOpenChange={ setInserterOpen }>
+			<Dialog.Popup
+				size="full"
+				portal={
+					<Dialog.Portal
+						style={
+							{
+								'--wp-ui-dialog-z-index': 99999,
+							} as React.CSSProperties
+						}
+					/>
+				}
+			>
+				<Dialog.Header>
+					<Dialog.Title>{ __( 'Add widget' ) }</Dialog.Title>
+					<Dialog.CloseIcon />
+				</Dialog.Header>
+
+				<Dialog.Content>
+					<WidgetPicker onSelect={ insertWidgets } />
+				</Dialog.Content>
+			</Dialog.Popup>
+		</Dialog.Root>
+	);
+}

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

@@ -0,0 +1 @@
+export { WidgetPicker } from './widget-picker';

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

@@ -0,0 +1,11 @@
+.preview {
+	width: 125%;
+	height: 125%;
+	overflow: hidden;
+	padding: 0;
+	transform: scale(0.8);
+	transform-origin: top left;
+	/* Let clicks and hovers reach the picker tile, not links inside the preview. */
+	pointer-events: none;
+	user-select: none;
+}

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

@@ -0,0 +1,137 @@
+/**
+ * WordPress dependencies
+ */
+import { DataViewsPicker, filterSortAndPaginate } from '@wordpress/dataviews';
+import type { Field, View } from '@wordpress/dataviews';
+import { Suspense, useMemo, useState } from '@wordpress/element';
+import { __ } from '@wordpress/i18n';
+import type { WidgetType } from '@wordpress/widget-primitives';
+
+/**
+ * Internal dependencies
+ */
+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';
+
+const DEFAULT_VIEW: View = {
+	type: 'pickerGrid',
+	page: 1,
+	search: '',
+	mediaField: 'preview',
+	titleField: 'title',
+};
+
+const getItemId = ( item: WidgetType ) => item.name;
+
+function WidgetPreview( { item }: { item: WidgetType } ) {
+	const exampleWidget = useMemo(
+		() => createDashboardWidget( item, item.example?.attributes ),
+		[ item ]
+	);
+
+	return (
+		<div className={ styles.preview } { ...{ inert: '' } }>
+			<Suspense fallback={ null }>
+				<WidgetRender widget={ exampleWidget } widgetType={ item } />
+			</Suspense>
+		</div>
+	);
+}
+
+const fields: Field< WidgetType >[] = [
+	{
+		id: 'title',
+		type: 'text',
+		label: __( 'Title' ),
+		filterBy: false,
+	},
+	{
+		id: 'preview',
+		type: 'media',
+		render: WidgetPreview,
+	},
+	{
+		id: 'name',
+		type: 'text',
+		enableGlobalSearch: true,
+		enableHiding: false,
+		enableSorting: false,
+		filterBy: false,
+		getValue: ( { item } ) =>
+			`${ item.name.replace( /[\/,\-_]/g, ' ' ) } ${ item.title }`,
+	},
+];
+
+interface WidgetPickerProps {
+	/**
+	 * Called with the widget types selected by the user. The picker keeps
+	 * its own selection state; consumers receive the resolved list when
+	 * the "Select" action fires.
+	 */
+	onSelect: ( widgetTypes: WidgetType[] ) => void;
+
+	/**
+	 * Accessible label for the picker's item list.
+	 *
+	 * @default __( 'Widget list' )
+	 */
+	itemListLabel?: string;
+}
+
+/**
+ * DataViews-driven widget type picker. Lists `widgetTypes` from the dashboard
+ * context as a grid of live previews, supports search via `name`/`title`, and
+ * exposes a single "Select" action with bulk support so users can insert one
+ * or several widgets at once.
+ *
+ * @param {WidgetPickerProps} props Component props.
+ */
+export function WidgetPicker( {
+	onSelect,
+	itemListLabel = __( 'Widget list' ),
+}: WidgetPickerProps ) {
+	const { widgetTypes: registeredTypes } = useDashboardInternalContext();
+	const [ selection, setSelection ] = useState< string[] >( [] );
+	const [ view, setView ] = useState< View >( DEFAULT_VIEW );
+
+	const { data: widgetTypes } = filterSortAndPaginate(
+		registeredTypes,
+		view,
+		fields
+	);
+
+	const actions = useMemo(
+		() => [
+			{
+				id: 'select',
+				label: __( 'Select' ),
+				isPrimary: true,
+				supportsBulk: true,
+				callback: ( items: WidgetType[] ) => onSelect( items ),
+			},
+		],
+		[ onSelect ]
+	);
+
+	return (
+		<DataViewsPicker
+			data={ widgetTypes }
+			fields={ fields }
+			view={ view }
+			actions={ actions }
+			defaultLayouts={ { pickerGrid: {} } }
+			onChangeView={ setView }
+			isLoading={ false }
+			paginationInfo={ {
+				totalItems: widgetTypes.length,
+				totalPages: 1,
+			} }
+			selection={ selection }
+			onChangeSelection={ setSelection }
+			getItemId={ getItemId }
+			itemListLabel={ itemListLabel }
+		/>
+	);
+}

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

@@ -0,0 +1 @@
+export { WidgetRender } from './widget-render';