@wordpress/grid 0.1.0

package/build-types/shared/use-layout-shift-animation.d.ts

@@ -0,0 +1,77 @@
+export type RectSnapshot = {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+};
+type UseLayoutShiftAnimationOptions = {
+    /**
+     * Surface root that contains grid tiles.
+     */
+    container: HTMLElement | null;
+    /**
+     * When false, snapshots are cleared and no transforms run.
+     */
+    enabled: boolean;
+    /**
+     * Serialized layout/placement state. The hook runs FLIP when this
+     * value changes while `enabled` is true.
+     */
+    layoutFingerprint: string;
+    /**
+     * Item key to skip (the tile being dragged or resized).
+     */
+    excludeItemKey?: string | null;
+};
+type UseLayoutShiftAnimationResult = {
+    /**
+     * Capture tile positions synchronously **before** a layout update
+     * (call immediately before `setTemporaryLayout` / similar).
+     */
+    captureLayoutSnapshot: () => void;
+    /**
+     * Container-relative rects from the last committed paint (settled, no
+     * FLIP invert transforms).
+     */
+    getLastPositions: () => ReadonlyMap<string, RectSnapshot> | null;
+    /**
+     * Tile positions immediately before the latest layout commit. Used
+     * by item-exit animation when keys drop out of `layout`.
+     */
+    getPositionsBeforeLastChange: () => ReadonlyMap<string, RectSnapshot> | null;
+};
+/**
+ * Animates sibling tiles when grid layout reflows during drag or resize
+ * using a FLIP transform (see `layout-shift-animation.module.css`).
+ *
+ * @param root0                   Hook options.
+ * @param root0.container         Surface root that contains grid tiles.
+ * @param root0.enabled           When false, snapshots are cleared and no transforms run.
+ * @param root0.layoutFingerprint Serialized layout/placement state.
+ * @param root0.excludeItemKey    Item key to skip (the tile being dragged or resized).
+ * @return Snapshot capture callback for use before layout updates.
+ */
+export declare function useLayoutShiftAnimation({ container, enabled, layoutFingerprint, excludeItemKey }: UseLayoutShiftAnimationOptions): UseLayoutShiftAnimationResult;
+/**
+ * Stable fingerprint for {@link useLayoutShiftAnimation}. Width/height
+ * values may be numbers or layout keywords (`'fill'`, `'full'`).
+ *
+ * @param layout Layout items to serialize.
+ * @return Fingerprint string.
+ */
+export declare function getLayoutFingerprint(layout: ReadonlyArray<{
+    key: string;
+    width?: number | string;
+    height?: number;
+    order?: number;
+    lane?: number;
+}>): string;
+/**
+ * Placement fingerprint for lanes polyfill / explicit grid positions.
+ *
+ * @param itemStyles Per-item inline placement styles.
+ * @return Fingerprint string.
+ */
+export declare function getPlacementFingerprint(itemStyles: Map<string, React.CSSProperties>): string;
+export {};
+//# sourceMappingURL=use-layout-shift-animation.d.ts.map

package/build-types/shared/use-layout-shift-animation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-layout-shift-animation.d.ts","sourceRoot":"","sources":["../../src/shared/use-layout-shift-animation.ts"],"names":[],"mappings":"AAWA,MAAM,MAAM,YAAY,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,KAAK,8BAA8B,GAAG;IACrC;;OAEG;IACH,SAAS,EAAE,WAAW,GAAG,IAAI,CAAC;IAE9B;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B,CAAC;AAEF,KAAK,6BAA6B,GAAG;IACpC;;;OAGG;IACH,qBAAqB,EAAE,MAAM,IAAI,CAAC;IAElC;;;OAGG;IACH,gBAAgB,EAAE,MAAM,WAAW,CAAE,MAAM,EAAE,YAAY,CAAE,GAAG,IAAI,CAAC;IAEnE;;;OAGG;IACH,4BAA4B,EAAE,MAAM,WAAW,CAC9C,MAAM,EACN,YAAY,CACZ,GAAG,IAAI,CAAC;CACT,CAAC;AA0EF;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAE,EACxC,SAAS,EACT,OAAO,EACP,iBAAiB,EACjB,cAAqB,EACrB,EAAE,8BAA8B,GAAI,6BAA6B,CAkFjE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CACnC,MAAM,EAAE,aAAa,CAAE;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACd,CAAE,GACD,MAAM,CASR;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACtC,UAAU,EAAE,GAAG,CAAE,MAAM,EAAE,KAAK,CAAC,aAAa,CAAE,GAC5C,MAAM,CAaR"}

package/package.json

@@ -0,0 +1,80 @@
+{
+	"name": "@wordpress/grid",
+	"version": "0.1.0",
+	"description": "Grid layout components for arranging tiles in dashboard-style surfaces, with drag-to-reorder and tile resizing.",
+	"author": "The WordPress Contributors",
+	"license": "GPL-2.0-or-later",
+	"keywords": [
+		"wordpress",
+		"gutenberg",
+		"grid",
+		"dashboard"
+	],
+	"homepage": "https://github.com/WordPress/gutenberg/tree/HEAD/packages/grid/README.md",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/WordPress/gutenberg.git",
+		"directory": "packages/grid"
+	},
+	"bugs": {
+		"url": "https://github.com/WordPress/gutenberg/issues"
+	},
+	"engines": {
+		"node": ">=20.10.0",
+		"npm": ">=10.2.3"
+	},
+	"files": [
+		"src",
+		"build",
+		"build-module",
+		"build-types",
+		"*.md"
+	],
+	"main": "build/index.cjs",
+	"module": "build-module/index.mjs",
+	"exports": {
+		".": {
+			"types": "./build-types/index.d.ts",
+			"import": "./build-module/index.mjs",
+			"default": "./build/index.cjs"
+		},
+		"./package.json": "./package.json"
+	},
+	"wpScript": false,
+	"types": "build-types",
+	"sideEffects": [
+		"src/**/*.module.css"
+	],
+	"dependencies": {
+		"@dnd-kit/core": "^6.3.1",
+		"@dnd-kit/sortable": "^10.0.0",
+		"@dnd-kit/utilities": "^3.2.2",
+		"@wordpress/compose": "^8.2.0",
+		"@wordpress/element": "^8.1.0",
+		"@wordpress/style-runtime": "^0.5.0",
+		"clsx": "^2.1.1"
+	},
+	"devDependencies": {
+		"@storybook/react-vite": "^10.4.3",
+		"@testing-library/dom": "^10.4.1",
+		"@testing-library/react": "^16.3.2",
+		"@types/jest": "^29.5.14",
+		"@wordpress/icons": "^15.0.0",
+		"@wordpress/ui": "^0.16.0",
+		"storybook": "^10.4.3"
+	},
+	"peerDependencies": {
+		"@types/react": "^18.3.27",
+		"react": "^18.0.0",
+		"react-dom": "^18.0.0"
+	},
+	"peerDependenciesMeta": {
+		"@types/react": {
+			"optional": true
+		}
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"gitHead": "0e7112a4f4fde4ea15bd9060489b8f6fe11eb6ca"
+}

package/src/dashboard-grid/grid-item.module.css

@@ -0,0 +1,94 @@
+.item {
+	position: relative;
+}
+
+.item-content {
+	position: relative;
+	height: 100%;
+}
+
+.is-resizing {
+	overflow: visible;
+	z-index: 1;
+}
+
+.is-resizing .item-content {
+	position: relative;
+	z-index: 2;
+	overflow: visible;
+}
+
+/*
+ * During drag, the original item acts as a placeholder in its grid
+ * cell while `<DragOverlay>` renders a clone that follows the cursor.
+ * Fading the placeholder and outlining it makes the destination visible
+ * without any scaling or translation on the original element.
+ *
+ * Placeholder chrome waits until `data-wp-grid-dragging` is set and the
+ * drag-preview enter animation (`--wpds-motion-duration-sm`) finishes
+ * so the dashed outline does not flash under the lifting clone.
+ */
+.is-dragging {
+	pointer-events: none;
+}
+
+:global([data-wp-grid-dragging]) .is-dragging {
+	border-radius: var(--wp-grid-placeholder-radius, 0);
+}
+
+@media not (prefers-reduced-motion: reduce) {
+	:global([data-wp-grid-dragging]) .is-dragging {
+		opacity: 1;
+		outline-width: 0;
+		outline-style: var(--wp-grid-placeholder-outline-style, dashed);
+		outline-color: transparent;
+		animation:
+			wp-grid-item-placeholder-in 0ms linear
+			var(--wpds-motion-duration-sm) forwards;
+	}
+
+	@keyframes wp-grid-item-placeholder-in {
+		to {
+			opacity: var(--wp-grid-placeholder-opacity, 0.4);
+			outline-width: var(--wpds-border-width-sm);
+			outline-color: var(--wp-grid-placeholder-outline-color, var(--wpds-color-stroke-interactive-brand));
+		}
+	}
+}
+
+@media (prefers-reduced-motion: reduce) {
+	:global([data-wp-grid-dragging]) .is-dragging {
+		opacity: var(--wp-grid-placeholder-opacity, 0.4);
+		outline:
+			var(--wpds-border-width-sm)
+			var(--wp-grid-placeholder-outline-style, dashed)
+			var(--wp-grid-placeholder-outline-color, var(--wpds-color-stroke-interactive-brand));
+	}
+}
+
+@media (forced-colors: active) {
+	:global([data-wp-grid-dragging]) .is-dragging {
+		--wp-grid-placeholder-outline-color: Highlight;
+	}
+}
+
+.preview-overlay {
+	position: absolute;
+	top: 0;
+	inset-inline-start: 0;
+	box-sizing: border-box;
+	pointer-events: none;
+	z-index: 0;
+	border:
+		var(--wpds-border-width-sm)
+		var(--wp-grid-resize-preview-outline-style, solid)
+		var(--wp-grid-placeholder-outline-color, var(--wpds-color-stroke-interactive-brand));
+	background: transparent;
+	border-radius: var(--wp-grid-placeholder-radius, 0);
+}
+
+@media (forced-colors: active) {
+	.preview-overlay {
+		border-color: Highlight;
+	}
+}

package/src/dashboard-grid/grid-item.tsx

@@ -0,0 +1,205 @@
+/**
+ * External dependencies
+ */
+import { useSortable } from '@dnd-kit/sortable';
+import clsx from 'clsx';
+
+/**
+ * WordPress dependencies
+ */
+import { useState, useRef } from '@wordpress/element';
+import { useMergeRefs } from '@wordpress/compose';
+
+/**
+ * Internal dependencies
+ */
+import actionableAreaStyles from '../shared/actionable-area-slot.module.css';
+import { GRID_ITEM_DATA_KEY } from '../shared/grid-item-key';
+import ResizeHandle from '../shared/resize-handle';
+import { clampResizeDelta, type ResizeSnapSize } from '../shared/resize-snap';
+import type { ResizeDelta } from '../shared/types';
+import type { GridItemProps } from './types';
+import styles from './grid-item.module.css';
+
+function getItemCursor(
+	disabled: boolean,
+	interacting: boolean
+): React.CSSProperties[ 'cursor' ] {
+	if ( disabled ) {
+		return 'default';
+	}
+
+	if ( interacting ) {
+		return undefined;
+	}
+
+	return 'grab';
+}
+
+export function GridItem( {
+	item,
+	maxColumns,
+	disabled = false,
+	verticalResizable = true,
+	interacting = false,
+	dragging = false,
+	children,
+	actionableArea = null,
+	onResize,
+	onResizeEnd,
+	resizeSnapPreview = null,
+	minResizeWidthPx,
+	minResizeHeightPx,
+	renderResizeHandle,
+}: GridItemProps ) {
+	const [ resizeDelta, setResizeDelta ] = useState< ResizeDelta | null >(
+		null
+	);
+	const [ initialContentSize, setInitialContentSize ] = useState< {
+		width: number;
+		height: number;
+	} | null >( null );
+	const itemRef = useRef< HTMLDivElement >( null );
+	const contentRef = useRef< HTMLDivElement >( null );
+	const {
+		attributes,
+		listeners,
+		setNodeRef,
+		setActivatorNodeRef,
+		isDragging,
+	} = useSortable( {
+		id: item.key,
+		disabled,
+	} );
+	const mergedRef = useMergeRefs( [ itemRef, setNodeRef ] );
+	const contentMergedRef = useMergeRefs( [ contentRef ] );
+	/*
+	 * With `<DragOverlay>` handling the cursor-following clone, the
+	 * sortable item stays put in its grid cell and acts as a
+	 * placeholder. No `transform` is applied here — applying one
+	 * would double-move the placeholder alongside the overlay.
+	 */
+	const style = {
+		gridColumnEnd: `span ${
+			item.width === 'full'
+				? maxColumns
+				: Math.min(
+						typeof item.width === 'number' ? item.width : 1,
+						maxColumns
+				  )
+		}`,
+		gridRowEnd: `span ${ item.height || 1 }`,
+	};
+
+	const isResizing = resizeDelta !== null;
+	const itemClassName = clsx(
+		styles.item,
+		isDragging && styles[ 'is-dragging' ],
+		isResizing && styles[ 'is-resizing' ]
+	);
+
+	const handleResize = ( delta: ResizeDelta ) => {
+		const contentNode = contentRef.current;
+		let baselineSize = initialContentSize;
+		if ( contentNode && ! baselineSize ) {
+			const { width, height } = contentNode.getBoundingClientRect();
+			baselineSize = { width, height };
+			setInitialContentSize( baselineSize );
+		}
+		let clamped: ResizeDelta = {
+			width: delta.width,
+			height: verticalResizable ? delta.height : 0,
+		};
+		if ( baselineSize ) {
+			clamped = clampResizeDelta( clamped, baselineSize, {
+				width: minResizeWidthPx,
+				height: verticalResizable ? minResizeHeightPx : undefined,
+			} );
+		}
+		setResizeDelta( clamped );
+		onResize( item.key, clamped );
+	};
+
+	const handleResizeEnd = () => {
+		setResizeDelta( null );
+		setInitialContentSize( null );
+		onResizeEnd();
+	};
+
+	const continuousContentStyle: React.CSSProperties | undefined =
+		resizeDelta && initialContentSize
+			? {
+					width: initialContentSize.width + resizeDelta.width,
+					height: verticalResizable
+						? initialContentSize.height + resizeDelta.height
+						: undefined,
+			  }
+			: undefined;
+
+	const previewOverlay = resizeSnapPreview ? (
+		<SnapPreviewOverlay snap={ resizeSnapPreview } />
+	) : null;
+
+	return (
+		<div
+			ref={ mergedRef }
+			className={ itemClassName }
+			style={ style }
+			{ ...{ [ GRID_ITEM_DATA_KEY ]: item.key } }
+			data-wp-grid-item-resizing={ isResizing || undefined }
+		>
+			{ actionableArea ? (
+				<div
+					className={ actionableAreaStyles[ 'actionable-area-slot' ] }
+				>
+					<div
+						style={ { display: 'contents' } }
+						{ ...( dragging ? { inert: '' } : {} ) }
+					>
+						{ actionableArea }
+					</div>
+				</div>
+			) : null }
+
+			<div
+				ref={ setActivatorNodeRef }
+				{ ...attributes }
+				{ ...listeners }
+				style={ {
+					height: '100%',
+					cursor: getItemCursor( disabled, interacting ),
+				} }
+			>
+				<div
+					ref={ contentMergedRef }
+					className={ styles[ 'item-content' ] }
+					style={ continuousContentStyle }
+				>
+					{ children }
+					{ ! disabled && (
+						<ResizeHandle
+							itemId={ item.key }
+							verticalResizable={ verticalResizable }
+							onResize={ handleResize }
+							onResizeEnd={ handleResizeEnd }
+							renderResizeHandle={ renderResizeHandle }
+						/>
+					) }
+				</div>
+				{ previewOverlay }
+			</div>
+		</div>
+	);
+}
+
+function SnapPreviewOverlay( { snap }: { snap: ResizeSnapSize } ) {
+	return (
+		<div
+			className={ styles[ 'preview-overlay' ] }
+			style={ {
+				width: snap.widthPx,
+				height: snap.heightPx ?? '100%',
+			} }
+		/>
+	);
+}

package/src/dashboard-grid/grid.module.css

@@ -0,0 +1,134 @@
+.grid {
+	display: grid;
+	gap: var(--wp-grid-gap, var(--wpds-dimension-gap-xl));
+	position: relative;
+}
+
+/*
+ * Functional frame for the drag-preview clone inside `<DragOverlay>`.
+ * Always applied, including when the consumer passes a
+ * `renderDragPreview` wrapper. The outer frame has no `transform` so
+ * @dnd-kit’s drop translation matches the placeholder; scale lives on
+ * `__lift` (see dnd-kit #398). Owns elevation, radius, cursor, and
+ * pointer pass-through. Further chrome belongs to the consumer. Drag
+ * elevation animates `xs` → `md` so it reads above edit tiles at `xs`.
+ */
+.drag-preview-frame {
+	height: 100%;
+	border-radius: var(--wp-grid-drag-preview-radius, 0);
+	cursor: grabbing;
+	pointer-events: none;
+	box-shadow: var(--wpds-elevation-md);
+}
+
+.drag-preview-frame__lift {
+	height: 100%;
+	transform: scale(var(--wp-grid-drag-preview-scale, 1.05));
+	transform-origin: center;
+}
+
+@media not (prefers-reduced-motion: reduce) {
+	.drag-preview-frame {
+		animation:
+			wp-grid-drag-preview-shadow-enter
+			var(--wpds-motion-duration-sm) var(--wpds-motion-easing-balanced) both;
+	}
+
+	.drag-preview-frame__lift {
+		animation:
+			wp-grid-drag-preview-scale-enter
+			var(--wpds-motion-duration-sm) var(--wpds-motion-easing-balanced) both;
+	}
+}
+
+@media not (prefers-reduced-motion: reduce) {
+	@keyframes wp-grid-drag-preview-shadow-enter {
+		from {
+			box-shadow: var(--wpds-elevation-xs);
+		}
+
+		to {
+			box-shadow: var(--wpds-elevation-md);
+		}
+	}
+
+	@keyframes wp-grid-drag-preview-scale-enter {
+		from {
+			transform: scale(1);
+		}
+
+		to {
+			transform: scale(var(--wp-grid-drag-preview-scale, 1.05));
+		}
+	}
+}
+
+/*
+ * Applied by @dnd-kit `DragOverlay` drop side-effects while the
+ * default overlay transform runs; duration matches
+ * `createDashboardDragDropAnimation` (200ms / md token). Use keyframed
+ * exit (not transition) so scale does not snap when the enter animation
+ * is replaced.
+ */
+@media not (prefers-reduced-motion: reduce) {
+	.drag-preview-frame.dragPreviewFrameExiting {
+		animation:
+			wp-grid-drag-preview-shadow-exit
+			var(--wpds-motion-duration-md) var(--wpds-motion-easing-balanced)
+			forwards;
+	}
+
+	.drag-preview-frame.dragPreviewFrameExiting .drag-preview-frame__lift {
+		animation:
+			wp-grid-drag-preview-scale-exit
+			var(--wpds-motion-duration-md) var(--wpds-motion-easing-balanced)
+			forwards;
+	}
+
+	@keyframes wp-grid-drag-preview-shadow-exit {
+		from {
+			box-shadow: var(--wpds-elevation-md);
+		}
+
+		to {
+			box-shadow: var(--wpds-elevation-xs);
+		}
+	}
+
+	@keyframes wp-grid-drag-preview-scale-exit {
+		from {
+			transform: scale(var(--wp-grid-drag-preview-scale, 1.05));
+		}
+
+		to {
+			transform: scale(1);
+		}
+	}
+}
+
+.drag-preview-frame.dragPreviewFrameExiting {
+	box-shadow: var(--wpds-elevation-xs);
+}
+
+.drag-preview-frame.dragPreviewFrameExiting .drag-preview-frame__lift {
+	transform: scale(1);
+}
+
+@media (prefers-reduced-motion: reduce) {
+	.drag-preview-frame {
+		box-shadow: var(--wpds-elevation-md);
+	}
+
+	.drag-preview-frame__lift {
+		transform: none;
+	}
+
+	.drag-preview-frame.dragPreviewFrameExiting {
+		box-shadow: var(--wpds-elevation-xs);
+		transition: none;
+	}
+
+	.drag-preview-frame.dragPreviewFrameExiting .drag-preview-frame__lift {
+		transition: none;
+	}
+}