@wordpress/grid 0.1.0

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

@@ -0,0 +1,245 @@
+/**
+ * Lane placement algorithm for `display: grid-lanes` polyfill.
+ *
+ * Implements the source-ordered, shortest-lane placement described in
+ * https://webkit.org/blog/17660/introducing-css-grid-lanes/.
+ *
+ * The skyline + tolerance core is adapted from the CSS Grid Lanes
+ * Polyfill by Simon Willison (MIT,
+ * https://tools.simonwillison.net/grid-lanes-polyfill.js). The rest
+ * of this module is a pure function suitable for unit testing in
+ * isolation from any DOM.
+ *
+ * Concepts:
+ * - "Lane" is the cross-axis track: a column in waterfall mode, a row
+ *   in brick mode. The algorithm is axis-agnostic; the renderer maps
+ *   the chosen lane index plus offset to `grid-column-start` /
+ *   `grid-row-start` (or vice versa).
+ * - Items are placed in source order. Explicit-lane items are placed
+ *   first so auto-placed items can flow around them.
+ * - `flowTolerance` is a length: when two candidate lanes differ in
+ *   baseline by no more than this, the earlier lane wins (preserves
+ *   reading order).
+ */
+
+/**
+ * A single item to place. Heights are pre-measured by the caller.
+ */
+export type LanePlacementItem = {
+	/**
+	 * Stable identity. Returned in the result map.
+	 */
+	key: string;
+
+	/**
+	 * Number of contiguous lanes this item occupies. Clamped to
+	 * `[ 1, lanes ]` by the algorithm.
+	 */
+	span: number;
+
+	/**
+	 * Measured cross-axis size (typically pixels). The algorithm only
+	 * adds and compares heights; the unit is whatever the caller uses,
+	 * as long as `gap` and `flowTolerance` use the same one.
+	 */
+	height: number;
+
+	/**
+	 * Explicit 0-indexed starting lane. When set, the item bypasses
+	 * the skyline lookup and is placed at this lane regardless of
+	 * source order. Out-of-range values are clamped.
+	 */
+	lane?: number;
+};
+
+/**
+ * Algorithm input.
+ */
+export type LanePlacementInput = {
+	/**
+	 * Items in source order.
+	 */
+	items: ReadonlyArray< LanePlacementItem >;
+
+	/**
+	 * Total number of lanes. Clamped to `>= 1`.
+	 */
+	lanes: number;
+
+	/**
+	 * Gap between items in the same lane. Same unit as `height`.
+	 */
+	gap: number;
+
+	/**
+	 * Tolerance for source-order tiebreaking. When two candidate
+	 * lanes have baselines within this amount, the earlier lane wins.
+	 * Defaults to `0` if a negative value is passed.
+	 */
+	flowTolerance: number;
+};
+
+/**
+ * Resolved position for a single item.
+ */
+export type LanePlacement = {
+	/**
+	 * Mirrors the input key.
+	 */
+	key: string;
+
+	/**
+	 * 0-indexed starting lane. The renderer adds 1 for
+	 * `grid-column-start`.
+	 */
+	lane: number;
+
+	/**
+	 * Cross-axis offset from the container's start edge, in the same
+	 * unit as the input heights. Use as the item's start position
+	 * (e.g. `top`, or `grid-row-start` after dividing by a row unit).
+	 */
+	top: number;
+
+	/**
+	 * Effective span after clamping. Useful for the renderer when the
+	 * input span exceeded the lane count.
+	 */
+	span: number;
+};
+
+/**
+ * Algorithm output.
+ */
+export type LanePlacementResult = {
+	/**
+	 * Per-key placement. Insertion-ordered: the first iteration yields
+	 * the explicit items in source order, then the auto items in
+	 * source order.
+	 */
+	placements: Map< string, LanePlacement >;
+
+	/**
+	 * Sum of the tallest lane after all items are placed. The renderer
+	 * applies this as the container's intrinsic height.
+	 */
+	totalHeight: number;
+};
+
+function clampSpan( span: number, lanes: number ): number {
+	if ( ! Number.isFinite( span ) ) {
+		return 1;
+	}
+	return Math.max( 1, Math.min( Math.floor( span ), lanes ) );
+}
+
+function clampLane( lane: number, span: number, lanes: number ): number {
+	if ( ! Number.isFinite( lane ) ) {
+		return 0;
+	}
+	return Math.max( 0, Math.min( Math.floor( lane ), lanes - span ) );
+}
+
+function maxBaselineAcross(
+	laneBottoms: ReadonlyArray< number >,
+	startLane: number,
+	span: number
+): number {
+	let maxBaseline = 0;
+	for ( let i = startLane; i < startLane + span; i++ ) {
+		if ( laneBottoms[ i ] > maxBaseline ) {
+			maxBaseline = laneBottoms[ i ];
+		}
+	}
+	return maxBaseline;
+}
+
+/**
+ * Places all items into a fixed lane count using the grid-lanes
+ * algorithm: explicit items first, then auto items chosen by the
+ * shortest-lane skyline with a tolerance for source order.
+ *
+ * Pure: no DOM access, no mutation of inputs. Safe to call from a
+ * worker or during SSR.
+ *
+ * @param input Items, lane count, gap, and tolerance.
+ * @return Per-key placements plus the resulting total height.
+ */
+export function computeLanePlacements(
+	input: LanePlacementInput
+): LanePlacementResult {
+	const lanes = Math.max( 1, Math.floor( input.lanes ) );
+	const gap = Math.max( 0, input.gap );
+	const tolerance = Math.max( 0, input.flowTolerance );
+
+	const laneBottoms = new Array< number >( lanes ).fill( 0 );
+	const placements = new Map< string, LanePlacement >();
+
+	const explicitItems: LanePlacementItem[] = [];
+	const autoItems: LanePlacementItem[] = [];
+	for ( const item of input.items ) {
+		if ( item.lane !== undefined ) {
+			explicitItems.push( item );
+		} else {
+			autoItems.push( item );
+		}
+	}
+
+	for ( const item of explicitItems ) {
+		const span = clampSpan( item.span, lanes );
+		const lane = clampLane( item.lane as number, span, lanes );
+		const baseline = maxBaselineAcross( laneBottoms, lane, span );
+		const top = baseline === 0 ? 0 : baseline + gap;
+		const height = Math.max( 0, item.height );
+
+		placements.set( item.key, { key: item.key, lane, top, span } );
+
+		const newBottom = top + height;
+		for ( let i = lane; i < lane + span; i++ ) {
+			laneBottoms[ i ] = newBottom;
+		}
+	}
+
+	for ( const item of autoItems ) {
+		const span = clampSpan( item.span, lanes );
+		let bestLane = 0;
+		let bestBaseline = Infinity;
+
+		for ( let candidate = 0; candidate <= lanes - span; candidate++ ) {
+			const baseline = maxBaselineAcross( laneBottoms, candidate, span );
+
+			// Only take a lane that is strictly shorter beyond
+			// tolerance. Within-tolerance ties keep the earlier lane
+			// because candidates iterate in lane order, so the first
+			// acceptable baseline wins.
+			if ( bestBaseline - baseline > tolerance ) {
+				bestBaseline = baseline;
+				bestLane = candidate;
+			}
+		}
+
+		const top = bestBaseline === 0 ? 0 : bestBaseline + gap;
+		const height = Math.max( 0, item.height );
+
+		placements.set( item.key, {
+			key: item.key,
+			lane: bestLane,
+			top,
+			span,
+		} );
+
+		const newBottom = top + height;
+		for ( let i = bestLane; i < bestLane + span; i++ ) {
+			laneBottoms[ i ] = newBottom;
+		}
+	}
+
+	let totalHeight = 0;
+	for ( const bottom of laneBottoms ) {
+		if ( bottom > totalHeight ) {
+			totalHeight = bottom;
+		}
+	}
+
+	return { placements, totalHeight };
+}

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

@@ -0,0 +1,93 @@
+.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 lane
+ * 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;
+}
+
+@media (forced-colors: active) {
+	.preview-overlay {
+		border-color: Highlight;
+	}
+}

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

@@ -0,0 +1,236 @@
+/**
+ * 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 ResizeHandle from '../shared/resize-handle';
+import { clampResizeDelta, type ResizeSnapSize } from '../shared/resize-snap';
+import { GRID_ITEM_DATA_KEY } from '../shared/grid-item-key';
+import type { ResizeDelta, ResizeHandleRenderProps } from '../shared/types';
+import styles from './lanes-item.module.css';
+
+function getItemCursor(
+	disabled: boolean,
+	interacting: boolean
+): React.CSSProperties[ 'cursor' ] {
+	if ( disabled ) {
+		return 'default';
+	}
+	if ( interacting ) {
+		return undefined;
+	}
+	return 'grab';
+}
+
+/**
+ * Props for the internal `<LanesItem />` wrapper.
+ */
+export type LanesItemProps = {
+	/**
+	 * Item key. Forwarded to dnd-kit and emitted as the
+	 * `data-wp-grid-item-key` attribute the hook reads to map measured DOM
+	 * nodes back to logical items.
+	 */
+	itemKey: string;
+
+	/**
+	 * Inline placement style produced by `useLanePlacement`. On native
+	 * (`display: grid-lanes`), only `gridColumn: span N`. While
+	 * polyfilling, also `gridColumnStart` / `gridRowStart` /
+	 * `gridRowEnd: span N`.
+	 */
+	placementStyle: React.CSSProperties;
+
+	/**
+	 * Whether drag and resize interactions are disabled.
+	 */
+	disabled?: boolean;
+
+	/**
+	 * Whether any tile in the surface is currently being dragged or
+	 * resized. Drives the drag activator cursor.
+	 */
+	interacting?: boolean;
+
+	/**
+	 * Whether a tile drag is in progress. Mutes each tile's
+	 * `actionableArea` with `inert` so hovers on other tiles' controls
+	 * do not steal the gesture.
+	 *
+	 * @default false
+	 */
+	dragging?: boolean;
+
+	children: React.ReactNode;
+
+	actionableArea?: React.ReactNode;
+
+	onResize: ( id: string, delta: ResizeDelta ) => void;
+
+	/**
+	 * Snapped column span in pixels for the resize-preview outline.
+	 */
+	resizeSnapPreview?: ResizeSnapSize | null;
+
+	/**
+	 * Minimum tile width while resizing, in pixels (one column track).
+	 */
+	minResizeWidthPx: number;
+
+	onResizeEnd: () => void;
+
+	renderResizeHandle?: React.ComponentType< ResizeHandleRenderProps >;
+};
+
+export function LanesItem( {
+	itemKey,
+	placementStyle,
+	disabled = false,
+	interacting = false,
+	children,
+	actionableArea = null,
+	onResize,
+	onResizeEnd,
+	resizeSnapPreview = null,
+	minResizeWidthPx,
+	renderResizeHandle,
+	dragging = false,
+}: LanesItemProps ) {
+	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: itemKey,
+		disabled,
+	} );
+	const mergedRef = useMergeRefs( [ itemRef, setNodeRef ] );
+	const contentMergedRef = useMergeRefs( [ contentRef ] );
+
+	const style: React.CSSProperties = {
+		...placementStyle,
+		alignSelf: 'start',
+	};
+
+	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: 0 };
+		if ( baselineSize ) {
+			clamped = clampResizeDelta( clamped, baselineSize, {
+				width: minResizeWidthPx,
+			} );
+		}
+		setResizeDelta( clamped );
+		onResize( itemKey, clamped );
+	};
+
+	const handleResizeEnd = () => {
+		setResizeDelta( null );
+		setInitialContentSize( null );
+		onResizeEnd();
+	};
+
+	const continuousContentStyle: React.CSSProperties | undefined =
+		resizeDelta && initialContentSize
+			? {
+					width: initialContentSize.width + resizeDelta.width,
+			  }
+			: undefined;
+
+	const previewOverlay = resizeSnapPreview ? (
+		<div
+			className={ styles[ 'preview-overlay' ] }
+			style={ {
+				width: resizeSnapPreview.widthPx,
+				height: resizeSnapPreview.heightPx ?? '100%',
+			} }
+		/>
+	) : null;
+
+	return (
+		<div
+			ref={ mergedRef }
+			className={ itemClassName }
+			style={ style }
+			{ ...{ [ GRID_ITEM_DATA_KEY ]: itemKey } }
+			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={ itemKey }
+							verticalResizable={ false }
+							onResize={ handleResize }
+							onResizeEnd={ handleResizeEnd }
+							renderResizeHandle={ renderResizeHandle }
+						/>
+					) }
+				</div>
+				{ previewOverlay }
+			</div>
+		</div>
+	);
+}

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

@@ -0,0 +1,152 @@
+.lanes {
+	display: grid-lanes;
+	column-gap: var(--wp-grid-gap, var(--wpds-dimension-gap-xl));
+	row-gap: var(--wp-grid-gap, var(--wpds-dimension-gap-xl));
+	position: relative;
+}
+
+/*
+ * Polyfill fallback. The hook computes per-item `grid-column-start`
+ * and `grid-row-start`/`grid-row-end: span N` against this row unit.
+ * The skyline already builds inter-item vertical spacing into each
+ * tile's `top`, so `row-gap` must be zero here to avoid compounding
+ * on top of the algorithm's spacing. `grid-auto-flow: dense` is a
+ * safety net; the algorithm drives placement.
+ */
+@supports not (display: grid-lanes) {
+	.lanes {
+		display: grid;
+		grid-auto-rows: var(--wp-grid-lane-row-unit, 4px);
+		grid-auto-flow: dense;
+		row-gap: 0;
+	}
+}
+
+/*
+ * 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;
+	}
+}