@elementor/editor-canvas 4.2.0-926 → 4.2.0-928

package/src/components/grid-outline/__tests__/grid-outline.test.tsx

@@ -28,7 +28,7 @@ function getSvg( container: HTMLElement ): SVGSVGElement {
 describe( '<GridOutline />', () => {
 	it( 'sizes the svg to the element rect', () => {
 		const { container } = renderWithTheme(
-			<GridOutline tracks={ makeTracks( { columns: [ 100 ] } ) } width={ 320 } height={ 200 } />
+			<GridOutline element={ null } tracks={ makeTracks( { columns: [ 100 ] } ) } width={ 320 } height={ 200 } />
 		);
 
 		const svg = getSvg( container );
@@ -40,6 +40,7 @@ describe( '<GridOutline />', () => {
 		it( 'draws one line per unique boundary for an N×M grid', () => {
 			const { container } = renderWithTheme(
 				<GridOutline
+					element={ null }
 					tracks={ makeTracks( { columns: [ 100, 100, 100 ], rows: [ 80, 80 ] } ) }
 					width={ 300 }
 					height={ 160 }
@@ -53,6 +54,7 @@ describe( '<GridOutline />', () => {
 		it( 'snaps line coordinates to half pixels for crisp 1px strokes', () => {
 			const { container } = renderWithTheme(
 				<GridOutline
+					element={ null }
 					tracks={ makeTracks( {
 						columns: [ 100, 100 ],
 						rows: [ 80 ],
@@ -72,6 +74,7 @@ describe( '<GridOutline />', () => {
 		it( 'passes the resolved iframe border color through to each line', () => {
 			const { container } = renderWithTheme(
 				<GridOutline
+					element={ null }
 					tracks={ makeTracks( { columns: [ 100 ], rows: [ 100 ], borderColor: '#abcdef' } ) }
 					width={ 100 }
 					height={ 100 }
@@ -87,7 +90,7 @@ describe( '<GridOutline />', () => {
 
 		it( 'renders nothing when there are no tracks on either axis', () => {
 			const { container } = renderWithTheme(
-				<GridOutline tracks={ makeTracks() } width={ 100 } height={ 100 } />
+				<GridOutline element={ null } tracks={ makeTracks() } width={ 100 } height={ 100 } />
 			);
 
 			expect( container.querySelectorAll( 'line' ) ).toHaveLength( 0 );
@@ -95,10 +98,65 @@ describe( '<GridOutline />', () => {
 		} );
 	} );
 
+	describe( 'first-empty-cell indicator', () => {
+		it( 'renders a + glyph in the first empty cell when one exists', () => {
+			const element = document.createElement( 'div' );
+			document.body.appendChild( element );
+
+			const { container } = renderWithTheme(
+				<GridOutline
+					element={ element }
+					tracks={ makeTracks( { columns: [ 100, 100, 100 ], rows: [ 80, 80 ] } ) }
+					width={ 300 }
+					height={ 160 }
+				/>
+			);
+
+			expect( container.querySelector( '.eicon-plus' ) ).not.toBeNull();
+		} );
+
+		it( 'does not render the + glyph when the grid is fully occupied', () => {
+			const element = document.createElement( 'div' );
+
+			for ( let i = 0; i < 6; i++ ) {
+				const child = document.createElement( 'div' );
+				child.classList.add( 'elementor-element' );
+				element.appendChild( child );
+			}
+
+			document.body.appendChild( element );
+
+			const { container } = renderWithTheme(
+				<GridOutline
+					element={ element }
+					tracks={ makeTracks( { columns: [ 100, 100, 100 ], rows: [ 80, 80 ] } ) }
+					width={ 300 }
+					height={ 160 }
+				/>
+			);
+
+			expect( container.querySelector( '.eicon-plus' ) ).toBeNull();
+		} );
+
+		it( 'does not render the + glyph when no element is provided', () => {
+			const { container } = renderWithTheme(
+				<GridOutline
+					element={ null }
+					tracks={ makeTracks( { columns: [ 100 ], rows: [ 80 ] } ) }
+					width={ 100 }
+					height={ 80 }
+				/>
+			);
+
+			expect( container.querySelector( '.eicon-plus' ) ).toBeNull();
+		} );
+	} );
+
 	describe( 'with a gap', () => {
 		it( 'draws one rect per cell so each cell has its own framed perimeter', () => {
 			const { container } = renderWithTheme(
 				<GridOutline
+					element={ null }
 					tracks={ makeTracks( {
 						columns: [ 100, 100, 100 ],
 						rows: [ 80, 80 ],
@@ -117,6 +175,7 @@ describe( '<GridOutline />', () => {
 		it( 'offsets cells past the gap', () => {
 			const { container } = renderWithTheme(
 				<GridOutline
+					element={ null }
 					tracks={ makeTracks( {
 						columns: [ 100, 100, 100 ],
 						rows: [ 80 ],
@@ -134,6 +193,7 @@ describe( '<GridOutline />', () => {
 		it( 'passes the resolved iframe border color through to each cell', () => {
 			const { container } = renderWithTheme(
 				<GridOutline
+					element={ null }
 					tracks={ makeTracks( {
 						columns: [ 100, 100 ],
 						rows: [ 100 ],

package/src/components/grid-outline/first-empty-cell.tsx

@@ -0,0 +1,38 @@
+import * as React from 'react';
+
+import { type CellRect } from '../../utils/grid-outline-utils';
+
+const GLYPH_SIZE = 19;
+
+type Props = {
+	rect: CellRect;
+	color: string;
+};
+
+export function FirstEmptyCell( { rect, color }: Props ) {
+	const size = Math.min( GLYPH_SIZE, rect.width, rect.height );
+
+	if ( size <= 0 ) {
+		return null;
+	}
+
+	const centerX = rect.x + rect.width / 2;
+	const centerY = rect.y + rect.height / 2;
+
+	return (
+		<i
+			className="eicon-plus"
+			aria-hidden="true"
+			style={ {
+				position: 'absolute',
+				left: centerX,
+				top: centerY,
+				transform: 'translate(-50%, -50%)',
+				fontSize: size,
+				color,
+				lineHeight: 1,
+				pointerEvents: 'none',
+			} }
+		/>
+	);
+}

package/src/components/grid-outline/grid-outline-overlay.tsx

@@ -34,7 +34,7 @@ export const GridOutlineOverlay = ( { element, id, isSelected }: ElementOverlayP
 				data-grid-outline={ id }
 				role="presentation"
 			>
-				<GridOutline tracks={ tracks } width={ rect.width } height={ rect.height } />
+				<GridOutline element={ element } tracks={ tracks } width={ rect.width } height={ rect.height } />
 			</Box>
 		</FloatingPortal>
 	);

package/src/components/grid-outline/grid-outline.tsx

@@ -1,25 +1,29 @@
 import * as React from 'react';
+import { useMemo } from 'react';
 
 import { type GridTracks } from '../../hooks/use-grid-tracks';
-import { computeCellRects, computeGridLines, snapToHalfPixel } from '../../utils/grid-outline-utils';
+import { findFirstEmptyCell } from '../../utils/find-first-empty-cell';
+import { type CellRect, computeCellRects, computeGridLines, snapToHalfPixel } from '../../utils/grid-outline-utils';
 import { Cell } from './cell';
+import { FirstEmptyCell } from './first-empty-cell';
 import { Line } from './line';
 
 type Props = {
+	element: HTMLElement | null;
 	tracks: GridTracks;
 	width: number;
 	height: number;
 };
 
-const renderCells = ( tracks: GridTracks, width: number, height: number ) =>
-	computeCellRects( tracks, width, height ).map( ( cell, i ) => (
+const renderCells = ( cells: CellRect[], color: string ) =>
+	cells.map( ( cell, i ) => (
 		<Cell
 			key={ i }
 			x={ snapToHalfPixel( cell.x ) }
 			y={ snapToHalfPixel( cell.y ) }
 			width={ Math.round( cell.width ) }
 			height={ Math.round( cell.height ) }
-			color={ tracks.borderColor }
+			color={ color }
 		/>
 	) );
 
@@ -50,17 +54,29 @@ const renderLines = ( tracks: GridTracks, width: number, height: number ) => {
 	];
 };
 
-export function GridOutline( { tracks, width, height }: Props ) {
+export function GridOutline( { element, tracks, width, height }: Props ) {
+	const cells = useMemo( () => computeCellRects( tracks, width, height ), [ tracks, width, height ] );
 	const hasGap = tracks.columnGap > 0 || tracks.rowGap > 0;
+	const firstEmpty = useMemo(
+		() => findFirstEmptyCell( element, tracks.columns.length, tracks.rows.length ),
+		[ element, tracks ]
+	);
+	const emptyCellRect =
+		firstEmpty && tracks.columns.length > 0
+			? cells[ firstEmpty.row * tracks.columns.length + firstEmpty.col ]
+			: null;
 
 	return (
-		<svg
-			width={ width }
-			height={ height }
-			style={ { position: 'absolute', inset: 0, overflow: 'visible' } }
-			xmlns="http://www.w3.org/2000/svg"
-		>
-			{ hasGap ? renderCells( tracks, width, height ) : renderLines( tracks, width, height ) }
-		</svg>
+		<>
+			<svg
+				width={ width }
+				height={ height }
+				style={ { position: 'absolute', inset: 0, overflow: 'visible' } }
+				xmlns="http://www.w3.org/2000/svg"
+			>
+				{ hasGap ? renderCells( cells, tracks.borderColor ) : renderLines( tracks, width, height ) }
+			</svg>
+			{ emptyCellRect && <FirstEmptyCell rect={ emptyCellRect } color={ tracks.borderColor } /> }
+		</>
 	);
 }

package/src/hooks/use-toolbar-rect.ts

@@ -0,0 +1,30 @@
+const TOOLBAR_SELECTOR = ':scope > .elementor-element-overlay > .elementor-editor-element-settings';
+const WING_OVERHANG = 14;
+const OUTLINE_OVERHANG = 3;
+
+export type ToolbarCutoutRect = { x: number; y: number; width: number; height: number };
+
+export function useToolbarRect( element: HTMLElement | null, rect: DOMRect ): ToolbarCutoutRect | null {
+	if ( ! element ) {
+		return null;
+	}
+
+	const toolbar = element.querySelector( TOOLBAR_SELECTOR );
+
+	if ( ! toolbar ) {
+		return null;
+	}
+
+	const toolbarRect = toolbar.getBoundingClientRect();
+
+	if ( toolbarRect.width === 0 && toolbarRect.height === 0 ) {
+		return null;
+	}
+
+	return {
+		x: toolbarRect.left - rect.left - WING_OVERHANG,
+		y: toolbarRect.top - rect.top - OUTLINE_OVERHANG,
+		width: toolbarRect.width + WING_OVERHANG * 2,
+		height: toolbarRect.height + OUTLINE_OVERHANG * 2,
+	};
+}

package/src/legacy/create-pro-promotion-nested-type.ts

@@ -40,8 +40,11 @@ function createPromotionView( BaseView: typeof ElementView ): typeof ElementView
 		_afterRender() {
 			super._afterRender();
 
-			this.$el.off( 'click', '.e-form-placeholder__remove-btn' );
-			this.$el.on( 'click', '.e-form-placeholder__remove-btn', ( e: Event ) => {
+			const removeBtnSelector = '.e-pro-promotion-placeholder__remove-btn';
+			const unlockBtnSelector = '.e-pro-promotion-placeholder__unlock-btn';
+
+			this.$el.off( 'click', removeBtnSelector );
+			this.$el.on( 'click', removeBtnSelector, ( e: Event ) => {
 				e.preventDefault();
 				e.stopPropagation();
 
@@ -51,8 +54,8 @@ function createPromotionView( BaseView: typeof ElementView ): typeof ElementView
 				);
 			} );
 
-			this.$el.off( 'click', '.e-form-placeholder__unlock-btn' );
-			this.$el.on( 'click', '.e-form-placeholder__unlock-btn', ( e: Event ) => {
+			this.$el.off( 'click', unlockBtnSelector );
+			this.$el.on( 'click', unlockBtnSelector, ( e: Event ) => {
 				e.stopPropagation();
 			} );
 		}
@@ -75,8 +78,8 @@ function createPromotionView( BaseView: typeof ElementView ): typeof ElementView
 
 		onDestroy( ...args: unknown[] ) {
 			super.onDestroy( ...args );
-			this.$el.off( 'click', '.e-form-placeholder__remove-btn' );
-			this.$el.off( 'click', '.e-form-placeholder__unlock-btn' );
+			this.$el.off( 'click', '.e-pro-promotion-placeholder__remove-btn' );
+			this.$el.off( 'click', '.e-pro-promotion-placeholder__unlock-btn' );
 		}
 	} as unknown as typeof ElementView;
 }

package/src/utils/__tests__/find-first-empty-cell.test.ts

@@ -0,0 +1,132 @@
+import { findFirstEmptyCell } from '../find-first-empty-cell';
+
+type ChildSpec = {
+	gridColumnStart?: string;
+	gridColumnEnd?: string;
+	gridRowStart?: string;
+	gridRowEnd?: string;
+	display?: string;
+};
+
+function makeGrid( {
+	autoFlow = 'row',
+	children = [],
+}: { autoFlow?: string; children?: ChildSpec[] } = {} ): HTMLElement {
+	const element = document.createElement( 'div' );
+	element.style.gridAutoFlow = autoFlow;
+
+	for ( const spec of children ) {
+		const child = document.createElement( 'div' );
+		child.classList.add( 'elementor-element' );
+
+		if ( spec.gridColumnStart ) {
+			child.style.gridColumnStart = spec.gridColumnStart;
+		}
+		if ( spec.gridColumnEnd ) {
+			child.style.gridColumnEnd = spec.gridColumnEnd;
+		}
+		if ( spec.gridRowStart ) {
+			child.style.gridRowStart = spec.gridRowStart;
+		}
+		if ( spec.gridRowEnd ) {
+			child.style.gridRowEnd = spec.gridRowEnd;
+		}
+		if ( spec.display ) {
+			child.style.display = spec.display;
+		}
+
+		element.appendChild( child );
+	}
+
+	document.body.appendChild( element );
+	return element;
+}
+
+describe( 'findFirstEmptyCell', () => {
+	it( 'returns null when the element is null', () => {
+		expect( findFirstEmptyCell( null, 3, 3 ) ).toBeNull();
+	} );
+
+	it( 'returns null when either axis has zero tracks', () => {
+		const element = makeGrid();
+		expect( findFirstEmptyCell( element, 0, 3 ) ).toBeNull();
+		expect( findFirstEmptyCell( element, 3, 0 ) ).toBeNull();
+	} );
+
+	it( 'returns the first cell when the grid is empty', () => {
+		const element = makeGrid();
+		expect( findFirstEmptyCell( element, 3, 2 ) ).toEqual( { row: 0, col: 0 } );
+	} );
+
+	it( 'walks row-major when grid-auto-flow is row', () => {
+		const element = makeGrid( {
+			autoFlow: 'row',
+			children: [ {}, {} ],
+		} );
+		expect( findFirstEmptyCell( element, 3, 2 ) ).toEqual( { row: 0, col: 2 } );
+	} );
+
+	it( 'walks column-major when grid-auto-flow is column', () => {
+		const element = makeGrid( {
+			autoFlow: 'column',
+			children: [ {}, {} ],
+		} );
+		expect( findFirstEmptyCell( element, 3, 2 ) ).toEqual( { row: 0, col: 1 } );
+	} );
+
+	it( 'honors explicit grid-column-start / grid-row-start', () => {
+		const element = makeGrid( {
+			children: [ { gridColumnStart: '3', gridRowStart: '1' } ],
+		} );
+		expect( findFirstEmptyCell( element, 3, 2 ) ).toEqual( { row: 0, col: 0 } );
+	} );
+
+	it( 'skips cells covered by an explicit span', () => {
+		const element = makeGrid( {
+			children: [ { gridColumnStart: '1', gridColumnEnd: 'span 2' } ],
+		} );
+		expect( findFirstEmptyCell( element, 3, 2 ) ).toEqual( { row: 0, col: 2 } );
+	} );
+
+	it( 'skips rows covered by a row span', () => {
+		const element = makeGrid( {
+			children: [ { gridRowStart: '1', gridRowEnd: 'span 2' } ],
+		} );
+		expect( findFirstEmptyCell( element, 2, 2 ) ).toEqual( { row: 0, col: 1 } );
+	} );
+
+	it( 'auto-places remaining children around explicit placements', () => {
+		const element = makeGrid( {
+			children: [ { gridColumnStart: '2', gridRowStart: '1' }, {} ],
+		} );
+		expect( findFirstEmptyCell( element, 3, 2 ) ).toEqual( { row: 0, col: 2 } );
+	} );
+
+	it( 'returns null when the grid is fully occupied', () => {
+		const element = makeGrid( {
+			children: [ {}, {}, {}, {}, {}, {} ],
+		} );
+		expect( findFirstEmptyCell( element, 3, 2 ) ).toBeNull();
+	} );
+
+	it( 'ignores children with display: none', () => {
+		const element = makeGrid( {
+			children: [ { display: 'none' } ],
+		} );
+		expect( findFirstEmptyCell( element, 2, 1 ) ).toEqual( { row: 0, col: 0 } );
+	} );
+
+	it( 'ignores scaffolding children that are not .elementor-element', () => {
+		const element = makeGrid( { children: [ {} ] } );
+
+		const overlay = document.createElement( 'div' );
+		overlay.classList.add( 'elementor-element-overlay' );
+		element.insertBefore( overlay, element.firstChild );
+
+		const emptyView = document.createElement( 'div' );
+		emptyView.classList.add( 'elementor-empty-view' );
+		element.appendChild( emptyView );
+
+		expect( findFirstEmptyCell( element, 3, 1 ) ).toEqual( { row: 0, col: 1 } );
+	} );
+} );

package/src/utils/clip-path-cutout.ts

@@ -0,0 +1,11 @@
+type Size = { width: number; height: number };
+type CutoutRect = { x: number; y: number; width: number; height: number };
+
+export function rectCutoutClipPath( outer: Size, inner: CutoutRect ): string {
+	const { width: ow, height: oh } = outer;
+	const { x, y, width: iw, height: ih } = inner;
+
+	return `path(evenodd, 'M 0 0 L ${ ow } 0 L ${ ow } ${ oh } L 0 ${ oh } Z M ${ x } ${ y } L ${ x + iw } ${ y } L ${
+		x + iw
+	} ${ y + ih } L ${ x } ${ y + ih } L ${ x } ${ y } Z')`;
+}

package/src/utils/find-first-empty-cell.ts

@@ -0,0 +1,226 @@
+export type EmptyCell = {
+	row: number;
+	col: number;
+};
+
+type LineValue = 'auto' | number | { kind: 'span'; n: number };
+
+type ResolvedPlacement = {
+	start: number | null;
+	span: number;
+};
+
+export function findFirstEmptyCell(
+	element: HTMLElement | null,
+	columnCount: number,
+	rowCount: number
+): EmptyCell | null {
+	if ( ! element || columnCount === 0 || rowCount === 0 ) {
+		return null;
+	}
+
+	const previewWindow = element.ownerDocument?.defaultView;
+
+	if ( ! previewWindow ) {
+		return null;
+	}
+
+	const containerStyle = previewWindow.getComputedStyle( element );
+	const flowsByColumn = containerStyle.gridAutoFlow.trim().startsWith( 'column' );
+
+	const matrix: boolean[][] = Array.from( { length: rowCount }, () => new Array( columnCount ).fill( false ) );
+
+	const explicit: Array< { col: number | null; colSpan: number; row: number | null; rowSpan: number } > = [];
+	const autoPlaced: Array< { colSpan: number; rowSpan: number } > = [];
+
+	for ( const child of Array.from( element.children ) ) {
+		if ( ! child.classList.contains( 'elementor-element' ) ) {
+			continue;
+		}
+
+		const style = previewWindow.getComputedStyle( child );
+
+		if ( style.display === 'none' ) {
+			continue;
+		}
+
+		const col = resolvePlacement( style.gridColumnStart, style.gridColumnEnd );
+		const row = resolvePlacement( style.gridRowStart, style.gridRowEnd );
+
+		if ( col.start !== null || row.start !== null ) {
+			explicit.push( { col: col.start, colSpan: col.span, row: row.start, rowSpan: row.span } );
+		} else {
+			autoPlaced.push( { colSpan: col.span, rowSpan: row.span } );
+		}
+	}
+
+	for ( const child of explicit ) {
+		fillMatrix( matrix, child.col ?? 0, child.row ?? 0, child.colSpan, child.rowSpan );
+	}
+
+	for ( const child of autoPlaced ) {
+		const slot = findNextFreeSlot( matrix, child.colSpan, child.rowSpan, flowsByColumn );
+
+		if ( slot ) {
+			fillMatrix( matrix, slot.col, slot.row, child.colSpan, child.rowSpan );
+		}
+	}
+
+	return scanFirstEmpty( matrix, flowsByColumn );
+}
+
+function resolvePlacement( startRaw: string, endRaw: string ): ResolvedPlacement {
+	const start = parseLineValue( startRaw );
+	const end = parseLineValue( endRaw );
+
+	if ( typeof start === 'number' ) {
+		const zeroIndexedStart = start - 1;
+
+		if ( typeof end === 'number' ) {
+			return { start: zeroIndexedStart, span: Math.max( 1, end - start ) };
+		}
+
+		if ( isSpan( end ) ) {
+			return { start: zeroIndexedStart, span: end.n };
+		}
+
+		return { start: zeroIndexedStart, span: 1 };
+	}
+
+	if ( isSpan( start ) ) {
+		if ( typeof end === 'number' ) {
+			const zeroIndexedStart = end - 1 - start.n;
+			return { start: zeroIndexedStart >= 0 ? zeroIndexedStart : null, span: start.n };
+		}
+
+		return { start: null, span: start.n };
+	}
+
+	if ( typeof end === 'number' ) {
+		const zeroIndexedStart = end - 2;
+		return { start: zeroIndexedStart >= 0 ? zeroIndexedStart : null, span: 1 };
+	}
+
+	if ( isSpan( end ) ) {
+		return { start: null, span: end.n };
+	}
+
+	return { start: null, span: 1 };
+}
+
+function parseLineValue( raw: string ): LineValue {
+	const trimmed = raw.trim();
+
+	if ( trimmed === '' || trimmed === 'auto' ) {
+		return 'auto';
+	}
+
+	const spanMatch = trimmed.match( /^span\s+(\d+)$/ );
+
+	if ( spanMatch ) {
+		const n = parseInt( spanMatch[ 1 ], 10 );
+		return { kind: 'span', n: Math.max( 1, n ) };
+	}
+
+	const parsed = parseInt( trimmed, 10 );
+
+	if ( Number.isFinite( parsed ) && parsed > 0 ) {
+		return parsed;
+	}
+
+	return 'auto';
+}
+
+function isSpan( value: LineValue ): value is { kind: 'span'; n: number } {
+	return typeof value === 'object' && value !== null && 'kind' in value && value.kind === 'span';
+}
+
+function fillMatrix( matrix: boolean[][], col: number, row: number, colSpan: number, rowSpan: number ): void {
+	const rows = matrix.length;
+	const cols = rows > 0 ? matrix[ 0 ].length : 0;
+
+	const startRow = Math.max( 0, row );
+	const startCol = Math.max( 0, col );
+	const endRow = Math.min( rows, row + rowSpan );
+	const endCol = Math.min( cols, col + colSpan );
+
+	for ( let r = startRow; r < endRow; r++ ) {
+		for ( let c = startCol; c < endCol; c++ ) {
+			matrix[ r ][ c ] = true;
+		}
+	}
+}
+
+function findNextFreeSlot(
+	matrix: boolean[][],
+	colSpan: number,
+	rowSpan: number,
+	flowsByColumn: boolean
+): EmptyCell | null {
+	const rows = matrix.length;
+	const cols = rows > 0 ? matrix[ 0 ].length : 0;
+
+	const maxCol = cols - colSpan;
+	const maxRow = rows - rowSpan;
+
+	if ( maxCol < 0 || maxRow < 0 ) {
+		return null;
+	}
+
+	if ( flowsByColumn ) {
+		for ( let col = 0; col <= maxCol; col++ ) {
+			for ( let row = 0; row <= maxRow; row++ ) {
+				if ( canFit( matrix, col, row, colSpan, rowSpan ) ) {
+					return { row, col };
+				}
+			}
+		}
+	} else {
+		for ( let row = 0; row <= maxRow; row++ ) {
+			for ( let col = 0; col <= maxCol; col++ ) {
+				if ( canFit( matrix, col, row, colSpan, rowSpan ) ) {
+					return { row, col };
+				}
+			}
+		}
+	}
+
+	return null;
+}
+
+function canFit( matrix: boolean[][], col: number, row: number, colSpan: number, rowSpan: number ): boolean {
+	for ( let r = row; r < row + rowSpan; r++ ) {
+		for ( let c = col; c < col + colSpan; c++ ) {
+			if ( matrix[ r ][ c ] ) {
+				return false;
+			}
+		}
+	}
+
+	return true;
+}
+
+function scanFirstEmpty( matrix: boolean[][], flowsByColumn: boolean ): EmptyCell | null {
+	const rows = matrix.length;
+	const cols = rows > 0 ? matrix[ 0 ].length : 0;
+
+	if ( flowsByColumn ) {
+		for ( let col = 0; col < cols; col++ ) {
+			for ( let row = 0; row < rows; row++ ) {
+				if ( ! matrix[ row ][ col ] ) {
+					return { row, col };
+				}
+			}
+		}
+	} else {
+		for ( let row = 0; row < rows; row++ ) {
+			for ( let col = 0; col < cols; col++ ) {
+				if ( ! matrix[ row ][ col ] ) {
+					return { row, col };
+				}
+			}
+		}
+	}
+
+	return null;
+}