@searsuite/sear-foundation-rect

Immutable rectangle geometry and intersection utilities.

Rectangle values

class PositionRect<T>

Represents a rectangle in absolute position space.

Unlike Rect, which models a grid range, this class stores an origin and a size. It is typically used for layout calculations, collision checks, and hit-testing in rendered space.

constructorPositionRect<T>(x: number, y: number, width: number, height: number): PositionRect<T>

Creates a positioned rectangle from its origin and size.

x: Horizontal origin.
y: Vertical origin.
width: Rectangle width.
height: Rectangle height.

propertyreadonly height: number

The rectangle height measured from y.

propertykey: T | undefined

Optional external identifier associated with this rectangle.

propertyreadonly width: number

The rectangle width measured from x.

propertyx: number

Horizontal origin of the rectangle.

propertyy: number

Vertical origin of the rectangle.

methodgetBounds(): [number, number, number, number]

Returns rectangle bounds as [left, right, top, bottom].

methodgetPosition(): [number, number]

Returns the rectangle origin as [x, y].

methodgetSize(): [number, number]

Returns the rectangle size as [width, height].

methodinRect(x: number, y: number): boolean

Checks whether a point lies inside the rectangle, including its edges.

x: Horizontal coordinate to test.
y: Vertical coordinate to test.

methodtoJSON(): { height: number; key: T | undefined; width: number; x: number; y: number }

Serializes the rectangle and its optional key to a plain object.

methodupdatePosition(newX: number, newY: number): void

Moves the rectangle without changing its size.

newX: New horizontal origin.
newY: New vertical origin.

methodhasDominantAxisSpan(positionRect1: PositionRect, positionRect2: PositionRect): booleanstatic

Checks whether the first rectangle extends further than the second on at least one major axis.

This helper is useful when choosing a dominant rectangle during merge or overlap resolution logic.

positionRect1: The first rectangle.
positionRect2: The second rectangle.

methodintersection(positionRect1: PositionRect, positionRect2: PositionRect): booleanstatic

Returns true when the two rectangles overlap with a non-zero area.

Edge-touching rectangles are treated as non-intersecting.

positionRect1: The first rectangle.
positionRect2: The second rectangle.

methodmerge(rect1: PositionRect, rect2: PositionRect): PositionRectstatic

Creates the smallest rectangle that covers both inputs.

rect1: The first rectangle.
rect2: The second rectangle.

classRangeRect

class RangeRect<T>

Associates a value with a rectangular range in grid coordinates.

The range is defined as [startRow, endRow, startCol, endCol], using inclusive bounds on both axes.

constructorRangeRect<T>(rect: [number, number, number, number], value: T): RangeRect<T>

Creates a range/value pair.

rect: Rectangle coordinates as [startRow, endRow, startCol, endCol].
value: Value associated with every cell inside the rectangle.

propertyrect: [number, number, number, number]

Inclusive rectangle bounds encoded as [startRow, endRow, startCol, endCol].

propertyvalue: T

Value returned for every cell covered by the range.

membershape

shape: unknown

methodaddCol(colIndex: number): this

Extends the range to the right when a column is inserted inside it.

colIndex: Inserted column index.

methodaddRow(rowIndex: number): this

Extends the range downward when a row is inserted inside the current span.

rowIndex: Inserted row index.

methodclone(): RangeRect<T>

Creates an independent copy of this value and its mutable data.

methodforEach(callbackfn: (rowIndex: number, colIndex: number, value: T): void): void

Iterates through every covered cell and yields the stored value.

callbackfn: Called once for each covered cell.

methodgetValue(rowIndex: number, colIndex: number): T | null

Returns the stored value when the requested cell lies inside the range.

rowIndex: Row index to query.
colIndex: Column index to query.

methodremoveCol(colIndex: number): this

Contracts the range when a column is removed from inside it.

colIndex: Removed column index.

methodremoveRow(rowIndex: number): this

Contracts the range when a row is removed from inside the current span.

rowIndex: Removed row index.

methodtoJSON(): { rect: [number, number, number, number]; value: T }

Serializes the range and its associated value.

classRect

Describes a rectangle in sheet coordinates.

The rectangle is stored as two corner points: the top-left point followed by the bottom-right point. The class provides helpers for iteration, structural updates after row or column mutations, and serialization.

constructorRect(rect?: [Point, Point]): Rect

Creates a rectangle from two corner points.

rect: The rectangle bounds as [[startRow, startCol], [endRow, endCol]].

membershape

shape: unknown

memberEmptystatic

Empty: unknown

methodaddCol(colIndex: number): this

Expands or shifts the rectangle after a column insertion.

colIndex: The inserted column index.

methodaddRow(rowIndex: number): this

Expands or shifts the rectangle after a row insertion.

If the insertion happens before the rectangle, both bounds move down. If it happens inside the rectangle, only the ending bound expands.

rowIndex: The inserted row index.

methodclone(): Rect

Creates an independent copy of this value and its mutable data.

methodforEach(callbackfn: (rowIndex: number, colIndex: number): void): void

Iterates through every cell coordinate covered by the rectangle.

callbackfn: Called once for each (rowIndex, colIndex) pair.

methodgetPoint(index: 0 | 1): Point

Returns one of the stored corner points.

index: 0 for the start point, 1 for the end point.

methodlockMutations(): void

Prevents changes through methods or coordinates retained from a committed state.

methodremoveCol(colIndex: number): this

Shrinks or shifts the rectangle after a column removal.

colIndex: The removed column index.

methodremoveRow(rowIndex: number): this

Shrinks or shifts the rectangle after a row removal.

If the removed row is before the rectangle, both bounds move up. If it is inside the rectangle, only the ending bound contracts.

rowIndex: The removed row index.

methodtoJSON(): { rect: [Point, Point] }

Serializes the rectangle to a plain object.

methodupdate(rect: [Point, Point]): Rect

Replaces the rectangle with a new set of bounds.

rect: The new rectangle coordinates.

methodcontains(rectA: Rect, rectB: Rect): booleanstatic

Checks whether rectA fully contains rectB.

rectA: The outer candidate rectangle.
rectB: The inner candidate rectangle.

methodfindBoundingRectangle(rects: Rect[]): Rectstatic

Computes the smallest rectangle that encloses all provided rectangles.

rects: The rectangles to merge into a bounding box.

interfacePositionRectProps

Plain-object shape of a rectangle in pixel or layout coordinates.

propertyheight: number

propertywidth: number

propertyx: number

propertyy: number

typePoint

type Point = [number, number]

A tuple representing a two-dimensional point in grid coordinates.

The first item is the row index and the second item is the column index.

variableemptyPositionRect

emptyPositionRect: PositionRectProps

Zero-sized rectangle used as the default empty layout region.

functioncreateEmptyRect

createEmptyRect(): Rect

Public API for grid and positioned rectangle helpers.

This module re-exports the core geometry primitives used by other searTable packages to describe rectangular selections, layout bounds, and range-based value lookup.

functioncreateEmptyRectShape

createEmptyRectShape(): [Point, Point]

Public API for grid and positioned rectangle helpers.

This module re-exports the core geometry primitives used by other searTable packages to describe rectangular selections, layout bounds, and range-based value lookup.

Rectangle managers

classPositionRectManager

class PositionRectManager<PositionRectKeyType>

Maintains a collection of positioned rectangles that are updated together.

This manager is intentionally lightweight. It acts as a shared holder for rectangles that should move in lockstep, such as overlay fragments that track the same origin.

constructorPositionRectManager<PositionRectKeyType>(): PositionRectManager<PositionRectKeyType>

memberlength

length: unknown

methodaddPositionRect(positionRect: PositionRect<PositionRectKeyType>): void

Registers a rectangle with the manager.

positionRect: Rectangle instance to track.

methodupdatePosition(newX: number, newY: number): void

Moves every managed rectangle to the same new origin.

newX: New horizontal origin.
newY: New vertical origin.

classRangeRectManager

class RangeRectManager<T>

Stores multiple RangeRect instances and resolves a merged value for a cell.

The manager assumes each range contributes part of an object-like value. When a cell belongs to multiple ranges, the returned result is a shallow merge of all matching values in insertion order.

constructorRangeRectManager<T>(): RangeRectManager<T>

memberlength

length: unknown

methodaddRange(range: RangeRect<T>): void

Adds a range to the manager.

range: Range definition to register.

methodgetValue(row: number, col: number): T | null

Resolves the value for a cell by shallow-merging all matching ranges.

When no range covers the target cell, null is returned.

row: Row index to query.
col: Column index to query.

methodtoJSON(): { rect: [number, number, number, number]; value: T }[]

Serializes all ranges in insertion order.

A dedicated exported JSON type could be extracted later if multiple packages start depending on this exact payload shape.