@searsuite/sear-foundation-rect API reference

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.

constructorconstructor

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

Creates a positioned rectangle from its origin and size.

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

propertyheight

readonly height: number

The rectangle height measured from y.

propertykey

key: T | undefined

Optional external identifier associated with this rectangle.

propertywidth

readonly width: number

The rectangle width measured from x.

propertyx

x: number

Horizontal origin of the rectangle.

propertyy

y: number

Vertical origin of the rectangle.

methodgetBounds

getBounds(): [number, number, number, number]

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

methodgetPosition

getPosition(): [number, number]

Returns the rectangle origin as [x, y].

methodgetSize

getSize(): [number, number]

Returns the rectangle size as [width, height].

methodinRect

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

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

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

methodtoJSON

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

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

methodupdatePosition

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

Moves the rectangle without changing its size.

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

methodhasDominantAxisSpanstatic

hasDominantAxisSpan(positionRect1: PositionRect, positionRect2: PositionRect): boolean

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: PositionRect: The first rectangle.
positionRect2: PositionRect: The second rectangle.

methodintersectionstatic

intersection(positionRect1: PositionRect, positionRect2: PositionRect): boolean

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

Edge-touching rectangles are treated as non-intersecting.

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

methodmergestatic

merge(rect1: PositionRect, rect2: PositionRect): PositionRect

Creates the smallest rectangle that covers both inputs.

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

classPositionRectManager source ↗

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.

constructorconstructor

PositionRectManager<PositionRectKeyType>(): PositionRectManager<PositionRectKeyType>

Creates a PositionRectManager instance.

memberlength

length: unknown

methodaddPositionRect

addPositionRect(positionRect: PositionRect<PositionRectKeyType>): void

Registers a rectangle with the manager.

positionRect: PositionRect<PositionRectKeyType>: Rectangle instance to track.

methodupdatePosition

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

Moves every managed rectangle to the same new origin.

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

classRangeRect source ↗

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.

constructorconstructor

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

Creates a range/value pair.

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

propertyrect

rect: [number, number, number, number]

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

propertyvalue

value: T

Value returned for every cell covered by the range.

membershape

shape: unknown

methodaddCol

addCol(colIndex: number): this

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

colIndex: number: Inserted column index.

methodaddRow

addRow(rowIndex: number): this

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

rowIndex: number: Inserted row index.

methodclone

clone(): RangeRect<T>

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

methodforEach

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

Iterates through every covered cell and yields the stored value.

callbackfn: (rowIndex: number, colIndex: number, value: T): void: Called once for each covered cell.

methodgetValue

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

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

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

methodremoveCol

removeCol(colIndex: number): this

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

colIndex: number: Removed column index.

methodremoveRow

removeRow(rowIndex: number): this

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

rowIndex: number: Removed row index.

methodtoJSON

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

Serializes the range and its associated value.

classRangeRectManager source ↗

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.

constructorconstructor

RangeRectManager<T>(): RangeRectManager<T>

memberlength

length: unknown

methodaddRange

addRange(range: RangeRect<T>): void

Adds a range to the manager.

range: RangeRect<T>: Range definition to register.

methodgetValue

getValue(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: number: Row index to query.
col: number: Column index to query.

methodtoJSON

toJSON(): { 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.

classRect source ↗

class Rect

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.

constructorconstructor

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

Creates a rectangle from two corner points.

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

membershape

shape: unknown

memberEmptystatic

Empty: unknown

methodaddCol

addCol(colIndex: number): this

Expands or shifts the rectangle after a column insertion.

colIndex: number: The inserted column index.

methodaddRow

addRow(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: number: The inserted row index.

methodclone

clone(): Rect

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

methodforEach

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

Iterates through every cell coordinate covered by the rectangle.

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

methodgetPoint

getPoint(index: 0 | 1): Point

Returns one of the stored corner points.

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

methodlockMutations

lockMutations(): void

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

methodremoveCol

removeCol(colIndex: number): this

Shrinks or shifts the rectangle after a column removal.

colIndex: number: The removed column index.

methodremoveRow

removeRow(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: number: The removed row index.

methodtoJSON

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

Serializes the rectangle to a plain object.

methodupdate

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

Replaces the rectangle with a new set of bounds.

rect: [Point, Point]: The new rectangle coordinates.

methodcontainsstatic

contains(rectA: Rect, rectB: Rect): boolean

Checks whether rectA fully contains rectB.

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

methodfindBoundingRectanglestatic

findBoundingRectangle(rects: Rect[]): Rect

Computes the smallest rectangle that encloses all provided rectangles.

rects: Rect[]: The rectangles to merge into a bounding box.

interfacePositionRectProps source ↗

interface PositionRectProps

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

propertyheight

height: number

propertywidth

width: number

propertyx

x: number

propertyy

y: number

typePoint source ↗

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 source ↗

emptyPositionRect: PositionRectProps

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

functioncreateEmptyRect source ↗

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 source ↗

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.