@wordpress/grid 0.1.0

package/src/dashboard-grid/test/keyboard-activation.test.tsx

@@ -0,0 +1,76 @@
+/**
+ * @jest-environment jsdom
+ */
+
+/**
+ * External dependencies
+ */
+import { render } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import { DashboardGrid } from '..';
+
+class MockResizeObserver {
+	observed: Set< Element > = new Set();
+	observe( element: Element ) {
+		this.observed.add( element );
+	}
+	unobserve( element: Element ) {
+		this.observed.delete( element );
+	}
+	disconnect() {
+		this.observed.clear();
+	}
+}
+
+let originalResizeObserver: typeof ResizeObserver;
+
+beforeEach( () => {
+	originalResizeObserver = global.ResizeObserver;
+	( global as unknown as { ResizeObserver: unknown } ).ResizeObserver =
+		MockResizeObserver;
+} );
+
+afterEach( () => {
+	( global as unknown as { ResizeObserver: unknown } ).ResizeObserver =
+		originalResizeObserver;
+} );
+
+describe( 'DashboardGrid keyboard activation', () => {
+	it( 'places the dnd-kit keyboard activator on the inner wrapper, not the outer item', () => {
+		// Verifies the DOM hierarchy: keyboard activation needs the
+		// focused node and the keydown listener to share a node, so
+		// the activator must live nested inside the outer item.
+		/* eslint-disable testing-library/no-container, testing-library/no-node-access */
+		const { container } = render(
+			<DashboardGrid
+				layout={ [ { key: 'a', width: 1 } ] }
+				columns={ 2 }
+				editMode
+			>
+				<div key="a">A</div>
+			</DashboardGrid>
+		);
+
+		// Edit mode also renders a resize handle with `role="button"`;
+		// `aria-roledescription="sortable"` isolates the activator.
+		const activator = container.querySelector(
+			'[role="button"][aria-roledescription="sortable"]'
+		);
+		expect( activator ).not.toBeNull();
+		expect( activator ).toHaveAttribute( 'tabindex', '0' );
+
+		// Outer item is identified by its inline `grid-column-end`
+		// placement style; the activator must be its descendant.
+		const items = container.querySelectorAll(
+			'[style*="grid-column-end"]'
+		);
+		expect( items ).toHaveLength( 1 );
+		const item = items[ 0 ];
+		expect( activator ).not.toBe( item );
+		expect( item.contains( activator! ) ).toBe( true );
+		/* eslint-enable testing-library/no-container, testing-library/no-node-access */
+	} );
+} );

package/src/dashboard-grid/test/resolve-fill-widths.test.ts

@@ -0,0 +1,250 @@
+/**
+ * Internal dependencies
+ */
+import { resolveFillWidths } from '../resolve-fill-widths';
+import type { DashboardGridLayoutItem } from '../types';
+
+function makeMap(
+	items: DashboardGridLayoutItem[]
+): Map< string, DashboardGridLayoutItem > {
+	const map = new Map< string, DashboardGridLayoutItem >();
+	items.forEach( ( item ) => map.set( item.key, item ) );
+	return map;
+}
+
+function keys( items: DashboardGridLayoutItem[] ): string[] {
+	return items.map( ( item ) => item.key );
+}
+
+describe( 'resolveFillWidths', () => {
+	it( 'returns empty map when no items use width: "fill"', () => {
+		const items: DashboardGridLayoutItem[] = [
+			{ key: 'a', width: 2 },
+			{ key: 'b', width: 4 },
+		];
+		const result = resolveFillWidths( keys( items ), makeMap( items ), 6 );
+		expect( result.size ).toBe( 0 );
+	} );
+
+	it( 'fill item takes all columns when alone', () => {
+		const items: DashboardGridLayoutItem[] = [
+			{ key: 'fill', width: 'fill' },
+		];
+		const result = resolveFillWidths( keys( items ), makeMap( items ), 6 );
+		expect( result.get( 'fill' ) ).toBe( 6 );
+	} );
+
+	it( 'fill item takes remaining columns after fixed items', () => {
+		const items: DashboardGridLayoutItem[] = [
+			{ key: 'sidebar', width: 1 },
+			{ key: 'fill', width: 'fill' },
+		];
+		const result = resolveFillWidths( keys( items ), makeMap( items ), 6 );
+		expect( result.get( 'fill' ) ).toBe( 5 );
+	} );
+
+	it( 'fill item reserves space for subsequent fixed items', () => {
+		const items: DashboardGridLayoutItem[] = [
+			{ key: 'left', width: 1 },
+			{ key: 'fill', width: 'fill' },
+			{ key: 'right', width: 2 },
+		];
+		const result = resolveFillWidths( keys( items ), makeMap( items ), 6 );
+		expect( result.get( 'fill' ) ).toBe( 3 );
+	} );
+
+	it( 'fill after a full-width item starts a new row', () => {
+		const items: DashboardGridLayoutItem[] = [
+			{ key: 'full', width: 'full' },
+			{ key: 'fill', width: 'fill' },
+			{ key: 'sidebar', width: 1 },
+		];
+		const result = resolveFillWidths( keys( items ), makeMap( items ), 6 );
+		expect( result.get( 'fill' ) ).toBe( 5 );
+	} );
+
+	it( 'consecutive fills each take a full row', () => {
+		const items: DashboardGridLayoutItem[] = [
+			{ key: 'fill-1', width: 'fill' },
+			{ key: 'fill-2', width: 'fill' },
+		];
+		const result = resolveFillWidths( keys( items ), makeMap( items ), 6 );
+		expect( result.get( 'fill-1' ) ).toBe( 6 );
+		expect( result.get( 'fill-2' ) ).toBe( 6 );
+	} );
+
+	it( 'does not reserve items that overflow the row', () => {
+		const items: DashboardGridLayoutItem[] = [
+			{ key: 'fill', width: 'fill' },
+			{ key: 'a', width: 3 },
+			{ key: 'b', width: 4 },
+		];
+		const result = resolveFillWidths( keys( items ), makeMap( items ), 6 );
+		expect( result.get( 'fill' ) ).toBe( 3 );
+	} );
+
+	it( 'clamps item widths to maxColumns', () => {
+		const items: DashboardGridLayoutItem[] = [
+			{ key: 'fill', width: 'fill' },
+			{ key: 'wide', width: 10 },
+		];
+		const result = resolveFillWidths( keys( items ), makeMap( items ), 4 );
+		expect( result.get( 'fill' ) ).toBe( 4 );
+	} );
+
+	it( 'fill in the middle of a row', () => {
+		const items: DashboardGridLayoutItem[] = [
+			{ key: 'a', width: 1 },
+			{ key: 'b', width: 1 },
+			{ key: 'fill', width: 'fill' },
+			{ key: 'c', width: 1 },
+		];
+		const result = resolveFillWidths( keys( items ), makeMap( items ), 6 );
+		expect( result.get( 'fill' ) ).toBe( 3 );
+	} );
+
+	it( 'multiple fills in different rows', () => {
+		const items: DashboardGridLayoutItem[] = [
+			{ key: 'fill-1', width: 'fill' },
+			{ key: 'sidebar-1', width: 1 },
+			{ key: 'full', width: 'full' },
+			{ key: 'fill-2', width: 'fill' },
+			{ key: 'sidebar-2', width: 2 },
+		];
+		const result = resolveFillWidths( keys( items ), makeMap( items ), 6 );
+		expect( result.get( 'fill-1' ) ).toBe( 5 );
+		expect( result.get( 'fill-2' ) ).toBe( 4 );
+	} );
+
+	it( 'fill gets minimum of 1 column when row is almost full', () => {
+		const items: DashboardGridLayoutItem[] = [
+			{ key: 'a', width: 3 },
+			{ key: 'b', width: 2 },
+			{ key: 'fill', width: 'fill' },
+		];
+		const result = resolveFillWidths( keys( items ), makeMap( items ), 6 );
+		expect( result.get( 'fill' ) ).toBe( 1 );
+	} );
+
+	it( 'adapts to different column counts (responsive)', () => {
+		const items: DashboardGridLayoutItem[] = [
+			{ key: 'fill', width: 'fill' },
+			{ key: 'sidebar', width: 1 },
+		];
+		expect(
+			resolveFillWidths( keys( items ), makeMap( items ), 6 ).get(
+				'fill'
+			)
+		).toBe( 5 );
+		expect(
+			resolveFillWidths( keys( items ), makeMap( items ), 4 ).get(
+				'fill'
+			)
+		).toBe( 3 );
+		expect(
+			resolveFillWidths( keys( items ), makeMap( items ), 2 ).get(
+				'fill'
+			)
+		).toBe( 1 );
+	} );
+
+	it( 'look-ahead stops at the next fill boundary', () => {
+		const items: DashboardGridLayoutItem[] = [
+			{ key: 'fill-1', width: 'fill' },
+			{ key: 'fill-2', width: 'fill' },
+			{ key: 'sidebar', width: 1 },
+		];
+		const result = resolveFillWidths( keys( items ), makeMap( items ), 6 );
+		expect( result.get( 'fill-1' ) ).toBe( 6 );
+		expect( result.get( 'fill-2' ) ).toBe( 5 );
+	} );
+
+	it( 'look-ahead stops at the next full-width boundary', () => {
+		const items: DashboardGridLayoutItem[] = [
+			{ key: 'fill', width: 'fill' },
+			{ key: 'full', width: 'full' },
+			{ key: 'sidebar', width: 1 },
+		];
+		const result = resolveFillWidths( keys( items ), makeMap( items ), 6 );
+		expect( result.get( 'fill' ) ).toBe( 6 );
+	} );
+
+	it( 'every item gets 1 column when maxColumns is 1', () => {
+		const items: DashboardGridLayoutItem[] = [
+			{ key: 'a', width: 3 },
+			{ key: 'fill', width: 'fill' },
+			{ key: 'b', width: 2 },
+		];
+		const result = resolveFillWidths( keys( items ), makeMap( items ), 1 );
+		expect( result.get( 'fill' ) ).toBe( 1 );
+	} );
+
+	it( 'returns empty map for an empty layout', () => {
+		const result = resolveFillWidths( [], new Map(), 6 );
+		expect( result.size ).toBe( 0 );
+	} );
+
+	describe( 'with multi-row items (height > 1)', () => {
+		it( 'accounts for the shadow of a tall tile on the left', () => {
+			const items: DashboardGridLayoutItem[] = [
+				{ key: 'tall', width: 3, height: 2 },
+				{ key: 'header', width: 9, height: 1 },
+				{ key: 'sub', width: 3, height: 1 },
+				{ key: 'fill', width: 'fill', height: 1 },
+			];
+			const result = resolveFillWidths(
+				keys( items ),
+				makeMap( items ),
+				12
+			);
+			expect( result.get( 'fill' ) ).toBe( 6 );
+		} );
+
+		it( 'accounts for the shadow of a tall tile in the middle', () => {
+			const items: DashboardGridLayoutItem[] = [
+				{ key: 'a', width: 3, height: 1 },
+				{ key: 'b', width: 3, height: 2 },
+				{ key: 'c', width: 6, height: 1 },
+				{ key: 'd', width: 3, height: 1 },
+				{ key: 'fill', width: 'fill', height: 1 },
+			];
+			const result = resolveFillWidths(
+				keys( items ),
+				makeMap( items ),
+				12
+			);
+			expect( result.get( 'fill' ) ).toBe( 6 );
+		} );
+
+		it( 'accounts for the shadow of a tall tile on the right', () => {
+			const items: DashboardGridLayoutItem[] = [
+				{ key: 'a', width: 3, height: 1 },
+				{ key: 'b', width: 6, height: 1 },
+				{ key: 'c', width: 3, height: 2 },
+				{ key: 'd', width: 6, height: 1 },
+				{ key: 'fill', width: 'fill', height: 1 },
+			];
+			const result = resolveFillWidths(
+				keys( items ),
+				makeMap( items ),
+				12
+			);
+			expect( result.get( 'fill' ) ).toBe( 3 );
+		} );
+
+		it( 'tracks shadow across multiple rows for height > 2', () => {
+			const items: DashboardGridLayoutItem[] = [
+				{ key: 'tall', width: 3, height: 3 },
+				{ key: 'a', width: 9, height: 1 },
+				{ key: 'b', width: 9, height: 1 },
+				{ key: 'fill', width: 'fill', height: 1 },
+			];
+			const result = resolveFillWidths(
+				keys( items ),
+				makeMap( items ),
+				12
+			);
+			expect( result.get( 'fill' ) ).toBe( 9 );
+		} );
+	} );
+} );

package/src/dashboard-grid/types.ts

@@ -0,0 +1,271 @@
+/**
+ * Internal dependencies
+ */
+import type {
+	DragPreviewRenderProps,
+	GridOverlayRenderProps,
+	ResizeDelta,
+	ResizeHandleRenderProps,
+} from '../shared/types';
+import type { ResizeSnapSize } from '../shared/resize-snap';
+
+/**
+ * Dashboard grid layout item definition.
+ *
+ * `width` accepts either a numeric column span or a discriminated string:
+ * - `number` spans that many columns (clamped to the grid's column count).
+ * - `'fill'` spans the remaining columns in the current row.
+ * - `'full'` spans all columns (`grid-column: 1 / -1`).
+ */
+export type DashboardGridLayoutItem = {
+	/**
+	 * Unique key that matches a child component key.
+	 */
+	key: string;
+
+	/**
+	 * Number of columns this item spans, or a string discriminator
+	 * (`'fill'` or `'full'`).
+	 */
+	width?: number | 'fill' | 'full';
+
+	/**
+	 * Number of rows this item spans.
+	 *
+	 * @default 1
+	 */
+	height?: number;
+
+	/**
+	 * Display order for the item. Lower values render first. When
+	 * omitted, the item falls back to its index in the `layout` array.
+	 */
+	order?: number;
+};
+
+/**
+ * Props for the internal `<GridItem />` wrapper.
+ */
+export type GridItemProps = {
+	/**
+	 * The layout item containing grid positioning information.
+	 */
+	item: DashboardGridLayoutItem;
+
+	/**
+	 * The maximum number of columns in the grid.
+	 */
+	maxColumns: number;
+
+	/**
+	 * Whether drag and resize interactions are disabled.
+	 *
+	 * @default false
+	 */
+	disabled?: boolean;
+
+	/**
+	 * Whether the item can be resized vertically. Disabled when the
+	 * grid uses `rowHeight: 'auto'`, where row height is driven by
+	 * content rather than by the user.
+	 *
+	 * @default true
+	 */
+	verticalResizable?: boolean;
+
+	/**
+	 * Whether any tile in the grid is currently being dragged or
+	 * resized. Drives the drag activator cursor.
+	 *
+	 * @default false
+	 */
+	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;
+
+	/**
+	 * The content to be displayed within the grid item.
+	 */
+	children: React.ReactNode;
+
+	/**
+	 * Content rendered above the draggable area that stays interactive
+	 * in edit mode, typically action buttons, menus, or links. While
+	 * a tile drag is in progress, this content is set `inert` so hovers
+	 * on other tiles can't steal the gesture. During resize, visibility
+	 * is controlled by grid-level CSS hooks.
+	 */
+	actionableArea?: React.ReactNode;
+
+	/**
+	 * Callback fired while the item is being resized. Receives the
+	 * item's `key` plus the cursor offset from the gesture start in
+	 * pixels. The grid derives snapped spans from the delta and passes
+	 * them back through `resizeSnapPreview`.
+	 */
+	onResize: ( id: string, delta: ResizeDelta ) => void;
+
+	/**
+	 * Snapped grid size in pixels for the resize-preview outline. The
+	 * tile content resizes continuously with the cursor; this outline
+	 * shows the span the layout will commit to on release.
+	 */
+	resizeSnapPreview?: ResizeSnapSize | null;
+
+	/**
+	 * Minimum tile width while resizing, in pixels (one column track).
+	 */
+	minResizeWidthPx: number;
+
+	/**
+	 * Minimum tile height while resizing, in pixels (one row track).
+	 * Omitted when vertical resize is disabled.
+	 */
+	minResizeHeightPx?: number;
+
+	/**
+	 * Callback fired when the resize gesture ends.
+	 */
+	onResizeEnd: () => void;
+
+	/**
+	 * Component forwarded to `<ResizeHandle />` to override the default
+	 * corner triangle. See `DashboardGridProps.renderResizeHandle`.
+	 */
+	renderResizeHandle?: React.ComponentType< ResizeHandleRenderProps >;
+};
+
+/**
+ * Props for `DashboardGrid`. Extends the standard div props so consumers
+ * can pass `id`, `aria-*`, `data-*`, event handlers, etc., directly on
+ * the grid root.
+ *
+ * `columns` and `minColumnWidth` compose as a layered model:
+ * - `columns` alone: fixed N columns; each tile scales with the container.
+ * - `minColumnWidth` alone: column count derives from container width,
+ *   floored by the per-tile minimum, down to 1 column.
+ * - Both together: `columns` caps the count, `minColumnWidth` enforces a
+ *   per-tile width floor that can reduce the count below the cap on
+ *   narrow containers ("up to N columns, but never narrower than W px").
+ */
+export interface DashboardGridProps
+	extends Omit<
+		React.ComponentPropsWithoutRef< 'div' >,
+		'children' | 'className' | 'style'
+	> {
+	/**
+	 * Array of layout items.
+	 */
+	layout: DashboardGridLayoutItem[];
+
+	/**
+	 * Grid children. Each child must carry a `key` that matches an
+	 * entry in `layout`; children without a match render at the end
+	 * of the grid without explicit placement and fall through CSS
+	 * Grid's auto-flow.
+	 */
+	children: React.ReactNode;
+
+	/**
+	 * Additional CSS class on the grid root.
+	 */
+	className?: string;
+
+	/**
+	 * Inline styles applied to the grid root. Merged underneath the
+	 * grid's own layout styles, so the layout (`gridTemplateColumns`,
+	 * `gridAutoRows`) always wins. 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;
+
+	/**
+	 * Height of each row in pixels, or `'auto'` to let the tallest
+	 * tile in the row size it.
+	 *
+	 * @default 'auto'
+	 */
+	rowHeight?: number | 'auto';
+
+	/**
+	 * Whether the grid is in edit mode (allows dragging and
+	 * repositioning items).
+	 *
+	 * @default false
+	 */
+	editMode?: boolean;
+
+	/**
+	 * Callback fired when the user commits a drag or resize. Receives
+	 * the resulting layout.
+	 */
+	onChangeLayout?: ( newLayout: DashboardGridLayoutItem[] ) => void;
+
+	/**
+	 * Callback fired continuously during a drag or resize interaction
+	 * with the in-progress layout. Useful for live feedback in the
+	 * surface (e.g., displaying the current width/position). The final
+	 * committed layout is still emitted via `onChangeLayout`.
+	 */
+	onPreviewLayout?: ( previewLayout: DashboardGridLayoutItem[] ) => void;
+
+	/**
+	 * Override the default corner-triangle resize handle with a custom
+	 * component. The grid still owns the gesture (dnd-kit `<DndContext>`,
+	 * throttled delta loop) and passes the wiring to the consumer:
+	 * spread `listeners` and `attributes` and assign `ref` on the
+	 * element that should receive the gesture. Use `disabled` and
+	 * `verticalResizable` to adapt the visual to context.
+	 */
+	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 (row-marker tiles per
+	 * column) with a custom component. The grid supplies the resolved
+	 * column count, row height, and row count; the consumer is
+	 * responsible for the visual.
+	 *
+	 * The overlay only renders when `editMode` is true. When omitted,
+	 * the package's default visual is used.
+	 */
+	renderGridOverlay?: React.ComponentType< GridOverlayRenderProps >;
+
+	/**
+	 * Target column 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
+	 * column count derives from container width, floored by this value,
+	 * down to 1.
+	 */
+	minColumnWidth?: number;
+}