@wordpress/widget-dashboard 0.1.1-next.v.202606191442.0

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

@@ -0,0 +1,58 @@
+/**
+ * WordPress dependencies
+ */
+import { useCallback } from '@wordpress/element';
+import { WidgetRender as WidgetRenderPrimitive } from '@wordpress/widget-primitives';
+import type { WidgetType } from '@wordpress/widget-primitives';
+
+/**
+ * Internal dependencies
+ */
+import { useDashboardInternalContext } from '../../context/dashboard-context';
+import type { DashboardWidget } from '../../types';
+
+interface WidgetRenderProps {
+	widget: DashboardWidget< unknown >;
+	widgetType: WidgetType;
+}
+
+/**
+ * Adapter around the host-agnostic `WidgetRender` primitive. Bridges the
+ * dashboard context (`resolveWidgetModule`, layout state) and turns
+ * layout-level attribute updates into the per-instance `setAttributes`
+ * callback the render contract expects.
+ *
+ * @param {WidgetRenderProps} props Component props.
+ */
+export function WidgetRender( { widget, widgetType }: WidgetRenderProps ) {
+	const { layout, onLayoutChange, resolveWidgetModule } =
+		useDashboardInternalContext();
+
+	const setAttributes = useCallback(
+		( next: Partial< unknown > ) => {
+			onLayoutChange(
+				layout.map( ( w ) =>
+					w.uuid === widget.uuid
+						? {
+								...w,
+								attributes: {
+									...( w.attributes as object ),
+									...( next as object ),
+								},
+						  }
+						: w
+				)
+			);
+		},
+		[ widget.uuid, layout, onLayoutChange ]
+	);
+
+	return (
+		<WidgetRenderPrimitive
+			widgetType={ widgetType }
+			attributes={ widget.attributes }
+			setAttributes={ setAttributes }
+			resolveWidgetModule={ resolveWidgetModule }
+		/>
+	);
+}

package/src/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';

package/src/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 );
+}

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

@@ -0,0 +1,22 @@
+/**
+ * WordPress dependencies
+ */
+import { sprintf, __ } from '@wordpress/i18n';
+import type { WidgetType } from '@wordpress/widget-primitives';
+
+/**
+ * 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' );
+}

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

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

package/src/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-background-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);
+	}
+}

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

@@ -0,0 +1,45 @@
+/**
+ * WordPress dependencies
+ */
+import type { WidgetType } from '@wordpress/widget-primitives';
+
+/**
+ * Internal dependencies
+ */
+import { WidgetToolbar } from '../widget-toolbar';
+import { WidgetSettingsTrigger } from './widget-settings-trigger';
+import styles from './widget-settings-toolbar.module.css';
+import type { DashboardWidget } 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.
+ */
+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>
+	);
+}

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

@@ -0,0 +1,96 @@
+/**
+ * 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';
+import type { WidgetType } from '@wordpress/widget-primitives';
+
+/**
+ * Internal dependencies
+ */
+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.
+	 */
+	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 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.
+ *
+ * @param {WidgetSettingsTriggerProps} props Component props.
+ */
+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 }
+		/>
+	);
+}

package/src/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);
+}

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

@@ -0,0 +1,200 @@
+/**
+ * WordPress dependencies
+ */
+import { DataForm } from '@wordpress/dataviews';
+import type { Field, Form } from '@wordpress/dataviews';
+import { useCallback, useEffect, useMemo, useState } from '@wordpress/element';
+import { __ } from '@wordpress/i18n';
+// Dashboard is still experimental.
+// eslint-disable-next-line @wordpress/use-recommended-components
+import { Button, Drawer } from '@wordpress/ui';
+
+/**
+ * Internal dependencies
+ */
+import { useDashboardInternalContext } from '../../context/dashboard-context';
+import { useDashboardUIContext } from '../../context/ui-context';
+import { getWidgetSettingsTitle } from './utils';
+import styles from './widget-settings.module.css';
+
+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.
+ *
+ * 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.
+ */
+export function WidgetSettings(): React.ReactNode {
+	const {
+		layout,
+		onLayoutChange,
+		widgetTypes,
+		commit,
+		cancel: cancelStaging,
+		hasUncommittedChanges,
+	} = useDashboardInternalContext();
+	const {
+		settingsWidgetUuid,
+		setSettingsWidgetUuid,
+		settingsDrawerSide,
+		settingsDrawerInset,
+	} = useDashboardUIContext();
+
+	const open = settingsWidgetUuid !== null;
+
+	// Keep the last opened instance resolved while the drawer animates
+	// closed so its form and title don't blank out mid-transition. While
+	// open the live `settingsWidgetUuid` wins, so opening shows no stale
+	// frame.
+	const [ lastWidgetUuid, setLastWidgetUuid ] = useState< string | null >(
+		settingsWidgetUuid
+	);
+	useEffect( () => {
+		if ( settingsWidgetUuid ) {
+			setLastWidgetUuid( settingsWidgetUuid );
+		}
+	}, [ settingsWidgetUuid ] );
+
+	const activeUuid = settingsWidgetUuid ?? lastWidgetUuid;
+	const widget = activeUuid
+		? layout.find( ( instance ) => instance.uuid === activeUuid )
+		: undefined;
+	const widgetType = widget
+		? widgetTypes.find( ( type ) => type.name === widget.type )
+		: undefined;
+
+	const fields = useMemo< Field< WidgetAttributes >[] >(
+		() => ( widgetType?.attributes ?? [] ) as Field< WidgetAttributes >[],
+		[ widgetType?.attributes ]
+	);
+
+	const form = useMemo< Form >(
+		() => ( {
+			layout: { type: 'regular', labelPosition: 'top' },
+			fields: fields.map( ( field ) => field.id ),
+		} ),
+		[ fields ]
+	);
+
+	const handleChange = useCallback(
+		( edits: Record< string, unknown > ) => {
+			if ( ! widget ) {
+				return;
+			}
+			onLayoutChange(
+				layout.map( ( instance ) =>
+					instance.uuid === widget.uuid
+						? {
+								...instance,
+								attributes: {
+									...( instance.attributes as object ),
+									...edits,
+								},
+						  }
+						: instance
+				)
+			);
+		},
+		[ layout, onLayoutChange, widget ]
+	);
+
+	const close = useCallback(
+		() => setSettingsWidgetUuid( null ),
+		[ setSettingsWidgetUuid ]
+	);
+
+	const handleSave = useCallback( () => {
+		commit();
+		close();
+	}, [ commit, close ] );
+
+	const handleOpenChange = useCallback(
+		( nextOpen: boolean ) => {
+			// Any path out of the drawer other than Save discards the
+			// staged edits, matching the layout-settings drawer.
+			if ( ! nextOpen ) {
+				cancelStaging();
+				close();
+			}
+		},
+		[ 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 ) {
+		return null;
+	}
+
+	const title = getWidgetSettingsTitle( widgetType );
+	const data = ( widget?.attributes ??
+		widgetType?.example?.attributes ??
+		{} ) as WidgetAttributes;
+
+	return (
+		<Drawer.Root
+			open={ open }
+			onOpenChange={ handleOpenChange }
+			swipeDirection={ settingsDrawerSide }
+			modal={ false }
+			disablePointerDismissal
+		>
+			<Drawer.Popup
+				size="medium"
+				className={ styles.popup }
+				style={ popupStyle }
+			>
+				<Drawer.Header>
+					<Drawer.Title>{ title }</Drawer.Title>
+					<Drawer.CloseIcon />
+				</Drawer.Header>
+
+				<Drawer.Content>
+					<DataForm< WidgetAttributes >
+						data={ data }
+						fields={ fields }
+						form={ form }
+						onChange={ handleChange }
+					/>
+				</Drawer.Content>
+
+				<Drawer.Footer>
+					<Button
+						variant="minimal"
+						tone="brand"
+						size="compact"
+						onClick={ () => handleOpenChange( false ) }
+					>
+						{ __( 'Cancel' ) }
+					</Button>
+					<Button
+						variant="solid"
+						tone="brand"
+						size="compact"
+						onClick={ handleSave }
+						disabled={ ! hasUncommittedChanges }
+					>
+						{ __( 'Save' ) }
+					</Button>
+				</Drawer.Footer>
+			</Drawer.Popup>
+		</Drawer.Root>
+	);
+}

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

@@ -0,0 +1,2 @@
+export { WidgetToolbar } from './widget-toolbar';
+export type { WidgetToolbarProps } from './widget-toolbar';

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

@@ -0,0 +1,12 @@
+/*
+ * 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;
+	padding: var(--wpds-dimension-padding-xs);
+	border-radius: var(--wpds-border-radius-md);
+}

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

@@ -0,0 +1,46 @@
+/**
+ * External dependencies
+ */
+import clsx from 'clsx';
+import type { ReactNode } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { Stack } from '@wordpress/ui';
+
+/**
+ * Internal dependencies
+ */
+import styles from './widget-toolbar.module.css';
+
+export interface WidgetToolbarProps {
+	/** Toolbar controls, laid out in one row. */
+	children: ReactNode;
+
+	/** Variant surface class (background, reveal). */
+	className?: string;
+}
+
+/**
+ * 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.
+ *
+ * @param {WidgetToolbarProps} props Component props.
+ */
+export function WidgetToolbar( {
+	children,
+	className,
+}: WidgetToolbarProps ): React.ReactNode {
+	return (
+		<Stack
+			direction="row"
+			align="center"
+			gap="xs"
+			className={ clsx( styles.widgetToolbar, className ) }
+		>
+			{ children }
+		</Stack>
+	);
+}

package/src/components/widgets/index.ts

@@ -0,0 +1 @@
+export { Widgets } from './widgets';

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

@@ -0,0 +1,6 @@
+/* Solid surface: shown for the whole customize session, not on hover. */
+.widgetLayoutToolbar {
+	background: var(--wpds-color-background-surface-neutral-strong);
+	border: 1px solid var(--wpds-color-stroke-surface-neutral-weak);
+	box-shadow: var(--wpds-elevation-xs);
+}

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

@@ -0,0 +1,118 @@
+/**
+ * WordPress dependencies
+ */
+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';
+
+/**
+ * Internal dependencies
+ */
+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 );
+
+type NamedGridWidth = Exclude<
+	NonNullable< GridTilePlacement[ 'width' ] >,
+	number
+>;
+
+export interface WidgetLayoutToolbarProps {
+	/** The instance this toolbar manages 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`.
+ *
+ * @param {WidgetLayoutToolbarProps} props Component props.
+ */
+export function WidgetLayoutToolbar( {
+	widget,
+}: WidgetLayoutToolbarProps ): React.ReactNode {
+	const { layout, onLayoutChange } = useDashboardInternalContext();
+	const width = widget.placement?.width;
+
+	const updateWidth = ( nextWidth: GridTilePlacement[ 'width' ] ) => {
+		const nextLayout = layout.map( ( currentWidget ) =>
+			currentWidget.uuid === widget.uuid
+				? {
+						...currentWidget,
+						placement: {
+							...currentWidget.placement,
+							width: nextWidth,
+						},
+				  }
+				: currentWidget
+		);
+		onLayoutChange( nextLayout );
+	};
+
+	const onNamedWidthChange = ( nextWidth: NamedGridWidth ) => {
+		updateWidth( nextWidth );
+	};
+
+	const onRemove = () => {
+		onLayoutChange(
+			layout.filter(
+				( currentWidget ) => currentWidget.uuid !== widget.uuid
+			)
+		);
+	};
+
+	return (
+		<WidgetToolbar className={ styles.widgetLayoutToolbar }>
+			<Menu>
+				<Menu.TriggerButton
+					render={
+						<IconButton
+							icon={ moreVertical }
+							label={ __( 'Widget options' ) }
+							size="compact"
+							variant="minimal"
+							tone="neutral"
+						/>
+					}
+				/>
+				<Menu.Popover>
+					<Menu.Group>
+						<Menu.GroupLabel>{ __( 'Width' ) }</Menu.GroupLabel>
+						<Menu.Item
+							disabled={ width === 'fill' }
+							onClick={ () => onNamedWidthChange( 'fill' ) }
+						>
+							<Menu.ItemLabel>
+								{ __( 'Use available width' ) }
+							</Menu.ItemLabel>
+						</Menu.Item>
+						<Menu.Item
+							disabled={ width === 'full' }
+							onClick={ () => onNamedWidthChange( 'full' ) }
+						>
+							<Menu.ItemLabel>
+								{ __( 'Make full width' ) }
+							</Menu.ItemLabel>
+						</Menu.Item>
+					</Menu.Group>
+				</Menu.Popover>
+			</Menu>
+			<IconButton
+				icon={ trash }
+				label={ __( 'Remove' ) }
+				size="compact"
+				variant="minimal"
+				tone="neutral"
+				onClick={ onRemove }
+			/>
+		</WidgetToolbar>
+	);
+}