@wordpress/grid 0.1.0

package/src/shared/layout-shift-animation.module.css

@@ -0,0 +1,16 @@
+/*
+ * Sibling tile reflow during drag/resize/remove in edit mode. Transition
+ * lives on tiles so the browser can interpolate `transform` reliably
+ * (inline `transition` + FLIP in the same frame is skipped).
+ */
+.layout-animating :global([data-wp-grid-item-key]) {
+	transition:
+		transform var(--wpds-motion-duration-md)
+		var(--wpds-motion-easing-balanced);
+}
+
+@media (prefers-reduced-motion: reduce) {
+	.layout-animating :global([data-wp-grid-item-key]) {
+		transition: none;
+	}
+}

package/src/shared/resize-handle.module.css

@@ -0,0 +1,88 @@
+/*
+ * Fade with opacity only: `visibility` is not interpolatable and pairing
+ * it with delayed transitions breaks fade-in.
+ */
+.resize-handle-slot {
+	opacity: 1;
+}
+
+@media (prefers-reduced-motion: no-preference) {
+	.resize-handle-slot {
+		transition:
+			opacity var(--wpds-motion-duration-md)
+			var(--wpds-motion-easing-subtle);
+	}
+}
+
+/*
+ * Grid-level interaction hooks (`data-wp-grid-dragging`,
+ * `data-wp-grid-resizing`, `data-wp-grid-item-resizing`) drive
+ * handle visibility.
+ */
+:global([data-wp-grid-dragging]) .resize-handle-slot,
+:global([data-wp-grid-resizing]) .resize-handle-slot {
+	opacity: 0;
+	pointer-events: none;
+}
+
+:global([data-wp-grid-resizing])
+:global([data-wp-grid-item-resizing])
+.resize-handle-slot {
+	opacity: 1;
+	pointer-events: auto;
+}
+
+.resize-handle {
+	position: absolute;
+	bottom: 0;
+	inset-inline-end: 0;
+	width: 0;
+	height: 0;
+	z-index: 1;
+	cursor: nwse-resize;
+	/*
+	 * Triangle drawn via borders. Use per-side logical shorthands
+	 * instead of `border-width: 0` + `border-block-end-width: 12px`:
+	 * the build's CSS optimizer merges the global shorthands into a
+	 * single `border: 0 solid transparent` and emits it AFTER the
+	 * logical longhands, which then loses the cascade and zeroes
+	 * the triangle widths. The unused sides default to
+	 * `border-style: none` and render as 0 regardless of width.
+	 */
+	border-block-end: 12px solid var(--wpds-color-foreground-interactive-brand);
+	border-inline-start: 12px solid transparent;
+}
+
+/*
+ * When the host surface only resizes horizontally (e.g. lanes,
+ * where height is content-driven), the corner triangle advertises a
+ * vertical drag the user cannot perform. Override with a vertical
+ * grip centered on the trailing edge.
+ */
+.is-horizontal-only {
+	cursor: ew-resize;
+	border-style: none;
+	bottom: auto;
+	top: 50%;
+	transform: translateY(-50%);
+	width: 16px;
+	height: 40px;
+	background: transparent;
+	display: flex;
+	align-items: center;
+	justify-content: center;
+}
+
+.is-horizontal-only::before {
+	content: "";
+	width: 4px;
+	height: 24px;
+	border-radius: 2px;
+	background-color: var(--wpds-color-foreground-interactive-brand);
+}
+
+@media (forced-colors: active) {
+	.is-horizontal-only::before {
+		background-color: Highlight;
+	}
+}

package/src/shared/resize-handle.tsx

@@ -0,0 +1,163 @@
+/**
+ * External dependencies
+ */
+import { DndContext, useDraggable } from '@dnd-kit/core';
+import type { DragMoveEvent } from '@dnd-kit/core';
+import clsx from 'clsx';
+
+/**
+ * WordPress dependencies
+ */
+import { useCallback, useEffect, useRef } from '@wordpress/element';
+import { useMergeRefs, useThrottle } from '@wordpress/compose';
+
+/**
+ * Internal dependencies
+ */
+import type { ResizeDelta, ResizeHandleProps } from './types';
+import styles from './resize-handle.module.css';
+
+/**
+ * Sets `document.documentElement.style.cursor` for the duration of a drag
+ * and restores it on cleanup. Lives outside the component so cursor writes
+ * are not analyzed as mutating values derived from refs in the component
+ * body (react-hooks/immutability).
+ *
+ * @param getDocument Returns the document whose root element should receive
+ *                    the cursor (handle owner, or global `document`).
+ * @param cursor      CSS cursor value while active.
+ * @return Cleanup that restores the previous cursor.
+ */
+function lockDocumentCursorWhileActive(
+	getDocument: () => Document,
+	cursor: string
+): () => void {
+	const root = getDocument().documentElement;
+	const previous = root.style.cursor;
+	root.style.cursor = cursor;
+	return () => {
+		root.style.cursor = previous;
+	};
+}
+
+function ResizeHandle( {
+	itemId,
+	verticalResizable = true,
+	renderResizeHandle,
+}: ResizeHandleProps ) {
+	const { attributes, listeners, setNodeRef, isDragging } = useDraggable( {
+		id: 'draggable',
+		data: { itemId },
+	} );
+
+	// Snapshot owner document on mount/update via ref callback so the
+	// cursor-lock effect can resolve the correct document in an iframe.
+	const ownerDocumentRef = useRef< Document | null >( null );
+	const setOwnerDocumentRef = useCallback( ( node: HTMLElement | null ) => {
+		ownerDocumentRef.current = node?.ownerDocument ?? null;
+	}, [] );
+	const mergedRef = useMergeRefs( [ setOwnerDocumentRef, setNodeRef ] );
+
+	// Lock the document cursor while the gesture is active. Without
+	// this, the OS pointer reverts to the default arrow as soon as it
+	// leaves the handle's hit area, even though the resize is still
+	// in progress.
+	useEffect( () => {
+		if ( ! isDragging ) {
+			return;
+		}
+		const cursor = verticalResizable ? 'nwse-resize' : 'ew-resize';
+		return lockDocumentCursorWhileActive(
+			() => ownerDocumentRef.current ?? document,
+			cursor
+		);
+	}, [ isDragging, verticalResizable ] );
+
+	if ( renderResizeHandle ) {
+		const RenderResizeHandle = renderResizeHandle;
+		return (
+			<RenderResizeHandle
+				ref={ mergedRef }
+				listeners={ listeners }
+				attributes={ attributes }
+				verticalResizable={ verticalResizable }
+				isResizing={ isDragging }
+				itemId={ itemId }
+			/>
+		);
+	}
+
+	return (
+		<div
+			ref={ mergedRef }
+			className={ clsx(
+				styles[ 'resize-handle' ],
+				! verticalResizable && styles[ 'is-horizontal-only' ]
+			) }
+			{ ...listeners }
+			{ ...attributes }
+		/>
+	);
+}
+
+/**
+ * Renders a corner resize handle inside an isolated `<DndContext>`.
+ * Reports the cursor offset since the gesture started (in pixels)
+ * via `onResize`, throttled to one animation frame so the grid
+ * commit loop runs at most once per paint.
+ *
+ * Auto-scroll is enabled with a tight trigger zone and a low
+ * acceleration so a resize gesture near the viewport edge scrolls
+ * the page only when the user deliberately pushes against the very
+ * edge, and even then at a pace the user can interrupt by releasing.
+ * Default tuning would otherwise produce a runaway loop where the
+ * page scrolls fast, dnd-kit's document-coordinate `delta` inflates
+ * with the scroll, and the tile keeps growing without further user
+ * input.
+ *
+ * @param props Component props.
+ */
+export default function ResizeHandleWrapper( props: ResizeHandleProps ) {
+	const throttleDelay = 16;
+	const throttledResize = useThrottle( ( delta: ResizeDelta ) => {
+		if ( props.onResize ) {
+			props.onResize( delta );
+		}
+	}, throttleDelay );
+
+	// `event.delta` is the cursor offset from the gesture start —
+	// not from the handle's current position — so it stays stable
+	// even when the tile (and therefore the handle) jumps a column.
+	// The grid's resize logic snapshots the start width and adds
+	// `delta`, so the two must share the same frame of reference.
+	const handleDragMove = ( event: DragMoveEvent ) => {
+		if ( event.active.id !== 'draggable' ) {
+			return;
+		}
+		throttledResize( {
+			width: event.delta.x,
+			height: event.delta.y,
+		} );
+	};
+
+	const handleDragEnd = () => {
+		if ( props.onResizeEnd ) {
+			props.onResizeEnd();
+		}
+	};
+
+	return (
+		<DndContext
+			autoScroll={ {
+				threshold: { x: 0.005, y: 0.005 },
+				acceleration: 1,
+			} }
+			onDragMove={ handleDragMove }
+			onDragEnd={ handleDragEnd }
+		>
+			<div className={ styles[ 'resize-handle-slot' ] }>
+				<ResizeHandle { ...props } />
+			</div>
+		</DndContext>
+	);
+}

package/src/shared/resize-snap.ts

@@ -0,0 +1,63 @@
+import type { ResizeDelta } from './types';
+
+/**
+ * Pixel dimensions for the snapped resize preview outline.
+ */
+export type ResizeSnapSize = {
+	widthPx: number;
+	/** When `null`, the preview spans the item's content height (lanes). */
+	heightPx: number | null;
+};
+
+/**
+ * Clamps a resize delta so the tile cannot shrink below the given
+ * minimum width (and height when provided).
+ *
+ * @param delta              Cursor offset from the gesture start in pixels.
+ * @param initialSize        Size captured at gesture start.
+ * @param initialSize.width  Initial width in pixels.
+ * @param initialSize.height Initial height in pixels.
+ * @param minSize            Minimum tile size in pixels.
+ * @param minSize.width      Minimum width in pixels.
+ * @param minSize.height     Minimum height in pixels, when vertical resize applies.
+ */
+export function clampResizeDelta(
+	delta: ResizeDelta,
+	initialSize: { width: number; height: number },
+	minSize: { width: number; height?: number }
+): ResizeDelta {
+	const maxShrinkWidth = initialSize.width - minSize.width;
+	const width = Math.max( delta.width, -maxShrinkWidth );
+	if ( minSize.height === undefined ) {
+		return { ...delta, width };
+	}
+	const maxShrinkHeight = initialSize.height - minSize.height;
+	const height = Math.max( delta.height, -maxShrinkHeight );
+	return { width, height };
+}
+
+/**
+ * Converts grid spans to pixel width/height for the resize-preview
+ * outline, using the same track math the surface uses for placement.
+ *
+ * @param columnSpan  Number of columns the snap target spans.
+ * @param rowSpan     Number of rows the snap target spans.
+ * @param columnWidth Width of one column track in pixels.
+ * @param gapPx       Gap between tracks in pixels.
+ * @param rowHeightPx Row track height in pixels, or `null` when rows
+ *                    are content-sized.
+ */
+export function gridSpanToPixelSize(
+	columnSpan: number,
+	rowSpan: number,
+	columnWidth: number,
+	gapPx: number,
+	rowHeightPx: number | null
+): ResizeSnapSize {
+	const widthPx = columnSpan * columnWidth + ( columnSpan - 1 ) * gapPx;
+	const heightPx =
+		rowHeightPx === null
+			? null
+			: rowSpan * rowHeightPx + ( rowSpan - 1 ) * gapPx;
+	return { widthPx, heightPx };
+}

package/src/shared/test/resize-snap.test.ts

@@ -0,0 +1,35 @@
+import { clampResizeDelta, gridSpanToPixelSize } from '../resize-snap';
+
+describe( 'gridSpanToPixelSize', () => {
+	it( 'returns one column track width for a single-column span', () => {
+		expect( gridSpanToPixelSize( 1, 1, 100, 16, null ).widthPx ).toBe(
+			100
+		);
+	} );
+} );
+
+describe( 'clampResizeDelta', () => {
+	it( 'does not shrink width below one column', () => {
+		const initial = { width: 216, height: 120 };
+		const min = { width: 100, height: 48 };
+		expect(
+			clampResizeDelta( { width: -200, height: 0 }, initial, min )
+		).toEqual( { width: -116, height: 0 } );
+	} );
+
+	it( 'does not shrink height below one row when a minimum height is set', () => {
+		const initial = { width: 200, height: 144 };
+		const min = { width: 100, height: 48 };
+		expect(
+			clampResizeDelta( { width: 0, height: -120 }, initial, min )
+		).toEqual( { width: 0, height: -96 } );
+	} );
+
+	it( 'leaves growth deltas unchanged', () => {
+		const initial = { width: 100, height: 48 };
+		const min = { width: 100, height: 48 };
+		expect(
+			clampResizeDelta( { width: 80, height: 40 }, initial, min )
+		).toEqual( { width: 80, height: 40 } );
+	} );
+} );

package/src/shared/types.ts

@@ -0,0 +1,164 @@
+/**
+ * External dependencies
+ */
+import type { useDraggable } from '@dnd-kit/core';
+
+// `useDraggable`'s `listeners` and `attributes` types are not exported
+// from `@dnd-kit/core`'s public surface, so derive them from the hook
+// itself rather than via a deep import.
+type DraggableBindings = ReturnType< typeof useDraggable >;
+
+/**
+ * Cursor offset reported by the resize handle, in pixels relative to
+ * the gesture start. Width and height are independent so the surface
+ * can step columns and rows separately.
+ */
+export type ResizeDelta = {
+	width: number;
+	height: number;
+};
+
+/**
+ * Props received by a custom resize handle component. Spread `listeners`
+ * and `attributes` onto the element that should respond to the gesture,
+ * and assign `ref` to the same element so dnd-kit can track it.
+ */
+export interface ResizeHandleRenderProps {
+	/**
+	 * Ref callback to attach to the gesture-bearing element.
+	 */
+	ref: DraggableBindings[ 'setNodeRef' ];
+
+	/**
+	 * Pointer/keyboard event listeners that initiate the drag.
+	 */
+	listeners: DraggableBindings[ 'listeners' ];
+
+	/**
+	 * Accessibility and dnd-kit attributes (role, aria-*, tabIndex…).
+	 */
+	attributes: DraggableBindings[ 'attributes' ];
+
+	/**
+	 * Whether vertical resizing is allowed for this tile. Useful for
+	 * adapting the cursor or visual cue.
+	 */
+	verticalResizable: boolean;
+
+	/**
+	 * True while the user is actively dragging this handle. Use it to
+	 * swap colors, icons, or transforms during the gesture.
+	 */
+	isResizing: boolean;
+
+	/**
+	 * Owning item's `key`. Available so consumers can render per-tile
+	 * content if needed.
+	 */
+	itemId?: string;
+}
+
+/**
+ * Props received by a custom drag-preview component. The surface mounts
+ * the component inside `<DragOverlay>` and supplies the active tile's
+ * cloned children plus its `key`. The component is responsible for the
+ * visual chrome of the dragged clone (shadow, radius, padding); the
+ * surface keeps a thin functional wrapper around it that owns the lift
+ * cue, the cursor, and pointer pass-through during the gesture.
+ */
+export interface DragPreviewRenderProps {
+	/**
+	 * The cloned tile content the surface mounts inside the
+	 * `<DragOverlay>` portal. Render it where the visual wrapper
+	 * expects the tile body.
+	 */
+	children: React.ReactNode;
+
+	/**
+	 * Owning tile's `key`. Useful when the visual chrome needs to
+	 * vary by which tile is being dragged.
+	 */
+	itemId: string;
+}
+
+/**
+ * Props received by a custom grid overlay component. The overlay
+ * paints behind the tiles in edit mode to visualize the column tracks
+ * and (when `rowHeight` is defined) the row tracks. Receives a
+ * snapshot of the surface's resolved layout parameters so the visual
+ * can reproduce the tracks pixel-accurately without re-deriving them.
+ *
+ * Reused by both `DashboardGrid` and `DashboardLanes`: lanes pass no
+ * `rowHeight` because heights are content-driven.
+ */
+export interface GridOverlayRenderProps {
+	/**
+	 * Number of column tracks in the active surface. In responsive
+	 * mode (`minColumnWidth`), this is the count derived from the
+	 * container width, not the prop value.
+	 */
+	columns: number;
+
+	/**
+	 * Row height in pixels for surfaces with uniform rows. Omitted on
+	 * surfaces with content-driven heights (lanes) or when row height
+	 * is `'auto'`; in those cases row markers are omitted.
+	 */
+	rowHeight?: number;
+
+	/**
+	 * Number of row tracks to mirror in each column. Derived from the
+	 * grid container height when `rowHeight` is numeric; omitted when
+	 * row height is unknown.
+	 */
+	rows?: number;
+
+	/**
+	 * Whether the overlay should be visible. Surfaces render the
+	 * overlay even when `false` so the implementation can transition
+	 * opacity in and out; while `false`, the overlay must hide itself
+	 * (and ideally release paint cost via `visibility: hidden` or an
+	 * equivalent).
+	 */
+	isActive: boolean;
+}
+
+/**
+ * Props for the internal `<ResizeHandle />` wrapper.
+ */
+export interface ResizeHandleProps {
+	/**
+	 * Owning item's `key`. Forwarded as `data.itemId` on the draggable
+	 * so the parent can correlate the gesture with a tile if needed.
+	 */
+	itemId?: string;
+
+	/**
+	 * Whether the handle should track vertical movement. When false,
+	 * the handle still appears but only emits horizontal deltas, and
+	 * the cursor is constrained to the column resize axis.
+	 *
+	 * @default true
+	 */
+	verticalResizable?: boolean;
+
+	/**
+	 * Callback fired while the handle is being dragged. Receives the
+	 * cursor offset from the gesture start in pixels.
+	 */
+	onResize?: ( delta: ResizeDelta ) => void;
+
+	/**
+	 * Callback fired when the gesture ends.
+	 */
+	onResizeEnd?: () => void;
+
+	/**
+	 * Component that overrides the default corner triangle with a
+	 * custom element. Receives gesture wiring (`ref`, `listeners`,
+	 * `attributes`) plus context. The surface keeps ownership of the
+	 * `<DndContext>` and the throttled delta loop; consumers are only
+	 * responsible for the visual.
+	 */
+	renderResizeHandle?: React.ComponentType< ResizeHandleRenderProps >;
+}