@wordpress/grid 0.1.0

package/src/dashboard-lanes/test/use-lane-placement.test.tsx

@@ -0,0 +1,358 @@
+/**
+ * @jest-environment jsdom
+ */
+
+/**
+ * External dependencies
+ */
+import { render, act, screen } from '@testing-library/react';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { GRID_ITEM_DATA_KEY } from '../../shared/grid-item-key';
+import { useLanePlacement } from '../use-lane-placement';
+import type {
+	UseLanePlacementInput,
+	UseLanePlacementResult,
+} from '../use-lane-placement';
+
+type Entry = {
+	target: Element;
+	contentRect: { height: number; width: number };
+};
+
+class MockResizeObserver {
+	static instances: MockResizeObserver[] = [];
+	static lastInstance(): MockResizeObserver | undefined {
+		return MockResizeObserver.instances[
+			MockResizeObserver.instances.length - 1
+		];
+	}
+	static reset() {
+		MockResizeObserver.instances = [];
+	}
+
+	callback: ResizeObserverCallback;
+	observed: Set< Element > = new Set();
+	disconnected = false;
+
+	constructor( callback: ResizeObserverCallback ) {
+		this.callback = callback;
+		MockResizeObserver.instances.push( this );
+	}
+	observe( element: Element ) {
+		this.observed.add( element );
+	}
+	unobserve( element: Element ) {
+		this.observed.delete( element );
+	}
+	disconnect() {
+		this.observed.clear();
+		this.disconnected = true;
+	}
+	fire( entries: Entry[] ) {
+		this.callback(
+			entries as unknown as ResizeObserverEntry[],
+			this as unknown as ResizeObserver
+		);
+	}
+}
+
+let originalResizeObserver: typeof ResizeObserver;
+let originalSupports: typeof CSS.supports | undefined;
+let originalRaf: typeof requestAnimationFrame;
+
+function installMockObserver() {
+	originalResizeObserver = global.ResizeObserver;
+	MockResizeObserver.reset();
+	( global as unknown as { ResizeObserver: unknown } ).ResizeObserver =
+		MockResizeObserver;
+}
+
+function restoreObserver() {
+	( global as unknown as { ResizeObserver: unknown } ).ResizeObserver =
+		originalResizeObserver;
+}
+
+function setNativeSupport( supported: boolean ) {
+	if ( typeof CSS === 'undefined' ) {
+		( global as unknown as { CSS: unknown } ).CSS = {
+			supports: () => supported,
+		};
+		return;
+	}
+	originalSupports = CSS.supports;
+	CSS.supports = ( property: string, value?: string ) => {
+		if ( property === 'display' && value === 'grid-lanes' ) {
+			return supported;
+		}
+		return originalSupports
+			? originalSupports.call( CSS, property, value as string )
+			: false;
+	};
+}
+
+function restoreSupport() {
+	if ( originalSupports ) {
+		CSS.supports = originalSupports;
+		originalSupports = undefined;
+	}
+}
+
+function flushRaf() {
+	// jsdom polyfills `requestAnimationFrame` via `setTimeout`; an
+	// `act` boundary lets React commit any state set inside the rAF.
+	jest.runAllTimers();
+}
+
+beforeEach( () => {
+	installMockObserver();
+	originalRaf = global.requestAnimationFrame;
+	global.requestAnimationFrame = ( cb ) =>
+		setTimeout( () => cb( performance.now() ), 0 ) as unknown as number;
+	jest.useFakeTimers();
+} );
+
+afterEach( () => {
+	jest.useRealTimers();
+	global.requestAnimationFrame = originalRaf;
+	restoreObserver();
+	restoreSupport();
+} );
+
+type HarnessProps = {
+	input: UseLanePlacementInput;
+	measuredHeights?: Record< string, number >;
+	onResult?: ( result: UseLanePlacementResult ) => void;
+};
+
+function Harness( { input, measuredHeights, onResult }: HarnessProps ) {
+	const [ container, setContainer ] = useState< HTMLDivElement | null >(
+		null
+	);
+	const result = useLanePlacement( container, input );
+	if ( onResult ) {
+		onResult( result );
+	}
+	return (
+		<div ref={ setContainer } data-testid="container">
+			{ input.items.map( ( item ) => (
+				<div
+					key={ item.key }
+					{ ...{ [ GRID_ITEM_DATA_KEY ]: item.key } }
+					data-testid={ `item-${ item.key }` }
+					style={ {
+						...result.itemStyles.get( item.key ),
+						height: measuredHeights?.[ item.key ] ?? 0,
+					} }
+				/>
+			) ) }
+		</div>
+	);
+}
+
+function captureLatestResult() {
+	let latest: UseLanePlacementResult | null = null;
+	const onResult = ( result: UseLanePlacementResult ) => {
+		latest = result;
+	};
+	const get = (): UseLanePlacementResult => {
+		if ( ! latest ) {
+			throw new Error( 'Hook never produced a result' );
+		}
+		return latest;
+	};
+	return { onResult, get };
+}
+
+function fireMeasurements( heights: Record< string, number > ) {
+	const observer = MockResizeObserver.lastInstance();
+	if ( ! observer ) {
+		throw new Error( 'No ResizeObserver instance registered' );
+	}
+	const entries: Entry[] = [];
+	for ( const [ key, height ] of Object.entries( heights ) ) {
+		const element = screen.getByTestId( `item-${ key }` );
+		entries.push( {
+			target: element,
+			contentRect: { height, width: 0 },
+		} );
+	}
+	act( () => {
+		observer.fire( entries );
+		flushRaf();
+	} );
+}
+
+describe( 'useLanePlacement', () => {
+	describe( 'native support', () => {
+		it( 'returns isPolyfilled=false and span-only styles when supported', () => {
+			setNativeSupport( true );
+			const { onResult, get } = captureLatestResult();
+
+			render(
+				<Harness
+					input={ {
+						items: [
+							{ key: 'a', span: 1 },
+							{ key: 'b', span: 2 },
+						],
+						lanes: 3,
+						gap: 16,
+						flowTolerance: 0,
+					} }
+					onResult={ onResult }
+				/>
+			);
+			act( () => {
+				flushRaf();
+			} );
+
+			const result = get();
+			expect( result.isPolyfilled ).toBe( false );
+			expect( result.itemStyles.get( 'a' ) ).toEqual( {
+				gridColumn: 'span 1',
+			} );
+			expect( result.itemStyles.get( 'b' ) ).toEqual( {
+				gridColumn: 'span 2',
+			} );
+			// No observers should have been instantiated.
+			expect( MockResizeObserver.instances.length ).toBe( 0 );
+		} );
+	} );
+
+	describe( 'polyfill path', () => {
+		it( 'returns native-shape styles before measurement completes', () => {
+			setNativeSupport( false );
+			const { onResult, get } = captureLatestResult();
+
+			render(
+				<Harness
+					input={ {
+						items: [
+							{ key: 'a', span: 1 },
+							{ key: 'b', span: 2 },
+						],
+						lanes: 3,
+						gap: 16,
+						flowTolerance: 0,
+					} }
+					onResult={ onResult }
+				/>
+			);
+
+			const result = get();
+			expect( result.isPolyfilled ).toBe( true );
+			expect( result.itemStyles.get( 'a' ) ).toEqual( {
+				gridColumn: 'span 1',
+			} );
+		} );
+
+		it( 'observes children and emits placement styles after measurement', () => {
+			setNativeSupport( false );
+			const { onResult, get } = captureLatestResult();
+
+			render(
+				<Harness
+					input={ {
+						items: [
+							{ key: 'a', span: 1 },
+							{ key: 'b', span: 1 },
+							{ key: 'c', span: 1 },
+						],
+						lanes: 3,
+						gap: 0,
+						flowTolerance: 0,
+						rowUnit: 4,
+					} }
+					onResult={ onResult }
+				/>
+			);
+
+			// One ResizeObserver should have been constructed for the
+			// container's children.
+			expect( MockResizeObserver.instances.length ).toBe( 1 );
+			const observer = MockResizeObserver.lastInstance();
+			expect( observer?.observed.size ).toBe( 3 );
+
+			fireMeasurements( {
+				a: 100,
+				b: 80,
+				c: 60,
+			} );
+
+			const result = get();
+			expect( result.isPolyfilled ).toBe( true );
+
+			// All three items should land in lane 0/1/2 respectively
+			// (zero baselines), at row 1.
+			const a = result.itemStyles.get( 'a' )!;
+			const b = result.itemStyles.get( 'b' )!;
+			const c = result.itemStyles.get( 'c' )!;
+			expect( a.gridColumnStart ).toBe( 1 );
+			expect( a.gridRowStart ).toBe( 1 );
+			expect( a.gridRowEnd ).toBe( 'span 25' ); // 100 / 4
+			expect( b.gridColumnStart ).toBe( 2 );
+			expect( b.gridRowEnd ).toBe( 'span 20' ); // 80 / 4
+			expect( c.gridColumnStart ).toBe( 3 );
+			expect( c.gridRowEnd ).toBe( 'span 15' ); // 60 / 4
+		} );
+
+		it( 'recomputes when an item resizes', () => {
+			setNativeSupport( false );
+			const { onResult, get } = captureLatestResult();
+
+			render(
+				<Harness
+					input={ {
+						items: [
+							{ key: 'a', span: 1 },
+							{ key: 'b', span: 1 },
+						],
+						lanes: 1,
+						gap: 0,
+						flowTolerance: 0,
+						rowUnit: 4,
+					} }
+					onResult={ onResult }
+				/>
+			);
+
+			fireMeasurements( { a: 100, b: 50 } );
+			expect( get().itemStyles.get( 'b' )?.gridRowStart ).toBe( 26 ); // 100/4 + 1
+
+			fireMeasurements( { a: 200 } );
+			expect( get().itemStyles.get( 'b' )?.gridRowStart ).toBe( 51 ); // 200/4 + 1
+		} );
+	} );
+
+	describe( 'cleanup', () => {
+		it( 'disconnects observers on unmount', () => {
+			setNativeSupport( false );
+
+			const { unmount } = render(
+				<Harness
+					input={ {
+						items: [ { key: 'a', span: 1 } ],
+						lanes: 3,
+						gap: 16,
+						flowTolerance: 0,
+					} }
+				/>
+			);
+
+			const observer = MockResizeObserver.lastInstance();
+			expect( observer ).toBeDefined();
+			expect( observer!.disconnected ).toBe( false );
+
+			unmount();
+			expect( observer!.disconnected ).toBe( true );
+		} );
+	} );
+} );

package/src/dashboard-lanes/types.ts

@@ -0,0 +1,176 @@
+/**
+ * Internal dependencies
+ */
+import type {
+	DragPreviewRenderProps,
+	GridOverlayRenderProps,
+	ResizeHandleRenderProps,
+} from '../shared/types';
+
+/**
+ * Lanes layout item definition.
+ *
+ * Mirrors the public surface of `display: grid-lanes`: column span,
+ * an optional pinned lane, and an optional source order. Heights are
+ * content-driven; there is no `height` field. There is no `'fill'`
+ * (lanes pack their items by skyline; nothing is "left over").
+ * `'full'` is expressed by setting `width` to the lane count.
+ */
+export type DashboardLanesLayoutItem = {
+	/**
+	 * Unique key that matches a child component key.
+	 */
+	key: string;
+
+	/**
+	 * Number of lanes this item spans (`grid-column: span N`). Clamped
+	 * to the surface's lane count.
+	 *
+	 * @default 1
+	 */
+	width?: number;
+
+	/**
+	 * Pin the item to a specific 0-indexed lane. Pinned items are
+	 * placed before auto items, so the auto flow runs around them.
+	 * Out-of-range values (negative, or beyond `columns - width`) are
+	 * clamped to the available range.
+	 */
+	lane?: number;
+
+	/**
+	 * Display order. Lower values render first. When omitted, the
+	 * item falls back to its index in the `layout` array.
+	 */
+	order?: number;
+};
+
+/**
+ * Props for `DashboardLanes`.
+ *
+ * `columns` and `minColumnWidth` compose as a layered model:
+ * - `columns` alone: fixed N lanes; tiles scale with the container.
+ * - `minColumnWidth` alone: lane count derives from container width,
+ *   floored by the per-tile minimum, down to 1.
+ * - Both together: `columns` caps the count, `minColumnWidth` enforces
+ *   a per-tile width floor that can reduce the count below the cap.
+ */
+export interface DashboardLanesProps
+	extends Omit<
+		React.ComponentPropsWithoutRef< 'div' >,
+		'children' | 'className' | 'style'
+	> {
+	/**
+	 * Array of layout items.
+	 */
+	layout: DashboardLanesLayoutItem[];
+
+	/**
+	 * Surface children. Each child must carry a `key` matching an
+	 * entry in `layout`; children without a match render at the end
+	 * of the surface without explicit placement and fall through the
+	 * lanes auto-flow.
+	 */
+	children: React.ReactNode;
+
+	/**
+	 * Additional CSS class on the surface root.
+	 */
+	className?: string;
+
+	/**
+	 * Inline styles on the surface root. Merged underneath the
+	 * surface's own layout styles, so `display` and
+	 * `gridTemplateColumns` always win. The gap between tiles is
+	 * owned by the design-system gap token and is not configurable
+	 * per instance; override it via a theme or density change.
+	 */
+	style?: React.CSSProperties;
+
+	/**
+	 * `flow-tolerance` value in pixels. When two candidate lanes
+	 * differ in baseline by no more than this, the earlier lane wins
+	 * to preserve source order. Larger values keep tiles closer to
+	 * reading order at the cost of bigger empty regions.
+	 *
+	 * @default 16
+	 */
+	flowTolerance?: number;
+
+	/**
+	 * Snap unit for the polyfill's `grid-row-start` / `grid-row-end:
+	 * span N` math. Smaller values produce sharper placement at the
+	 * cost of a larger implicit row count. Ignored on browsers with
+	 * native `display: grid-lanes` support.
+	 *
+	 * @default 4
+	 */
+	rowUnit?: number;
+
+	/**
+	 * Whether the surface is in edit mode (drag-to-reorder, resize).
+	 *
+	 * @default false
+	 */
+	editMode?: boolean;
+
+	/**
+	 * Fired when the user commits a drag or resize.
+	 */
+	onChangeLayout?: ( newLayout: DashboardLanesLayoutItem[] ) => void;
+
+	/**
+	 * Fired continuously during a gesture with the in-progress
+	 * layout. The committed result still emits via `onChangeLayout`.
+	 */
+	onPreviewLayout?: ( previewLayout: DashboardLanesLayoutItem[] ) => void;
+
+	/**
+	 * Override the default corner resize handle. See `DashboardGrid`
+	 * for the full contract; on lanes the handle is horizontal-only
+	 * because heights are content-driven.
+	 */
+	renderResizeHandle?: React.ComponentType< ResizeHandleRenderProps >;
+
+	/**
+	 * Custom wrapper for the dragged-clone visual mounted inside
+	 * `<DragOverlay>`. The surface always wraps the clone with a thin
+	 * functional frame (lift scale, grabbing cursor, pointer pass-
+	 * through) and mounts this component inside it; the consumer
+	 * owns the visual chrome (shadow, radius, padding).
+	 *
+	 * When omitted, the cloned children render directly inside the
+	 * functional frame so any chrome the consumer applied to the
+	 * persistent tile carries through unchanged.
+	 *
+	 * Token-only adjustments (lift scale, placeholder opacity,
+	 * outline color, placeholder radius) flow through CSS custom
+	 * properties documented in the README.
+	 */
+	renderDragPreview?: React.ComponentType< DragPreviewRenderProps >;
+
+	/**
+	 * Override the default edit-mode overlay (empty column tracks) with
+	 * a custom component. Lanes are content-driven vertically, so no
+	 * `rowHeight` or `rows` is supplied and the default visual paints
+	 * columns only.
+	 *
+	 * The overlay only renders when `editMode` is true. When omitted,
+	 * the package's default visual is used.
+	 */
+	renderGridOverlay?: React.ComponentType< GridOverlayRenderProps >;
+
+	/**
+	 * Target lane count, used as a cap. Defaults to six when neither
+	 * `columns` nor `minColumnWidth` is set; with `minColumnWidth` set
+	 * it can resolve lower on narrow containers.
+	 */
+	columns?: number;
+
+	/**
+	 * Per-tile minimum width in pixels. Enables responsive mode: the
+	 * lane count derives from container width, floored by this value,
+	 * down to 1.
+	 */
+	minColumnWidth?: number;
+}