tiny-essentials
Version:
Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.
187 lines • 6.01 kB
text/typescript
/**
* Calculates the offset between the center of rect2 and the center of rect1.
*
* The values will be 0 when rect1 is perfectly centered over rect2.
*
* @param {ObjRect} rect1 - The bounding rectangle of the reference element.
* @param {ObjRect} rect2 - The bounding rectangle of the element being compared.
* @returns {{
* x: number,
* y: number
* }} An object with the X and Y offset in pixels from rect1's center to rect2's center.
*/
export function getElsRelativeCenterOffset(rect1: ObjRect, rect2: ObjRect): {
x: number;
y: number;
};
/**
* Detects the direction of the dominant collision between two elements
* and calculates how deep the overlap is in both x and y axes.
*
* @param {ObjRect} rect1 - The bounding rectangle of the first element.
* @param {ObjRect} rect2 - The bounding rectangle of the second element.
* @returns {{
* inDir: Dirs | null;
* dirX: Dirs | null;
* dirY: Dirs | null;
* depthX: number;
* depthY: number;
* }} An object containing the collision direction and how deep the overlap is.
*/
export function getElsCollDirDepth(rect1: ObjRect, rect2: ObjRect): {
inDir: Dirs | null;
dirX: Dirs | null;
dirY: Dirs | null;
depthX: number;
depthY: number;
};
/**
* Detects the collision direction and depth between two DOMRects.
*
* @param {ObjRect} rect1 - The bounding rectangle of the first element.
* @param {ObjRect} rect2 - The bounding rectangle of the second element.
* @returns {{ depth: CollData; dirs: CollDirs; isNeg: NegCollDirs; }} Collision info or null if no collision is detected.
*/
export function getElsCollDetails(rect1: ObjRect, rect2: ObjRect): {
depth: CollData;
dirs: CollDirs;
isNeg: NegCollDirs;
};
export function areElsCollTop(rect1: ObjRect, rect2: ObjRect): boolean;
export function areElsCollBottom(rect1: ObjRect, rect2: ObjRect): boolean;
export function areElsCollLeft(rect1: ObjRect, rect2: ObjRect): boolean;
export function areElsCollRight(rect1: ObjRect, rect2: ObjRect): boolean;
export function areElsCollPerfTop(rect1: ObjRect, rect2: ObjRect): boolean;
export function areElsCollPerfBottom(rect1: ObjRect, rect2: ObjRect): boolean;
export function areElsCollPerfLeft(rect1: ObjRect, rect2: ObjRect): boolean;
export function areElsCollPerfRight(rect1: ObjRect, rect2: ObjRect): boolean;
export function areElsColliding(rect1: ObjRect, rect2: ObjRect): boolean;
export function areElsPerfColliding(rect1: ObjRect, rect2: ObjRect): boolean;
export function getElsColliding(rect1: ObjRect, rect2: ObjRect): string | null;
export function getElsPerfColliding(rect1: ObjRect, rect2: ObjRect): "top" | "bottom" | "left" | "right" | null;
export function getElsCollOverlap(rect1: ObjRect, rect2: ObjRect): {
overlapLeft: number;
overlapRight: number;
overlapTop: number;
overlapBottom: number;
};
export function getElsCollOverlapPos({ overlapLeft, overlapRight, overlapTop, overlapBottom, }?: {
overlapLeft?: number | undefined;
overlapRight?: number | undefined;
overlapTop?: number | undefined;
overlapBottom?: number | undefined;
}): {
dirX: Dirs;
dirY: Dirs;
};
export function getRectCenter(rect: ObjRect): {
x: number;
y: number;
};
/**
* A direction relative to a rectangle.
*
* Represents one of the four cardinal directions from the perspective of the element.
*/
export type Dirs = "top" | "bottom" | "left" | "right";
/**
* Represents all directional aspects of a collision.
*/
export type CollDirs = {
/**
* - The dominant direction of entry. `'center'` if all sides are equally overlapped. `null` if no collision.
*/
in: Dirs | "center" | null;
/**
* - The horizontal direction (`'left'` or `'right'`) the collision is biased toward, or `null`.
*/
x: Dirs | null;
/**
* - The vertical direction (`'top'` or `'bottom'`) the collision is biased toward, or `null`.
*/
y: Dirs | null;
};
/**
* Indicates if a collision is in the negative direction (rect2 is outside rect1).
*/
export type NegCollDirs = {
/**
* - Horizontal direction of negative overlap, if any.
*/
x: Dirs | null;
/**
* - Vertical direction of negative overlap, if any.
*/
y: Dirs | null;
};
/**
* Collision depth values from each side of rect2 inside rect1.
*
* Positive values indicate penetration; negative values indicate gaps.
*/
export type CollData = {
/**
* - Depth from rect2's top into rect1.
*/
top: number;
/**
* - Depth from rect2's bottom into rect1.
*/
bottom: number;
/**
* - Depth from rect2's left into rect1.
*/
left: number;
/**
* - Depth from rect2's right into rect1.
*/
right: number;
};
/**
* X and Y offset representing center difference between two rectangles.
*
* Useful to measure how far one element's center is from another.
*/
export type CollCenter = {
/**
* - Horizontal distance in pixels from rect1's center to rect2's center.
*/
x: number;
/**
* - Vertical distance in pixels from rect1's center to rect2's center.
*/
y: number;
};
/**
* Represents a rectangular area in absolute pixel values.
*
* Similar to `DOMRect`, this object describes the dimensions and position of a box
* in the 2D plane, typically representing an element's bounding box.
*/
export type ObjRect = {
/**
* - The total height of the rectangle in pixels.
*/
height: number;
/**
* - The total width of the rectangle in pixels.
*/
width: number;
/**
* - The Y-coordinate of the top edge of the rectangle.
*/
top: number;
/**
* - The Y-coordinate of the bottom edge of the rectangle.
*/
bottom: number;
/**
* - The X-coordinate of the left edge of the rectangle.
*/
left: number;
/**
* - The X-coordinate of the right edge of the rectangle.
*/
right: number;
};
//# sourceMappingURL=collision.d.mts.map