SearSuite
← All packages

@searsuite/sear-foundation-common

Small dependency-free values and contracts shared across SearSuite packages.

enumBuildInStateName

Enumeration of built-in state names in the Sear framework.

These state names are reserved and used internally by the Sear document editing system to manage the core data structures and visual representations.

State Types:

  • CORE_STATE: The fundamental state managing document structure and content
  • COLUMN_SHAPE_STATE: State tracking column dimensions and visual properties
  • ROW_SHAPE_STATE: State tracking row dimensions and visual properties

These are typically used as keys in the state management system to ensure that core states don't conflict with user-defined or plugin-defined states.

enum memberCOLUMN_SHAPE_STATE: "COLUMN_SHAPE_STATE"

State managing column dimensions and visual shape properties

enum memberCORE_STATE: "CORE_STATE"

Core state managing the fundamental document structure and content

enum memberROW_SHAPE_STATE: "ROW_SHAPE_STATE"

State managing row dimensions and visual shape properties

enumSearDocumentType

Enumeration of supported document types in the Sear suite.

The Sear suite is a comprehensive document editing and collaboration platform that supports multiple document formats, each with specific features and use cases.

Supported Types:

  • UNKNOWN: Undefined or unrecognized document type
  • SEAR_DOC: General-purpose text document (word processor)
  • SEAR_SHEET: Spreadsheet with cells, formulas, and data analysis
  • SEAR_TABLE: Structured table for tabular data presentation
  • SEAR_SLIDE: Presentation slides for visual content delivery
  • SEAR_MIND: Mind mapping document for brainstorming and organizing ideas
  • SEAR_FLOW: Flowchart and diagram editor for process visualization
enum memberSEAR_DOC: 1

General document type (text processor)

enum memberSEAR_FLOW: 6

Flowchart and diagram document type

enum memberSEAR_MIND: 5

Mind map document type for hierarchical visualization

enum memberSEAR_SHEET: 2

Spreadsheet document type with cell-based data

enum memberSEAR_SLIDE: 4

Slide presentation document type

enum memberSEAR_TABLE: 3

Table document type for structured tabular data

enum memberUNKNOWN: 0

Unknown or unspecified document type

classQuadTree
class QuadTree<T>

High-level QuadTree interface for spatial data management.

This class provides a user-friendly API for working with quadtrees. It maintains a root node and delegates all operations to it.

Typical use cases:

  • 2D game collision detection (broad phase)
  • Spatial database indexing
  • Rectangle packing and overlap queries
  • Geographic information systems (GIS) spatial queries
constructorQuadTree<T>(rootNode: IQuadTreeNode<T>): QuadTree<T>

Creates a new QuadTree instance with a specified root node.

rootNode

The root node defining the initial boundary and capacity. Typically created as: new QuadTreeNode({ x: 0, y: 0, width: 800, height: 600 }, 4)

propertyroot: IQuadTreeNode<T>

The root node of the quadtree.

methodinsert(point: Point, value: T): boolean

Inserts a new point and associated value into the quadtree.

Returnstrue if insertion succeeded, false if point is outside the tree's boundary.

point

The 2D coordinates where the value should be stored.

value

The data to associate with this point.

methodquery(range: { height: number; width: number; x: number; y: number }): NodeData<T>[]

Queries all values within a rectangular range.

ReturnsArray of all data entries found within the range.

range

The query rectangle (x, y, width, height).

methodremove(point: Point): boolean

Removes a point and its associated value from the quadtree.

Returnstrue if point was found and removed, false if not found.

point

The exact coordinates of the point to remove.

classQuadTreeNode
class QuadTreeNode<T> extends IQuadTreeNode<T>

Implementation of a QuadTree node for efficient 2D spatial partitioning.

A QuadTree divides a 2D space into four quadrants recursively, enabling fast spatial queries. This implementation is particularly useful for:

  • Range queries on 2D data
  • Collision detection in graphics/gaming
  • Spatial indexing in databases
  • Performance optimization for large datasets

The tree automatically subdivides nodes when they exceed capacity, creating a balanced spatial structure. Each node can hold up to 'capacity' points before subdividing into four child nodes (northeast, northwest, southeast, southwest).

constructorQuadTreeNode<T>(boundary: { height: number; width: number; x: number; y: number }, capacity: number): QuadTreeNode<T>

Creates a new QuadTree node with specified boundary and capacity.

boundary

The rectangular area this node covers.

capacity

Maximum points before node subdivides (typically 4).

propertyboundary: { height: number; width: number; x: number; y: number }

The rectangular boundary of this node in 2D space.

propertycapacity: number

Maximum number of points this node can hold before subdividing.

propertydivided: boolean

Flag indicating whether this node has been subdivided into children.

propertynortheast: IQuadTreeNode<T> | null

Northeast child node (upper-right quadrant).

propertynorthwest: IQuadTreeNode<T> | null

Northwest child node (upper-left quadrant).

propertypoints: NodeData<T>[]

Array of data points stored in this node (before subdivision).

propertysoutheast: IQuadTreeNode<T> | null

Southeast child node (lower-right quadrant).

propertysouthwest: IQuadTreeNode<T> | null

Southwest child node (lower-left quadrant).

methodcontains(boundary: { height: number; width: number; x: number; y: number }, point: Point): boolean

Checks if a point is contained within a rectangular boundary. Uses inclusive lower bound and exclusive upper bound for consistency.

Returnstrue if the point is within the boundary (x1 <= x < x2, y1 <= y < y2).

boundary

The rectangle to check against.

point

The point to test.

methodinsert(data: NodeData<T>): boolean

Inserts a data entry into the quadtree. The insertion process:

  1. Checks if the point is within this node's boundary
  2. If node has capacity, adds point directly
  3. If node is full, subdivides and recursively inserts into children

This ensures the tree grows in a balanced manner, with points distributed across quadrants as the tree expands.

Returnstrue if insertion succeeded, false if point is outside boundary.

data

The point and value to insert.

methodintersects(a: { height: number; width: number; x: number; y: number }, b: { height: number; width: number; x: number; y: number }): boolean

Checks if two rectangles intersect (have any overlapping area). Uses the separating axis theorem for AABB (Axis-Aligned Bounding Box) collision.

Two rectangles do NOT intersect if:

  • Rectangle A is completely to the right of B
  • Rectangle A is completely to the left of B
  • Rectangle A is completely below B
  • Rectangle A is completely above B

Returnstrue if the rectangles intersect, false otherwise.

a

First rectangle.

b

Second rectangle.

methodquery(range: { height: number; width: number; x: number; y: number }, found?: NodeData<T>[]): NodeData<T>[]

Finds all data entries within a given rectangular range. This is the primary query operation for spatial lookups.

The query process:

  1. Checks if the query range intersects with this node's boundary
  2. If no intersection, skips this node and its children
  3. If intersection, checks all points in this node
  4. Recursively queries child nodes if subdivided

This approach provides O(log N) average performance for sparse data.

ReturnsArray of all data entries found within the range.

range

The rectangular area to query.

found

Accumulator array (for recursion, default empty array).

methodremove(point: Point): boolean

Removes a data entry at the specified point coordinates.

The removal process:

  1. Checks if point is within this node's boundary
  2. Searches and removes the point from this node's points array
  3. If not found, recursively searches child nodes

Note: This operation does not trigger node merging after removal, so the tree structure may become unbalanced over time with many removals.

Returnstrue if point was found and removed, false if not found.

point

The exact coordinates of the point to remove.

methodsubdivide(): void

Subdivides this node into four equal child nodes (quadrants). Called when the node reaches capacity and needs to distribute points to child nodes for better spatial organization.

The subdivision creates four equal rectangles:

  • Northeast (NE): upper-right
  • Northwest (NW): upper-left
  • Southeast (SE): lower-right
  • Southwest (SW): lower-left
classSearKey

SearKey class for generating unique identifiers within the Sear framework.

This class is primarily used for plugin identification and namespace management in the Sear document editing system. Each instance receives a uniquely generated key that prevents naming collisions even when multiple plugins with the same base name are loaded.

Use cases:

  • Plugin identification: Each plugin instance gets a unique key for internal references
  • State management: Creating unique state keys for different plugin instances
  • Event system: Identifying event listeners and handlers from different sources
  • Namespace isolation: Preventing key collisions in shared state objects
Example
const key1 = new SearKey('plugin'); // Returns key='plugin#39;
const key2 = new SearKey('plugin'); // Returns key='plugin$1'
const key3 = new SearKey('plugin'); // Returns key='plugin$2'
const key4 = new SearKey('state');  // Returns key='state#39;
constructorSearKey(key?: string): SearKey

Creates a new SearKey instance with a unique identifier.

key

The base name for this key (default: 'plugin'). Should be descriptive and represent the purpose of this key.

propertykey: string

The unique key string generated for this instance. Format: '{baseName}#39; for the first instance, '{baseName}${count}' for subsequent ones.

functionprintNameAndVersion
printNameAndVersion(name: string, version: string): void

Exports the console logging utility for displaying plugin name and version.

Example
import { printNameAndVersion } from '@searsuite/sear-foundation-common';\n *
// Display plugin info on initialization
printNameAndVersion('SearEditor', '1.2.3');
// Console output: \" SearEditor  v1.2.3 \" with styling
name

The name of the plugin or component (e.g., 'sear-editor', 'sear-table')

version

The version string of the plugin (e.g., '1.0.0', '2.1.5-beta')

variableCommandExecutionPhase
CommandExecutionPhase: { Completed: "completed"; Failed: "failed"; Started: "started" }

Stable lifecycle phases emitted by Sheet, Doc, and Workbook command buses.