@searsuite/sear-domain-editor
Editor and layout
DocLayoutEngine computes document geometry for a viewport. The viewport and page contracts describe which part of that layout a host should paint.
- classDocBlockLayoutDiff
-
Compares two block-layout snapshots and exposes render-neutral reuse facts.
constructor DocBlockLayoutDiff(entries: readonly DocBlockLayoutDiffEntry[]): DocBlockLayoutDiffproperty readonly entries: readonly DocBlockLayoutDiffEntry[]method getChangedEntries(): readonly DocBlockLayoutDiffEntry[]method getEntry(id: DocNodeId): DocBlockLayoutDiffEntry | nullmethod getReusableRasterCopies(): readonly DocBlockRasterReuse[]method getShiftedEntries(): readonly DocBlockLayoutDiffEntry[]method hasChanges(): booleanmethod compare(previous: DocLayoutCache | null, current: DocLayoutCache, options?: DocBlockLayoutDiffOptions): DocBlockLayoutDiffstatic - classDocLayoutCache
-
Immutable snapshot of block-level document layout used by viewport and SceneGraph projection.
constructor DocLayoutCache(snapshot: LayoutSnapshot, blocksOrIndex: IndexedSnapshot<LayoutSnapshot, DocBlockLayout, DocNodeId> | readonly DocBlockLayout[]): DocLayoutCacheCreates a layout cache from already computed block records.
snapshotLayout snapshot used to derive this cache.
blocksOrIndexTop-level block layout records ordered by document position, or a custom indexed store.
memberblocks blocks: unknownmembersnapshot snapshot: unknownmethod getBlockById(id: DocNodeId): DocBlockLayout | nullReturns the cached layout record for a document block id.
method getBlockByIndex(index: number): DocBlockLayout | nullReturns the cached layout record for a top-level block index.
method getBlockIdsByIndexes(indexes: readonly number[]): readonly DocNodeId[]Returns block ids for the supplied top-level block indexes.
method getBlocksInVerticalRange(top: number, bottom: number): readonly DocBlockLayout[]Returns all cached block records intersecting the supplied vertical range.
method getContentLayoutReusableBlockIndexes(previous: DocLayoutCache): readonly number[]Returns block indexes whose internal content layout can be reused from a previous cache.
A downstream flow shift changes absolute
rect.y, so the whole block record cannot be reused. The renderer can still reuse the block's measured content shape when line count, visual size and flow height are unchanged.method hasBlockFlowLayoutChanged(previous: DocLayoutCache, blockId: DocNodeId): booleanReturns whether one block's height-sensitive flow layout changed.
method hasFlowHeightChanged(previous: DocLayoutCache, blockId: DocNodeId): booleanReturns whether one block's flow height changed compared with another cache.
method fromSnapshot(document: readonly RichDocNode[], snapshot: LayoutSnapshot, previousCache?: DocLayoutCache | null): DocLayoutCachestaticBuilds a block layout cache from a rich document and its layout snapshot.
- classDocLayoutEngine
-
Converts between DocCursorPos (path + char offset) and pixel coordinates (relative to the editor box top-left corner), using rich-text block measurements.
Mirrors the Y-positioning formula used by the document render layout so that cursor positions align with rendered glyphs.
constructor DocLayoutEngine(blockFlowRegistry: RichTextBlockFlowRegistry): DocLayoutEngineproperty readonly symbol: symbolstaticDI token for resolving DocLayoutEngine.
method buildSnapshot(doc: RichDocNode[], blockManager: RichTextBlockLayoutProvider, editorWidth: number, editorHeight: number, cellPadding?: number, verticalAlign?: DocVerticalAlign): LayoutSnapshotBuild a LayoutSnapshot from the current blockManager state.
Prerequisites: callers must add all document paragraphs to
blockManagerbefore building the snapshot.docThe current RichDocNode[] being edited.
blockManagerLayout provider that already holds the paragraph blocks.
editorWidthTotal pixel width of the editor box (including padding).
editorHeightTotal pixel height of the editor box (including padding).
cellPaddingPadding on each side (default 4).
verticalAlignVertical positioning strategy (default center for embedded cell editors).
method buildSnapshotForBlocks(doc: RichDocNode[], blockManager: RichTextBlockLayoutProvider, blockIndexes: readonly number[], blockTops: readonly number[], editorWidth: number, cellPadding?: number): BlockLayoutSnapshotBuilds a snapshot for selected top-level document blocks.
The returned lines keep their full-document text paths, but only the requested blocks are materialized. Callers supply each block's document Y-position from a block-height index.
method cursorToPoint(pos: DocCursorPos, snapshot: LayoutSnapshot): { height: number; x: number; y: number }Convert a DocCursorPos to pixel coordinates relative to the editor box top-left corner.
Returns the position of the cursor bar's horizontal anchor (i.e. the x at which to draw the vertical cursor line, and the y passed to drawCursor), plus the line height needed to size the cursor bar.
method findLineIndex(pos: DocCursorPos, snapshot: LayoutSnapshot): numberReturns the index into
snapshot.linesfor the line containingpos. Returns 0 if not found.method getSelectionRects(sel: DocSelection, snapshot: LayoutSnapshot, originX: number, originY: number): { height: number; width: number; x: number; y: number }[]Compute canvas-space rectangles for a non-collapsed DocSelection.
ReturnsArray of {x,y,width,height} rectangles in canvas coordinates.
selThe current DocSelection (anchor + head).
snapshotLayout snapshot from buildSnapshot.
originXAbsolute canvas X of the editor box top-left.
originYAbsolute canvas Y of the editor box top-left.
method pointToCursor(px: number, py: number, snapshot: LayoutSnapshot): DocCursorPosConvert a pixel position (relative to the editor box top-left) to the nearest DocCursorPos.
Used for click-to-position-cursor and drag-selection.
- classDocPageMap
-
Maps document blocks to pages for viewport range queries and virtualization.
constructor DocPageMap(pageHeight: number, pageGap: number, pages: readonly DocPageLayout[]): DocPageMapCreates a page map from immutable page records.
pageHeightPage height used by this map.
pageGapGap between pages in document coordinates.
pagesOrdered page layout records.
property readonly pageGap: numberGap between pages in document coordinates.
property readonly pageHeight: numberPage height used by this map.
property readonly pages: readonly DocPageLayout[]Ordered page layout records.
method getPage(index: number): DocPageLayout | nullReturns a page record by index.
method getPageIndexesForBlock(blockId: DocNodeId): readonly number[]Returns page indexes that intersect a block id.
method getPagesByIndexes(indexes: readonly number[]): readonly DocPageLayout[]Returns pages for the supplied page indexes, preserving page order.
method getPagesForBlock(block: DocBlockLayout): readonly DocPageLayout[]Returns all pages intersecting a block layout record.
method getPagesInVerticalRange(top: number, bottom: number): readonly DocPageLayout[]Returns all pages intersecting the supplied vertical document range.
method fromLayoutCache(cache: DocLayoutCache, pageHeight: number, pageGap?: number): DocPageMapstaticBuilds a page map by intersecting cached block rectangles with fixed-height pages.
- classDocViewportWindow
-
Visible document window used to filter block and page layout ranges.
constructor DocViewportWindow(x: number, y: number, width: number, height: number): DocViewportWindowCreates a viewport window from document-space rectangle coordinates.
xLeft edge in document coordinates.
yTop edge in document coordinates.
widthVisible width in document units.
heightVisible height in document units.
property readonly height: numberVisible height in document units.
property readonly width: numberVisible width in document units.
property readonly x: numberLeft edge in document coordinates.
property readonly y: numberTop edge in document coordinates.
memberbottom bottom: unknownmethod intersects(rect: DocLayoutRect): booleanReturns whether this viewport intersects another document-space rectangle.
method fromViewport(viewport: { contentRect: DocLayoutRect }, scroll?: { x: number; y: number }): DocViewportWindowstaticCreates a document-space window from a viewport rectangle and scroll offsets.
- classSearEditor
-
Injectable rich-document editor service placeholder.
The service owns document-editor initialization once a document assembly root is available. It is bound by symbol so consumers do not depend on string DI tokens.
constructor SearEditor(): SearEditorConstructs the editor service.
property readonly symbol: symbolstaticDI token for resolving the editor service.
method initialize(): voidInitializes document-editor runtime state.
- interfaceBlockLayoutSnapshot
-
Materialized layout for a subset of top-level document blocks.
property readonly blocks: readonly DocBlockLayout[]Block records for the materialized blocks, using full-document indexes.
property readonly snapshot: LayoutSnapshotLine snapshot containing only the materialized block ranges.
- interfaceDocBlockLayout
-
Cached layout metadata for one top-level document block.
property readonly flowHeight: numberFlow height from this block top to the next block top, or visual height for the last block.
property readonly id: DocNodeIdStable block identity used by retained render nodes.
property readonly index: numberZero-based top-level document block index.
property readonly lineEnd: numberExclusive index after the last layout line belonging to this block.
property readonly lineStart: numberInclusive index of the first layout line belonging to this block.
property readonly rect: DocLayoutRectDocument-space rectangle occupied by this block.
- interfaceDocBlockLayoutDiffEntry
-
property readonly current: DocBlockLayout | nullproperty readonly deltaY: numberproperty readonly id: DocNodeIdproperty readonly index: numberproperty readonly previous: DocBlockLayout | nullproperty readonly status: DocBlockLayoutDiffStatus - interfaceDocBlockLayoutDiffOptions
-
property readonly reflowBlockIds?: ReadonlySet<DocNodeId>Reflow blocks whose render output changed even if their measured layout shape did not.
property readonly repaintBlockIds?: ReadonlySet<DocNodeId>Repaint blocks whose render output changed without invalidating layout cache.
- interfaceDocLayoutRect
-
Rectangle contract used by document layout planning without binding to a render target.
property readonly height: numberHeight in document units.
property readonly width: numberWidth in document units.
property readonly x: numberLeft edge in document coordinates.
property readonly y: numberTop edge in document coordinates.
- interfaceDocPageLayout
-
Layout metadata for one document page.
property readonly blockIds: readonly DocNodeId[]Block ids that intersect this page.
property readonly index: numberZero-based page index.
property readonly rect: DocLayoutRectPage rectangle in document coordinates.
- interfaceDocViewportRange
-
Inclusive visible block/page range within the current document viewport.
property readonly endBlock: numberLast top-level document block index included in the buffered viewport.
property readonly endPage: numberLast page index included in the buffered viewport.
property readonly startBlock: numberFirst top-level document block index included in the buffered viewport.
property readonly startPage: numberFirst page index included in the buffered viewport.
- interfaceDocViewportScrollSource
-
Minimal scroll/viewport contract needed to compute a document viewport range.
method getShape(): readonly [number, number]Returns the viewport width/height.
method getState(): { x: number; y: number }Returns the current scroll offset in document coordinates.
- interfaceLayoutLine
-
A single wrapped line inside the editor, with full path metadata for bidirectional cursor ↔ pixel coordinate mapping.
property chars: RichTextChar[]Per-character measurements for this line.
property charStartOffset: numberChar offset (within the text node) of the FIRST character on this line. e.g. if a text node wraps at char 20, the second line has charStartOffset=20.
property cursorXOffsets?: number[]Cursor boundary x offsets relative to this line's x, one entry per char boundary.
property fontAscent: numberFont ascent: distance from baseline to top of tallest glyph on this line.
property height: numberLine height in CSS/canvas pixels.
property textNodePath: number[]Full path to the text node this line belongs to.
For a flat document (paragraph → single text node):
textNodePath = [paraIndex, 0]The path mirrors
DocCursorPos.pathsemantics: a cursor at{ path: textNodePath, offset }lives on this line whencharStartOffset <= offset <= charStartOffset + chars.length.property x: numberLeft edge of text, relative to editor box top-left (includes cellPadding).
property y: numberY coordinate used for fillText/cursor drawing, relative to editor box top-left. This is the baseline consumed by document render nodes so cursor pixel coordinates align with rendered text.
- typeDocBlockLayoutDiffStatus
-
type DocBlockLayoutDiffStatus = "unchanged" | "shifted" | "changed" | "added" | "removed" - typeDocVerticalAlign
-
type DocVerticalAlign = "top" | "center"Vertical positioning strategy for a laid-out document frame.
- functioncomputeViewportRange
-
computeViewportRange(scrollSource: DocViewportScrollSource, layoutCache: DocLayoutCache, pageMap: DocPageMap, offset?: { x: number; y: number }): DocViewportRangeComputes the visible document block/page range from scroll state and cached layout.
This mirrors Sheet's viewport-range helper at the responsibility level: convert viewport bounds to inclusive start/end indexes and include a one-item buffer on each side. Consumers decide how to query blocks/pages or render.
Snapshots and rendering
Layout snapshots and block diffs identify the areas that changed so rendering can reuse unaffected work.
- classArrayIndexedSnapshot
-
class ArrayIndexedSnapshot<TSnapshot, TItem, TKey> extends IndexedSnapshot<TSnapshot, TItem, TKey>Array and Map backed implementation of IndexedSnapshot.
constructor ArrayIndexedSnapshot<TSnapshot, TItem, TKey>(snapshot: TSnapshot, items: readonly TItem[], getKey: (item: TItem): TKey, getIndex: (item: TItem): number): ArrayIndexedSnapshot<TSnapshot, TItem, TKey>Creates an indexed snapshot from ordered items and selector functions.
method getByIndex(index: number): TItem | nullReturns one item by its numeric index.
method getByKey(key: TKey): TItem | nullReturns one item by its stable key.
method getKeysByIndexes(indexes: readonly number[]): readonly TKey[]Returns keys for the supplied numeric indexes, preserving input order.
- classIndexedSnapshot
-
class IndexedSnapshot<TSnapshot, TItem, TKey>Generic immutable snapshot plus ordered, multi-key indexed item access.
property readonly items: readonly TItem[]Items in their canonical order.
property readonly snapshot: TSnapshotmethod getByIndex(index: number): TItem | nullReturns one item by its numeric index.
method getByKey(key: TKey): TItem | nullReturns one item by its stable key.
method getKeysByIndexes(indexes: readonly number[]): readonly TKey[]Returns keys for the supplied numeric indexes, preserving input order.
- interfaceDocBlockRasterReuse
-
property readonly destination: DocLayoutRectproperty readonly id: DocNodeIdproperty readonly index: numberproperty readonly source: DocLayoutRect - interfaceDocBlockRenderDebugCopy
- interfaceDocBlockRenderDebugRect
-
property readonly height: numberproperty readonly width: numberproperty readonly x: numberproperty readonly y: number - interfaceDocBlockRenderDebugSnapshot
-
property readonly changedBlocks: readonly DocBlockRenderDebugRect[]property readonly copiedPixelArea: numberproperty readonly frameMode: DocBlockRenderFrameModeproperty readonly incrementalRenderAccepted: booleanproperty readonly incrementalRenderCandidate?: DocBlockRenderPolicyCandidateDebugMetricsproperty readonly incrementalRenderReason: stringproperty readonly invalidRedrawRects: readonly DocBlockRenderDebugRect[]property readonly rasterCopies: readonly DocBlockRenderDebugCopy[]property readonly redrawnBlockCount: numberproperty readonly reusedBlocks: readonly DocBlockRenderDebugRect[]property readonly shiftedBlocks: readonly DocBlockRenderDebugRect[]property readonly skippedBlockCount: number - interfaceDocBlockRenderPolicyCandidateDebugMetrics
-
property readonly copiedAreaRatio: numberproperty readonly copiedPixelArea: numberproperty readonly copyCount: numberproperty readonly invalidAreaRatio: numberproperty readonly invalidPixelArea: numberproperty readonly invalidRectCount: number - interfaceLayoutSnapshot
-
Pre-computed layout for the entire editing session.
property lines: LayoutLine[] - typeDocBlockRenderFrameMode
-
type DocBlockRenderFrameMode = "rebuild" | "full" | "scroll" | "block-copy" | "skipped" - functionlockLayoutSnapshot
-
lockLayoutSnapshot(snapshot: LayoutSnapshot): LayoutSnapshotLocks a completed layout so readers cannot change cursor or render geometry.
No matching API entries.