@wordpress/grid 0.1.0

package/src/dashboard-lanes/use-lane-placement.ts

@@ -0,0 +1,313 @@
+/**
+ * WordPress dependencies
+ */
+import { useState, useLayoutEffect, useMemo } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { computeLanePlacements } from './lane-placement';
+import { GRID_ITEM_DATA_KEY } from '../shared/grid-item-key';
+
+const DEFAULT_ROW_UNIT = 4;
+
+function supportsGridLanes(): boolean {
+	if ( typeof CSS === 'undefined' || ! CSS.supports ) {
+		return false;
+	}
+	return CSS.supports( 'display', 'grid-lanes' );
+}
+
+function clampSpan( span: number | undefined ): number {
+	if ( typeof span !== 'number' || ! Number.isFinite( span ) ) {
+		return 1;
+	}
+	return Math.max( 1, Math.floor( span ) );
+}
+
+/**
+ * Logical item passed to the hook. The renderer is responsible for
+ * mounting a DOM node with `data-wp-grid-item-key={ item.key }` for each
+ * entry; the hook will measure that node and produce inline styles.
+ */
+export type LaneItemInput = {
+	key: string;
+	span?: number;
+	lane?: number;
+};
+
+export type UseLanePlacementInput = {
+	items: ReadonlyArray< LaneItemInput >;
+	lanes: number;
+	gap: number;
+	flowTolerance: number;
+	/**
+	 * Snap unit for `grid-row-start` / `grid-row-end: span N` math.
+	 * Smaller values produce sharper placement at the cost of more
+	 * implicit rows. Defaults to 4 (px).
+	 */
+	rowUnit?: number;
+};
+
+export type UseLanePlacementResult = {
+	/**
+	 * Inline styles to apply to each item, keyed by item key. On
+	 * native (`display: grid-lanes`), entries carry only
+	 * `gridColumn: span N`; the browser handles row placement. While
+	 * polyfilling, entries also carry explicit `grid-column-start` /
+	 * `grid-row-*` values.
+	 */
+	itemStyles: Map< string, React.CSSProperties >;
+
+	/**
+	 * `false` when the host browser supports `display: grid-lanes`
+	 * natively. The hook avoids mounting any observers in that case.
+	 */
+	isPolyfilled: boolean;
+};
+
+/**
+ * Hook that measures item heights and resolves their placement when
+ * `display: grid-lanes` is unavailable, falling through to a no-op
+ * pass when the host browser supports the feature natively.
+ *
+ * Usage from the renderer:
+ *
+ * ```tsx
+ * const [ container, setContainer ] = useState< HTMLDivElement | null >( null );
+ * const { itemStyles } = useLanePlacement( container, {
+ *     items: layout,
+ *     lanes: columns,
+ *     gap: gapPx,
+ *     flowTolerance: 16,
+ * } );
+ *
+ * return (
+ *     <div ref={ setContainer } style={ { display: 'grid-lanes', ... } }>
+ *         { items.map( ( item ) => (
+ *             <div
+ *                 key={ item.key }
+ *                 data-wp-grid-item-key={ item.key }
+ *                 style={ itemStyles.get( item.key ) }
+ *             >
+ *                 { ... }
+ *             </div>
+ *         ) ) }
+ *     </div>
+ * );
+ * ```
+ *
+ * @param container HTMLElement (or null pre-mount) hosting the items.
+ * @param input     Logical items, lane count, gap, and tuning.
+ * @return Per-item styles plus the `isPolyfilled` flag.
+ */
+export function useLanePlacement(
+	container: HTMLElement | null,
+	input: UseLanePlacementInput
+): UseLanePlacementResult {
+	// Detect once at mount. SSR returns `true` (CSS undefined); the
+	// client-first render returns the real value. Either path produces
+	// the same DOM until the polyfill effect runs (both emit
+	// span-only styles), so there is no hydration mismatch.
+	const [ isPolyfilled ] = useState( () => ! supportsGridLanes() );
+
+	const [ itemStyles, setItemStyles ] = useState<
+		Map< string, React.CSSProperties >
+	>( () => new Map() );
+
+	// Native pass-through: items only need their column span; the
+	// browser handles row placement. Memoized so a stable items
+	// array yields a stable Map identity.
+	const nativeStyles = useMemo( () => {
+		const map = new Map< string, React.CSSProperties >();
+		for ( const item of input.items ) {
+			map.set( item.key, {
+				gridColumn: `span ${ clampSpan( item.span ) }`,
+			} );
+		}
+		return map;
+	}, [ input.items ] );
+
+	// Stable signature of items for deps. Keys, spans, and explicit
+	// lanes are the only fields that influence observer wiring or
+	// placement, so we hash exactly those.
+	const itemsSignature = useMemo( () => {
+		return input.items
+			.map(
+				( item ) =>
+					`${ item.key }/${ item.span ?? 1 }/${ item.lane ?? '' }`
+			)
+			.join( '\0' );
+	}, [ input.items ] );
+
+	// Stable array identity while placement-relevant fields match
+	// `itemsSignature`, so the layout effect is not torn down on every
+	// parent re-render that passes a fresh `items` reference.
+	// eslint-disable-next-line react-hooks/exhaustive-deps -- `itemsSignature` encodes keys/spans/lanes; `input.items` reference often changes without placement changes.
+	const itemsForPlacement = useMemo( () => input.items, [ itemsSignature ] );
+
+	const { lanes, gap, flowTolerance, rowUnit } = input;
+
+	useLayoutEffect( () => {
+		if ( ! isPolyfilled || ! container ) {
+			return;
+		}
+		if ( typeof ResizeObserver === 'undefined' ) {
+			return;
+		}
+
+		const heights = new Map< string, number >();
+		const observed = new Set< Element >();
+		let cancelled = false;
+		let rafId: number | null = null;
+
+		const recompute = () => {
+			if ( rafId !== null || cancelled ) {
+				return;
+			}
+			// One layout per frame even when ResizeObserver and
+			// MutationObserver fire in the same tick.
+			rafId = requestAnimationFrame( () => {
+				rafId = null;
+				if ( cancelled ) {
+					return;
+				}
+				const itemsWithHeight = itemsForPlacement.map( ( item ) => ( {
+					key: item.key,
+					span: clampSpan( item.span ),
+					lane: item.lane,
+					height: heights.get( item.key ) ?? 0,
+				} ) );
+				const result = computeLanePlacements( {
+					items: itemsWithHeight,
+					lanes,
+					gap,
+					flowTolerance,
+				} );
+				const effectiveRowUnit = Math.max(
+					1,
+					rowUnit ?? DEFAULT_ROW_UNIT
+				);
+				const next = new Map< string, React.CSSProperties >();
+				for ( const item of itemsForPlacement ) {
+					const placement = result.placements.get( item.key );
+					if ( ! placement ) {
+						continue;
+					}
+					const height = heights.get( item.key ) ?? 0;
+					const rowStart =
+						Math.floor( placement.top / effectiveRowUnit ) + 1;
+					const rowSpan = Math.max(
+						1,
+						Math.ceil( height / effectiveRowUnit )
+					);
+					next.set( item.key, {
+						gridColumnStart: placement.lane + 1,
+						gridColumnEnd: `span ${ placement.span }`,
+						gridRowStart: rowStart,
+						gridRowEnd: `span ${ rowSpan }`,
+					} );
+				}
+				setItemStyles( next );
+			} );
+		};
+
+		const resizeObserver = new ResizeObserver( ( entries ) => {
+			let changed = false;
+			for ( const entry of entries ) {
+				const key = ( entry.target as HTMLElement ).getAttribute(
+					GRID_ITEM_DATA_KEY
+				);
+				if ( ! key ) {
+					continue;
+				}
+				const newHeight = entry.contentRect.height;
+				if ( heights.get( key ) !== newHeight ) {
+					heights.set( key, newHeight );
+					changed = true;
+				}
+			}
+			if ( changed ) {
+				recompute();
+			}
+		} );
+
+		const refreshObserved = () => {
+			const current = container.querySelectorAll(
+				`[${ GRID_ITEM_DATA_KEY }]`
+			);
+			for ( const element of current ) {
+				if ( ! observed.has( element ) ) {
+					observed.add( element );
+					resizeObserver.observe( element );
+					const key = element.getAttribute( GRID_ITEM_DATA_KEY );
+					if ( key ) {
+						const rect = (
+							element as HTMLElement
+						 ).getBoundingClientRect();
+						heights.set( key, rect.height );
+					}
+				}
+			}
+			for ( const element of observed ) {
+				if ( ! container.contains( element ) ) {
+					resizeObserver.unobserve( element );
+					observed.delete( element );
+				}
+			}
+		};
+
+		// Children may mount, unmount, or change `data-wp-grid-item-key`
+		// after the container exists (drag reorders, additions). The
+		// mutation observer keeps the observed set in sync.
+		const mutationObserver =
+			typeof MutationObserver !== 'undefined'
+				? new MutationObserver( () => {
+						refreshObserved();
+						recompute();
+				  } )
+				: null;
+		if ( mutationObserver ) {
+			mutationObserver.observe( container, {
+				childList: true,
+				subtree: true,
+				attributes: true,
+				attributeFilter: [ GRID_ITEM_DATA_KEY ],
+			} );
+		}
+
+		refreshObserved();
+		recompute();
+
+		return () => {
+			cancelled = true;
+			if ( rafId !== null ) {
+				cancelAnimationFrame( rafId );
+			}
+			resizeObserver.disconnect();
+			mutationObserver?.disconnect();
+		};
+	}, [
+		container,
+		isPolyfilled,
+		lanes,
+		gap,
+		flowTolerance,
+		rowUnit,
+		itemsForPlacement,
+	] );
+
+	if ( ! isPolyfilled ) {
+		return { itemStyles: nativeStyles, isPolyfilled: false };
+	}
+	if ( itemStyles.size === 0 ) {
+		// Pre-measurement frame: emit native-shape styles so items
+		// appear in their default span rather than collapsing to 1
+		// column at the top-left.
+		return {
+			itemStyles: nativeStyles as Map< string, React.CSSProperties >,
+			isPolyfilled: true,
+		};
+	}
+	return { itemStyles, isPolyfilled: true };
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export { DashboardGrid } from './dashboard-grid';
+export { DashboardLanes } from './dashboard-lanes';
+
+export type {
+	DashboardGridLayoutItem,
+	DashboardGridProps,
+} from './dashboard-grid/types';
+export type {
+	DashboardLanesLayoutItem,
+	DashboardLanesProps,
+} from './dashboard-lanes/types';
+export type {
+	DragPreviewRenderProps,
+	GridOverlayRenderProps,
+	ResizeDelta,
+	ResizeHandleRenderProps,
+} from './shared/types';

package/src/shared/actionable-area-slot.module.css

@@ -0,0 +1,16 @@
+.actionable-area-slot {
+	opacity: 1;
+}
+
+@media (prefers-reduced-motion: no-preference) {
+	.actionable-area-slot {
+		transition:
+			opacity var(--wpds-motion-duration-md)
+			var(--wpds-motion-easing-subtle);
+	}
+}
+
+:global([data-wp-grid-resizing]) .actionable-area-slot {
+	opacity: 0;
+	pointer-events: none;
+}

package/src/shared/drag-overlay-drop-animation.ts

@@ -0,0 +1,66 @@
+/**
+ * External dependencies
+ */
+import {
+	defaultDropAnimation,
+	defaultDropAnimationSideEffects,
+} from '@dnd-kit/core';
+import type { DropAnimation } from '@dnd-kit/core';
+
+/** Matches `--wpds-motion-duration-md` on the drag preview frame exit. */
+export const DROP_ANIMATION_DURATION_MS = 200;
+
+/** Matches `--wpds-motion-easing-balanced` on the drag preview frame exit. */
+const DROP_ANIMATION_EASING = 'cubic-bezier(0.4, 0, 0.2, 1)';
+
+/**
+ * Composes @dnd-kit/core’s default overlay drop translation with preview
+ * exit keyframes (via side effects). When the pointer never moves, @dnd-kit
+ * skips the drop animation and these side effects do not run.
+ *
+ * @param dragPreviewFrameClassName Hashed class for `.drag-preview-frame`.
+ * @param exitingFrameClassName     Hashed class for the exit state.
+ */
+export function createDashboardDragDropAnimation(
+	dragPreviewFrameClassName: string,
+	exitingFrameClassName: string
+): DropAnimation {
+	return {
+		...defaultDropAnimation,
+		duration: DROP_ANIMATION_DURATION_MS,
+		easing: DROP_ANIMATION_EASING,
+		sideEffects( args ) {
+			const cleanupDefault = defaultDropAnimationSideEffects( {
+				styles: {
+					active: {
+						opacity: '0',
+					},
+				},
+			} )( args );
+
+			const frame = args.dragOverlay.node.getElementsByClassName(
+				dragPreviewFrameClassName
+			)[ 0 ] as HTMLElement | undefined;
+
+			if ( frame ) {
+				frame
+					.getAnimations()
+					.forEach( ( animation ) => animation.cancel() );
+				const lift = frame.firstElementChild;
+				if ( lift instanceof HTMLElement ) {
+					lift.getAnimations().forEach( ( animation ) =>
+						animation.cancel()
+					);
+				}
+				frame.classList.add( exitingFrameClassName );
+			}
+
+			return () => {
+				cleanupDefault?.();
+				if ( frame ) {
+					frame.classList.remove( exitingFrameClassName );
+				}
+			};
+		},
+	};
+}

package/src/shared/grid-item-key.ts

@@ -0,0 +1,5 @@
+/**
+ * Data attribute grid tiles declare so layout-shift animation can map
+ * measured DOM nodes back to logical item keys.
+ */
+export const GRID_ITEM_DATA_KEY = 'data-wp-grid-item-key';

package/src/shared/grid-overlay.module.css

@@ -0,0 +1,82 @@
+.overlay {
+	position: absolute;
+	inset: 0;
+	display: grid;
+	gap: var(--wp-grid-gap, var(--wpds-dimension-gap-xl));
+	pointer-events: none;
+	opacity: 0;
+	visibility: hidden;
+}
+
+.overlay.is-active {
+	opacity: 1;
+	visibility: visible;
+}
+
+/*
+ * Alpha wave: row-marker tiles (or column tracks on lanes) reveal in a
+ * diagonal sweep from the top-left using staggered delays.
+ */
+@media not (prefers-reduced-motion) {
+	.overlay.is-active .row,
+	.overlay.is-active:not(.has-rows) .column {
+		opacity: 0;
+		transform: scale(0.64);
+		animation:
+			grid-overlay-tile-in
+			var(--wpds-motion-duration-md) var(--wpds-motion-easing-subtle)
+			both;
+		animation-delay: calc(var(--wp-grid-overlay-wave-delay-step, 28ms) * (var(--wp-grid-overlay-column-index, 0) + var(--wp-grid-overlay-row-index, 0)));
+	}
+
+	@keyframes grid-overlay-tile-in {
+		to {
+			opacity: 1;
+			transform: scale(1);
+		}
+	}
+
+	.overlay:not(.is-active) {
+		transition:
+			opacity var(--wpds-motion-duration-sm)
+			var(--wpds-motion-easing-subtle),
+			visibility 0s linear var(--wpds-motion-duration-sm);
+	}
+
+	.overlay:not(.is-active) .row,
+	.overlay:not(.is-active) .column {
+		animation: none;
+		transform: none;
+	}
+}
+
+@media (prefers-reduced-motion: reduce) {
+	.overlay {
+		transition:
+			opacity var(--wpds-motion-duration-sm)
+			var(--wpds-motion-easing-subtle),
+			visibility 0s linear var(--wpds-motion-duration-sm);
+	}
+
+	.overlay.is-active {
+		transition:
+			opacity var(--wpds-motion-duration-sm)
+			var(--wpds-motion-easing-subtle),
+			visibility 0s linear 0s;
+	}
+}
+
+.column {
+	display: flex;
+	flex-direction: column;
+	gap: var(--wp-grid-gap, var(--wpds-dimension-gap-xl));
+	min-width: 0;
+}
+
+.row {
+	flex: 0 0 var(--wp-grid-overlay-row-height);
+	height: var(--wp-grid-overlay-row-height);
+	box-sizing: border-box;
+	border-radius: var(--wpds-border-radius-lg);
+	background-color: var(--wp-grid-overlay-tile-bg, var(--wpds-color-background-surface-neutral-weak));
+}

package/src/shared/grid-overlay.tsx

@@ -0,0 +1,93 @@
+/**
+ * External dependencies
+ */
+import clsx from 'clsx';
+
+/**
+ * WordPress dependencies
+ */
+import { useEffect, useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import type { GridOverlayRenderProps } from './types';
+import styles from './grid-overlay.module.css';
+
+/**
+ * Default edit-mode overlay: one column per track, each holding `rows`
+ * row-marker tiles when `rowHeight` is uniform. Used by both surfaces
+ * and replaceable via `renderGridOverlay`. Reveals with a diagonal
+ * wave on activate and releases paint cost while inactive.
+ *
+ * @param props           Render props supplied by the surface.
+ * @param props.columns   Column tracks to mirror.
+ * @param props.rowHeight Uniform row height in pixels; omitted for
+ *                        content-sized rows, which skip row markers.
+ * @param props.rows      Row tracks per column; omitted when unknown.
+ * @param props.isActive  When `false`, the overlay fades out.
+ */
+export function GridOverlay( {
+	columns,
+	rowHeight,
+	rows,
+	isActive,
+}: GridOverlayRenderProps ) {
+	const showRows =
+		typeof rowHeight === 'number' && typeof rows === 'number' && rows > 0;
+	// Bump the key when edit mode activates so CSS animations restart on
+	// each enter (the overlay stays mounted across toggles).
+	const [ waveKey, setWaveKey ] = useState( 0 );
+	useEffect( () => {
+		if ( isActive ) {
+			setWaveKey( ( key ) => key + 1 );
+		}
+	}, [ isActive ] );
+	const style: React.CSSProperties = {
+		gridTemplateColumns: `repeat(${ columns }, minmax(0, 1fr))`,
+		...( showRows
+			? ( {
+					'--wp-grid-overlay-row-height': `${ rowHeight }px`,
+			  } as React.CSSProperties )
+			: {} ),
+	};
+
+	return (
+		<div
+			key={ waveKey }
+			aria-hidden
+			className={ clsx(
+				styles.overlay,
+				isActive && styles[ 'is-active' ],
+				showRows && styles[ 'has-rows' ]
+			) }
+			style={ style }
+		>
+			{ Array.from( { length: columns }, ( _column, columnIndex ) => (
+				<div
+					key={ columnIndex }
+					className={ styles.column }
+					style={
+						{
+							'--wp-grid-overlay-column-index': columnIndex,
+							'--wp-grid-overlay-row-index': 0,
+						} as React.CSSProperties
+					}
+				>
+					{ showRows &&
+						Array.from( { length: rows }, ( _row, rowIndex ) => (
+							<div
+								key={ rowIndex }
+								className={ styles.row }
+								style={
+									{
+										'--wp-grid-overlay-row-index': rowIndex,
+									} as React.CSSProperties
+								}
+							/>
+						) ) }
+				</div>
+			) ) }
+		</div>
+	);
+}

package/src/shared/item-exit-animation.module.css

@@ -0,0 +1,49 @@
+/*
+ * Absolutely positioned clone of a removed tile. Siblings reflow via
+ * FLIP while this overlay scales down and fades out.
+ */
+.exit-overlay {
+	position: absolute;
+	pointer-events: none;
+	z-index: 2;
+	overflow: hidden;
+	transform-origin: center center;
+	opacity: 1;
+	transform: scale(1);
+}
+
+@media not (prefers-reduced-motion: reduce) {
+	.exit-overlay {
+		animation:
+			wp-grid-item-exit-opacity var(--wpds-motion-duration-md)
+			var(--wpds-motion-easing-subtle) forwards,
+			wp-grid-item-exit-scale var(--wpds-motion-duration-md)
+			var(--wpds-motion-easing-balanced) forwards;
+	}
+}
+
+@keyframes wp-grid-item-exit-opacity {
+	from {
+		opacity: 1;
+	}
+
+	to {
+		opacity: 0;
+	}
+}
+
+@keyframes wp-grid-item-exit-scale {
+	from {
+		transform: scale(1);
+	}
+
+	to {
+		transform: scale(0.88);
+	}
+}
+
+@media (prefers-reduced-motion: reduce) {
+	.exit-overlay {
+		display: none;
+	}
+}

package/src/shared/item-exit-overlay.tsx

@@ -0,0 +1,57 @@
+/**
+ * Internal dependencies
+ */
+import { GRID_ITEM_DATA_KEY } from './grid-item-key';
+import exitStyles from './item-exit-animation.module.css';
+import type { RectSnapshot } from './use-layout-shift-animation';
+
+export type ItemExitOverlayRect = Pick<
+	RectSnapshot,
+	'left' | 'top' | 'width' | 'height'
+>;
+
+export type ItemExitOverlayProps = {
+	itemKey: string;
+	rect: ItemExitOverlayRect;
+	children: React.ReactNode;
+	onAnimationEnd: () => void;
+};
+
+/**
+ * Ghost tile shown at the removed item's last position while siblings
+ * reflow. Not a sortable grid cell — only visual exit feedback.
+ *
+ * @param root0                Component props.
+ * @param root0.itemKey        Layout key of the removed tile.
+ * @param root0.rect           Last bounds relative to the grid surface.
+ * @param root0.children       Cached tile content to render in the ghost.
+ * @param root0.onAnimationEnd Called when the exit animation finishes.
+ */
+export function ItemExitOverlay( {
+	itemKey,
+	rect,
+	children,
+	onAnimationEnd,
+}: ItemExitOverlayProps ) {
+	return (
+		<div
+			className={ exitStyles[ 'exit-overlay' ] }
+			style={ {
+				left: rect.left,
+				top: rect.top,
+				width: rect.width,
+				height: rect.height,
+			} }
+			{ ...{ [ GRID_ITEM_DATA_KEY ]: itemKey } }
+			data-wp-grid-item-exiting=""
+			onAnimationEnd={ ( event ) => {
+				if ( event.target !== event.currentTarget ) {
+					return;
+				}
+				onAnimationEnd();
+			} }
+		>
+			{ children }
+		</div>
+	);
+}