packages/block-editor/src/utils/math.ts - trunk - githubmirror/gutenberg

packages/block-editor/src/utils/math.ts
127 строк4 KB
Manzoor Wani
Block editor: Convert utility modules to TypeScript (#79323)
22 июн 2026, 20:17
22 июн 2026, 20:17296721d
/**
 * A string representing the name of an edge.
 */
type EdgeName = 'top' | 'right' | 'bottom' | 'left';

interface Point {
	/** The horizontal position. */
	x: number;
	/** The vertical position. */
	y: number;
}

/**
 * Given a point, a DOMRect and the name of an edge, returns the distance to
 * that edge of the rect.
 *
 * This function works for edges that are horizontal or vertical (e.g. not
 * rotated), the following terms are used so that the function works in both
 * orientations:
 *
 * - Forward, meaning the axis running horizontally when an edge is vertical
 *   and vertically when an edge is horizontal.
 * - Lateral, meaning the axis running vertically when an edge is vertical
 *   and horizontally when an edge is horizontal.
 *
 * @param point The point to measure distance from.
 * @param rect  A DOM Rect containing edge positions.
 * @param edge  The edge to measure to.
 */
export function getDistanceFromPointToEdge(
	point: Point,
	rect: DOMRect,
	edge: EdgeName
) {
	const isHorizontal = edge === 'top' || edge === 'bottom';
	const { x, y } = point;
	const pointLateralPosition = isHorizontal ? x : y;
	const pointForwardPosition = isHorizontal ? y : x;
	const edgeStart = isHorizontal ? rect.left : rect.top;
	const edgeEnd = isHorizontal ? rect.right : rect.bottom;
	const edgeForwardPosition = rect[ edge ];

	// Measure the straight line distance to the edge of the rect, when the
	// point is adjacent to the edge.
	// Else, if the point is positioned diagonally to the edge of the rect,
	// measure diagonally to the nearest corner that the edge meets.
	let edgeLateralPosition;
	if (
		pointLateralPosition >= edgeStart &&
		pointLateralPosition <= edgeEnd
	) {
		edgeLateralPosition = pointLateralPosition;
	} else if ( pointLateralPosition < edgeEnd ) {
		edgeLateralPosition = edgeStart;
	} else {
		edgeLateralPosition = edgeEnd;
	}

	return Math.sqrt(
		( pointLateralPosition - edgeLateralPosition ) ** 2 +
			( pointForwardPosition - edgeForwardPosition ) ** 2
	);
}

/**
 * Given a point, a DOMRect and a list of allowed edges returns the name of and
 * distance to the nearest edge.
 *
 * @param point        The point to measure distance from.
 * @param rect         A DOM Rect containing edge positions.
 * @param allowedEdges A list of the edges included in the
 *                     calculation. Defaults to all edges.
 *
 * @return An array where the first value is the distance
 *         and a second is the edge name.
 */
export function getDistanceToNearestEdge(
	point: Point,
	rect: DOMRect,
	allowedEdges: EdgeName[] = [ 'top', 'bottom', 'left', 'right' ]
) {
	let candidateDistance: number | undefined;
	let candidateEdge: EdgeName | undefined;

	allowedEdges.forEach( ( edge ) => {
		const distance = getDistanceFromPointToEdge( point, rect, edge );

		if ( candidateDistance === undefined || distance < candidateDistance ) {
			candidateDistance = distance;
			candidateEdge = edge;
		}
	} );

	return [ candidateDistance, candidateEdge ];
}

/**
 * Is the point contained by the rectangle.
 *
 * @param point The point.
 * @param rect  The rectangle.
 *
 * @return True if the point is contained by the rectangle, false otherwise.
 */
export function isPointContainedByRect( point: Point, rect: DOMRect ) {
	return (
		rect.left <= point.x &&
		rect.right >= point.x &&
		rect.top <= point.y &&
		rect.bottom >= point.y
	);
}

/**
 * Is the point within the top and bottom boundaries of the rectangle.
 *
 * @param point The point.
 * @param rect  The rectangle.
 *
 * @return True if the point is within top and bottom of rectangle, false otherwise.
 */
export function isPointWithinTopAndBottomBoundariesOfRect(
	point: Point,
	rect: DOMRect
) {
	return rect.top <= point.y && rect.bottom >= point.y;
}