SearSuite
← All packages

API reference

@searsuite/sear-foundation-common

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

7 exportsderived from source

enumBuildInStateNamesource ↗
enum BuildInStateName

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: "COLUMN_SHAPE_STATE"

State managing column dimensions and visual shape properties

enum memberCORE_STATE
CORE_STATE: "CORE_STATE"

Core state managing the fundamental document structure and content

enum memberROW_SHAPE_STATE
ROW_SHAPE_STATE: "ROW_SHAPE_STATE"

State managing row dimensions and visual shape properties

enumSearDocumentTypesource ↗
enum SearDocumentType

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
SEAR_DOC: 1

General document type (text processor)

enum memberSEAR_FLOW
SEAR_FLOW: 6

Flowchart and diagram document type

enum memberSEAR_MIND
SEAR_MIND: 5

Mind map document type for hierarchical visualization

enum memberSEAR_SHEET
SEAR_SHEET: 2

Spreadsheet document type with cell-based data

enum memberSEAR_SLIDE
SEAR_SLIDE: 4

Slide presentation document type

enum memberSEAR_TABLE
SEAR_TABLE: 3

Table document type for structured tabular data

enum memberUNKNOWN
UNKNOWN: 0

Unknown or unspecified document type

classQuadTreesource ↗
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
constructorconstructor
QuadTree<T>(rootNode: IQuadTreeNode<T>): QuadTree<T>

Creates a new QuadTree instance with a specified root node.

rootNode: IQuadTreeNode<T>

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

propertyroot
root: IQuadTreeNode<T>

The root node of the quadtree.

methodinsert
insert(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: Point

The 2D coordinates where the value should be stored.

value: T

The data to associate with this point.

methodquery
query(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: { height: number; width: number; x: number; y: number }

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

methodremove
remove(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: Point

The exact coordinates of the point to remove.

classQuadTreeNodesource ↗
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).

constructorconstructor
QuadTreeNode<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: { height: number; width: number; x: number; y: number }

The rectangular area this node covers.

capacity: number

Maximum points before node subdivides (typically 4).

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

The rectangular boundary of this node in 2D space.

propertycapacity
capacity: number

Maximum number of points this node can hold before subdividing.

propertydivided
divided: boolean

Flag indicating whether this node has been subdivided into children.

propertynortheast
northeast: IQuadTreeNode<T> | null

Northeast child node (upper-right quadrant).

propertynorthwest
northwest: IQuadTreeNode<T> | null

Northwest child node (upper-left quadrant).

propertypoints
points: NodeData<T>[]

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

propertysoutheast
southeast: IQuadTreeNode<T> | null

Southeast child node (lower-right quadrant).

propertysouthwest
southwest: IQuadTreeNode<T> | null

Southwest child node (lower-left quadrant).

methodcontains
contains(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: { height: number; width: number; x: number; y: number }

The rectangle to check against.

point: Point

The point to test.

methodinsert
insert(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: NodeData<T>

The point and value to insert.

methodintersects
intersects(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: { height: number; width: number; x: number; y: number }

First rectangle.

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

Second rectangle.

methodquery
query(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: { height: number; width: number; x: number; y: number }

The rectangular area to query.

found: NodeData<T>[]

Accumulator array (for recursion, default empty array).

methodremove
remove(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: Point

The exact coordinates of the point to remove.

methodsubdivide
subdivide(): 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
classSearKeysource ↗
class SearKey

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;
constructorconstructor
SearKey(key?: string): SearKey

Creates a new SearKey instance with a unique identifier.

key: string

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

propertykey
key: string

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

functionprintNameAndVersionsource ↗
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: string

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

version: string

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

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

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