@wordpress/widget-dashboard 0.1.0

package/src/components/widgets/widget-resize-handle.module.css

@@ -0,0 +1,135 @@
+.handle {
+	position: absolute;
+	bottom: 0;
+	inset-inline-end: 0;
+	z-index: 1;
+	box-sizing: border-box;
+	padding: 0;
+	background: transparent;
+	/* Nudge painted affordance away from tile chrome; hit target stays flush. */
+	--widget-resize-handle-visual-inset: var(--wpds-dimension-padding-xs);
+	--widget-resize-handle-hover-scale: 1.18;
+}
+
+.handle:focus-visible {
+	outline: var(--wpds-border-width-focus) solid var(--wpds-color-stroke-focus);
+	/* Offset the ring by an amount equal to its own width. */
+	outline-offset: var(--wpds-border-width-focus);
+	border-radius: var(--wpds-border-radius-sm);
+}
+
+.resizing {
+	opacity: 0.72;
+}
+
+/*
+ * Larger box = hit target; small `::after` = visual only (still uses
+ * logical borders so RTL needs no mirroring).
+ */
+.handleCorner {
+	width: var(--wpds-dimension-size-sm);
+	height: var(--wpds-dimension-size-sm);
+	cursor: nwse-resize;
+}
+
+.handleCorner::after {
+	content: "";
+	position: absolute;
+	bottom: var(--widget-resize-handle-visual-inset);
+	inset-inline-end: var(--widget-resize-handle-visual-inset);
+	width: var(--wpds-dimension-size-4xs);
+	height: var(--wpds-dimension-size-4xs);
+	box-sizing: border-box;
+	border-block-end:
+		var(--wpds-border-width-sm) solid
+		var(--wpds-color-foreground-interactive-brand);
+	border-inline-end:
+		var(--wpds-border-width-sm) solid
+		var(--wpds-color-foreground-interactive-brand);
+	border-block-start: none;
+	border-inline-start: none;
+	/* Elbow only: matches tile scale; arm ends stay square. */
+	border-end-end-radius: var(--wpds-border-radius-md);
+	transform: scale(1);
+	transform-origin: 100% 100%;
+}
+
+[dir="rtl"] .handleCorner::after {
+	transform-origin: 0% 100%;
+}
+
+.handleCorner.resizing::after,
+.handleCorner:hover::after,
+.handleCorner:focus-visible::after {
+	transform: scale(var(--widget-resize-handle-hover-scale));
+	border-block-end:
+		var(--wpds-border-width-sm) solid
+		var(--wpds-color-foreground-interactive-brand-active);
+	border-inline-end:
+		var(--wpds-border-width-sm) solid
+		var(--wpds-color-foreground-interactive-brand-active);
+}
+
+.handleHorizontal {
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	width: var(--wpds-dimension-size-sm);
+	height: var(--wpds-dimension-size-lg);
+	padding-inline-end: var(--widget-resize-handle-visual-inset);
+	cursor: ew-resize;
+	border: none;
+}
+
+@media not ( prefers-reduced-motion ) {
+	.handleCorner::after {
+		transition:
+			transform var(--wpds-motion-duration-xs)
+			var(--wpds-motion-easing-balanced),
+			border-block-end-color var(--wpds-motion-duration-xs)
+			var(--wpds-motion-easing-balanced),
+			border-inline-end-color var(--wpds-motion-duration-xs)
+			var(--wpds-motion-easing-balanced);
+	}
+
+	.handleHorizontal::after {
+		transition:
+			transform var(--wpds-motion-duration-xs)
+			var(--wpds-motion-easing-balanced),
+			background-color var(--wpds-motion-duration-xs)
+			var(--wpds-motion-easing-balanced);
+	}
+}
+
+.handleHorizontal::after {
+	content: "";
+	width: var(--wpds-border-width-sm);
+	height: var(--wpds-dimension-size-3xs);
+	background-color: var(--wpds-color-foreground-interactive-brand);
+	transform: scale(1);
+	transform-origin: 50% 100%;
+}
+
+.handleHorizontal.resizing::after,
+.handleHorizontal:hover::after,
+.handleHorizontal:focus-visible::after {
+	transform: scale(var(--widget-resize-handle-hover-scale));
+	background-color: var(--wpds-color-foreground-interactive-brand-active);
+}
+
+@media (forced-colors: active) {
+	.handleCorner::after,
+	.handleCorner.resizing::after,
+	.handleCorner:hover::after,
+	.handleCorner:focus-visible::after {
+		border-block-end-color: Highlight;
+		border-inline-end-color: Highlight;
+	}
+
+	.handleHorizontal::after,
+	.handleHorizontal.resizing::after,
+	.handleHorizontal:hover::after,
+	.handleHorizontal:focus-visible::after {
+		background-color: Highlight;
+	}
+}

package/src/components/widgets/widget-resize-handle.tsx

@@ -0,0 +1,60 @@
+/**
+ * External dependencies
+ */
+import clsx from 'clsx';
+
+/**
+ * WordPress dependencies
+ */
+import { forwardRef } from '@wordpress/element';
+import type { ResizeHandleRenderProps } from '@wordpress/grid';
+
+/**
+ * Internal dependencies
+ */
+import styles from './widget-resize-handle.module.css';
+
+type WidgetResizeHandleProps = Omit< ResizeHandleRenderProps, 'ref' >;
+
+/**
+ * Rounded L-shaped resize affordance for the widget dashboard. Passed to
+ * `DashboardGrid` via `renderResizeHandle` so the grid keeps gesture wiring.
+ *
+ * Uses `forwardRef` because the grid attaches dnd-kit's merged node ref via
+ * the JSX `ref` attribute, not as a regular prop.
+ */
+export const WidgetResizeHandle = forwardRef<
+	HTMLDivElement,
+	WidgetResizeHandleProps
+>( function WidgetResizeHandle(
+	{ listeners, attributes, verticalResizable, isResizing },
+	ref
+) {
+	if ( ! verticalResizable ) {
+		return (
+			<div
+				ref={ ref }
+				className={ clsx(
+					styles.handle,
+					styles.handleHorizontal,
+					isResizing && styles.resizing
+				) }
+				{ ...listeners }
+				{ ...attributes }
+			></div>
+		);
+	}
+
+	return (
+		<div
+			ref={ ref }
+			className={ clsx(
+				styles.handle,
+				styles.handleCorner,
+				isResizing && styles.resizing
+			) }
+			{ ...listeners }
+			{ ...attributes }
+		></div>
+	);
+} );

package/src/components/widgets/widgets.module.css

@@ -0,0 +1,43 @@
+.grid {
+	/* stylelint-disable-next-line property-no-unknown -- container queries for the dashboard grid surface */
+	container-type: inline-size;
+	container-name: widget-dashboard;
+	width: 100%;
+	/* Placeholder and drag-preview radii: match `.tile` and `@wordpress/ui` Card (`--wpds-border-radius-lg`). */
+	--wp-grid-placeholder-radius: var(--wpds-border-radius-lg);
+	--wp-grid-drag-preview-radius: var(--wpds-border-radius-lg);
+}
+
+.tile {
+	height: 100%;
+	border-radius: var(--wpds-border-radius-lg);
+}
+
+/*
+ * Edit-mode tiles stay at resting elevation (`xs`) on hover; only the
+ * drag preview (`.drag-preview-frame` on `@wordpress/grid`) lifts to `md`.
+ */
+.tileEditMode {
+	box-shadow: var(--wpds-elevation-xs);
+}
+
+.tileEditMode:focus-visible {
+	outline: var(--wpds-border-width-focus) solid var(--wpds-color-stroke-focus);
+	outline-offset: 2px;
+}
+
+/*
+ * Wrapper applied through `renderDragPreview` on @wordpress/grid.
+ * `height: 100%` keeps the inner `.tile` height: 100% chain alive
+ * (without it, the wrapper auto-sizes and the cloned tile collapses
+ * to content height). Drag elevation is owned by the grid
+ * `.drag-preview-frame` (`md` while dragging); strip the cloned tile shadow so it
+ * does not stack on the frame.
+ */
+.dragPreview {
+	height: 100%;
+}
+
+.dragPreview .tile {
+	box-shadow: none;
+}

package/src/components/widgets/widgets.tsx

@@ -0,0 +1,208 @@
+/**
+ * External dependencies
+ */
+import clsx from 'clsx';
+
+/**
+ * WordPress dependencies
+ */
+import { forwardRef, useCallback, useMemo } from '@wordpress/element';
+import { DashboardGrid, DashboardLanes } from '@wordpress/grid';
+import type {
+	DashboardGridLayoutItem,
+	DashboardLanesLayoutItem,
+	DragPreviewRenderProps,
+	ResizeHandleRenderProps,
+} from '@wordpress/grid';
+import type { WidgetName } from '@wordpress/widget-primitives';
+
+/**
+ * Internal dependencies
+ */
+import { useDashboardInternalContext } from '../../context/dashboard-context';
+import { useDashboardContainerColumnCount } from '../../hooks/use-dashboard-container-column-count';
+import { WidgetChrome } from '../widget-chrome';
+import { WidgetSettingsToolbar } from '../widget-settings';
+import { WidgetLayoutToolbar } from './widget-layout-toolbar';
+import { WidgetResizeHandle } from './widget-resize-handle';
+import styles from './widgets.module.css';
+import type {
+	DashboardWidget,
+	GridTilePlacement,
+	MasonryTilePlacement,
+} from '../../types';
+
+function toGridLayout( widgets: DashboardWidget[] ): DashboardGridLayoutItem[] {
+	return widgets.map( ( w ) => ( {
+		key: w.uuid,
+		...( w.placement as GridTilePlacement | undefined ),
+	} ) );
+}
+
+function toMasonryLayout(
+	widgets: DashboardWidget[]
+): DashboardLanesLayoutItem[] {
+	return widgets.map( ( w ) => ( {
+		key: w.uuid,
+		...( w.placement as MasonryTilePlacement | undefined ),
+	} ) );
+}
+
+function applyGridChange(
+	widgets: DashboardWidget[],
+	gridLayout: DashboardGridLayoutItem[]
+): DashboardWidget[] {
+	return gridLayout.map( ( { key, ...placement } ) => {
+		const existing = widgets.find( ( w ) => w.uuid === key );
+		if ( ! existing ) {
+			return {
+				uuid: key,
+				type: '' as WidgetName,
+				placement,
+			};
+		}
+		return {
+			...existing,
+			placement,
+		};
+	} );
+}
+
+function applyMasonryChange(
+	widgets: DashboardWidget[],
+	masonryLayout: DashboardLanesLayoutItem[]
+): DashboardWidget[] {
+	return masonryLayout.map( ( { key, ...placement } ) => {
+		const existing = widgets.find( ( w ) => w.uuid === key );
+		if ( ! existing ) {
+			return {
+				uuid: key,
+				type: '' as WidgetName,
+				placement,
+			};
+		}
+		return {
+			...existing,
+			placement,
+		};
+	} );
+}
+
+export interface WidgetsProps {
+	className?: string;
+}
+
+/**
+ * Iterates `layout`, delegates each entry to `WidgetDashboard.WidgetChrome`, and
+ * feeds the resulting tree into the active `@wordpress/grid` surface (2D grid
+ * or masonry, picked from `gridSettings.model`).
+ */
+export const Widgets = forwardRef< HTMLDivElement, WidgetsProps >(
+	function Widgets( { className }, ref ) {
+		const { layout, onLayoutChange, editMode, gridSettings, widgetTypes } =
+			useDashboardInternalContext();
+		const { containerRef, columnCount } =
+			useDashboardContainerColumnCount( ref );
+		const isMasonry = gridSettings.model === 'masonry';
+
+		const gridLayout = useMemo(
+			() =>
+				isMasonry ? toMasonryLayout( layout ) : toGridLayout( layout ),
+			[ layout, isMasonry ]
+		);
+
+		const handleGridChange = useCallback(
+			( newGridLayout: DashboardGridLayoutItem[] ) => {
+				onLayoutChange( applyGridChange( layout, newGridLayout ) );
+			},
+			[ layout, onLayoutChange ]
+		);
+
+		const handleMasonryChange = useCallback(
+			( newMasonryLayout: DashboardLanesLayoutItem[] ) => {
+				onLayoutChange(
+					applyMasonryChange( layout, newMasonryLayout )
+				);
+			},
+			[ layout, onLayoutChange ]
+		);
+
+		const children = layout.map( ( widget, index ) => {
+			const widgetType = widgetTypes.find(
+				( type ) => type.name === widget.type
+			);
+			const hasSettings = !! widgetType?.attributes?.length;
+
+			// One slot, chosen by mode: layout toolbar while customizing,
+			// settings toolbar otherwise (undefined when nothing to configure).
+			let actionableArea: React.ReactNode;
+			if ( editMode ) {
+				actionableArea = <WidgetLayoutToolbar widget={ widget } />;
+			} else if ( hasSettings && widgetType ) {
+				actionableArea = (
+					<WidgetSettingsToolbar
+						widget={ widget }
+						widgetType={ widgetType }
+					/>
+				);
+			}
+
+			return (
+				<WidgetChrome
+					key={ widget.uuid }
+					widget={ widget }
+					index={ index }
+					className={ clsx( styles.tile, {
+						[ styles.tileEditMode ]: editMode,
+					} ) }
+					actionableArea={ actionableArea }
+				/>
+			);
+		} );
+
+		const renderDragPreview = useCallback(
+			( { children: clone }: DragPreviewRenderProps ) => (
+				<div className={ styles.dragPreview }>{ clone }</div>
+			),
+			[]
+		);
+
+		const sharedRenderProps = {
+			editMode,
+			renderDragPreview,
+			renderResizeHandle:
+				WidgetResizeHandle as React.ComponentType< ResizeHandleRenderProps >,
+		};
+
+		const surface: React.ReactNode = isMasonry ? (
+			<DashboardLanes
+				layout={ gridLayout as DashboardLanesLayoutItem[] }
+				columns={ columnCount }
+				flowTolerance={ gridSettings.flowTolerance }
+				onChangeLayout={ handleMasonryChange }
+				{ ...sharedRenderProps }
+			>
+				{ children }
+			</DashboardLanes>
+		) : (
+			<DashboardGrid
+				layout={ gridLayout as DashboardGridLayoutItem[] }
+				columns={ columnCount }
+				rowHeight={ gridSettings.rowHeight }
+				onChangeLayout={ handleGridChange }
+				{ ...sharedRenderProps }
+			>
+				{ children }
+			</DashboardGrid>
+		);
+
+		return (
+			<div
+				ref={ containerRef }
+				className={ clsx( styles.grid, className ) }
+			>
+				{ surface }
+			</div>
+		);
+	}
+);