@rtif-sdk/web 1.1.0 → 1.4.0

package/dist/virtual-viewport.d.ts

@@ -0,0 +1,241 @@
+/**
+ * Virtual viewport for block-level DOM virtualization.
+ *
+ * Manages which blocks are rendered into the DOM based on scroll position,
+ * using spacer elements to maintain correct scroll height. Only blocks
+ * within the visible range (plus a configurable buffer) are present in the
+ * DOM at any time, enabling smooth editing of documents with thousands of
+ * blocks.
+ *
+ * @packageDocumentation
+ */
+import type { Document } from '@rtif-sdk/core';
+import type { SpatialIndex } from './spatial-index.js';
+import type { MarkRendererRegistry } from './mark-renderer.js';
+import type { BlockRendererRegistry } from './block-renderer.js';
+/**
+ * Configuration for creating a {@link VirtualViewport}.
+ *
+ * @example
+ * ```ts
+ * const config: VirtualViewportConfig = {
+ *   root: document.getElementById('editor')!,
+ *   bufferSize: 15,
+ *   estimatedBlockHeight: 28,
+ * };
+ * ```
+ */
+export interface VirtualViewportConfig {
+    /** The root contenteditable element that contains block elements. */
+    readonly root: HTMLElement;
+    /**
+     * Number of extra blocks to render above and below the visible range
+     * for smoother scrolling. Higher values reduce flashing at the cost
+     * of more DOM nodes.
+     *
+     * Default: `10`.
+     */
+    readonly bufferSize?: number;
+    /**
+     * Default estimated pixel height for block types not listed in
+     * {@link blockTypeHeights}. Passed through to the spatial index.
+     *
+     * Default: `24`.
+     */
+    readonly estimatedBlockHeight?: number;
+    /**
+     * Estimated pixel heights per block type string.
+     * Passed through to the spatial index config.
+     *
+     * @example
+     * ```ts
+     * { heading: 48, image: 250 }
+     * ```
+     */
+    readonly blockTypeHeights?: Record<string, number>;
+    /**
+     * The scrollable ancestor element, or `window`. When omitted, the
+     * viewport walks DOM ancestors to auto-detect the nearest scrollable
+     * container via {@link findScrollParent}.
+     */
+    readonly scrollContainer?: HTMLElement | Window;
+}
+/**
+ * A virtual viewport that keeps only visible blocks in the DOM.
+ *
+ * Create with {@link createVirtualViewport}. The viewport manages spacer
+ * elements, scroll listeners, and height measurement to provide seamless
+ * editing of large documents.
+ *
+ * @example
+ * ```ts
+ * const vp = createVirtualViewport({ root }, doc);
+ * vp.renderInitial(doc, markRenderers, blockRenderers, blockElementMap);
+ * // On scroll, the viewport automatically updates visible blocks.
+ * // On document change:
+ * vp.reconcile(prevDoc, nextDoc, composingBlockId, markRenderers, blockRenderers, blockElementMap);
+ * ```
+ */
+export interface VirtualViewport {
+    /** The spatial index used for layout calculations. */
+    readonly spatialIndex: SpatialIndex;
+    /** The currently rendered block index range (start inclusive, end exclusive). */
+    readonly renderedRange: Readonly<{
+        start: number;
+        end: number;
+    }>;
+    /** Block IDs that are pinned (always rendered regardless of scroll). */
+    readonly pinnedBlockIds: ReadonlySet<string>;
+    /**
+     * Perform the initial render of the document into the root element.
+     *
+     * Clears root children, creates spacer elements, renders the initial
+     * visible range of blocks, and measures their heights.
+     *
+     * @param doc - The RTIF document to render
+     * @param markRenderers - Optional mark renderer registry
+     * @param blockRenderers - Optional block renderer registry
+     * @param blockElementMap - Optional map to populate with block ID to element mappings
+     *
+     * @example
+     * ```ts
+     * vp.renderInitial(doc, markRenderers, blockRenderers, blockElementMap);
+     * ```
+     */
+    renderInitial(doc: Document, markRenderers?: MarkRendererRegistry, blockRenderers?: BlockRendererRegistry, blockElementMap?: Map<string, HTMLElement>): void;
+    /**
+     * Reconcile the viewport after a document change.
+     *
+     * Rebuilds the spatial index preserving measured heights, recomputes
+     * the visible range, delegates to {@link reconcileBlock} for changed
+     * blocks, and updates spacer heights.
+     *
+     * @param prevDoc - The previous document state
+     * @param nextDoc - The new document state
+     * @param composingBlockId - Block ID under IME composition, or null
+     * @param markRenderers - Optional mark renderer registry
+     * @param blockRenderers - Optional block renderer registry
+     * @param blockElementMap - Optional map of block ID to element
+     *
+     * @example
+     * ```ts
+     * vp.reconcile(prevDoc, nextDoc, null, markRenderers, blockRenderers, blockElementMap);
+     * ```
+     */
+    reconcile(prevDoc: Document, nextDoc: Document, composingBlockId: string | null, markRenderers?: MarkRendererRegistry, blockRenderers?: BlockRendererRegistry, blockElementMap?: Map<string, HTMLElement>): void;
+    /**
+     * Ensure a specific block index is rendered in the DOM.
+     *
+     * If the block is outside the current rendered range, the range is
+     * expanded to include it. Returns the block element, or null if the
+     * index is out of bounds.
+     *
+     * @param blockIndex - The 0-based block index to ensure is rendered
+     * @returns The block DOM element, or null if the index is invalid
+     *
+     * @example
+     * ```ts
+     * const el = vp.ensureRendered(42);
+     * if (el) el.scrollIntoView();
+     * ```
+     */
+    ensureRendered(blockIndex: number): HTMLElement | null;
+    /**
+     * Pin a block so it stays rendered regardless of scroll position.
+     *
+     * Useful for blocks under active editing (e.g., IME composition)
+     * that must not be removed from the DOM.
+     *
+     * @param blockId - The block ID to pin
+     */
+    pin(blockId: string): void;
+    /**
+     * Unpin a previously pinned block.
+     *
+     * The block may be removed from the DOM on the next scroll event
+     * if it is outside the visible range.
+     *
+     * @param blockId - The block ID to unpin
+     */
+    unpin(blockId: string): void;
+    /**
+     * Handle a scroll event. Recomputes the visible range and adds/removes
+     * block elements as needed. Throttled via requestAnimationFrame.
+     */
+    onScroll(): void;
+    /**
+     * Measure actual DOM heights of all rendered block elements and update
+     * the spatial index with the measured values.
+     */
+    measureHeights(): void;
+    /**
+     * Temporarily render all blocks in the document.
+     *
+     * Uses a DocumentFragment to batch DOM insertions for better performance.
+     * Returns a restore function that removes non-visible blocks and
+     * restores spacer heights. Useful for operations that need all blocks
+     * in the DOM (e.g., find-and-replace, full-document selection sync).
+     *
+     * @returns A function that restores virtualized rendering
+     *
+     * @example
+     * ```ts
+     * const restore = vp.expandAll();
+     * // ... perform operation that needs all blocks ...
+     * restore();
+     * ```
+     */
+    expandAll(): () => void;
+    /**
+     * Destroy the viewport, removing scroll listeners and cleaning up state.
+     *
+     * The root element's children (spacers, blocks) are NOT removed -- the
+     * caller is responsible for clearing the root if needed.
+     */
+    destroy(): void;
+}
+/**
+ * Walk DOM ancestors of an element to find the nearest scrollable container.
+ *
+ * Checks `getComputedStyle(el).overflowY` for `auto` or `scroll`. If no
+ * scrollable ancestor is found (including `document.body` and
+ * `document.documentElement`), returns `window`.
+ *
+ * @param el - The element to start searching from
+ * @returns The nearest scrollable ancestor, or `window`
+ *
+ * @example
+ * ```ts
+ * const scroller = findScrollParent(editorRoot);
+ * scroller.addEventListener('scroll', onScroll);
+ * ```
+ */
+export declare function findScrollParent(el: HTMLElement): HTMLElement | Window;
+/**
+ * Create a virtual viewport for block-level DOM virtualization.
+ *
+ * The viewport renders only blocks within the visible scroll region (plus
+ * a configurable buffer), using spacer elements to maintain correct scroll
+ * height. As the user scrolls, blocks entering the viewport are created
+ * and blocks leaving are removed.
+ *
+ * @param config - Viewport configuration (root element, buffer size, etc.)
+ * @param doc - The initial RTIF document
+ * @returns A {@link VirtualViewport} instance
+ *
+ * @example
+ * ```ts
+ * import { createVirtualViewport } from '@rtif-sdk/web';
+ *
+ * const vp = createVirtualViewport({ root: editorEl, bufferSize: 15 }, doc);
+ * vp.renderInitial(doc, markRenderers, blockRenderers, blockElementMap);
+ *
+ * // On document change:
+ * vp.reconcile(prevDoc, nextDoc, null, markRenderers, blockRenderers, blockElementMap);
+ *
+ * // Cleanup:
+ * vp.destroy();
+ * ```
+ */
+export declare function createVirtualViewport(config: VirtualViewportConfig, doc: Document): VirtualViewport;
+//# sourceMappingURL=virtual-viewport.d.ts.map

package/dist/virtual-viewport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-viewport.d.ts","sourceRoot":"","sources":["../src/virtual-viewport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAS,MAAM,gBAAgB,CAAC;AAEtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAMjE;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,qBAAqB;IACpC,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAE3B;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;;OAKG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAEvC;;;;;;;;OAQG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEnD;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,WAAW,GAAG,MAAM,CAAC;CACjD;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,eAAe;IAC9B,sDAAsD;IACtD,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IAEpC,iFAAiF;IACjF,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEjE,wEAAwE;IACxE,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAE7C;;;;;;;;;;;;;;;OAeG;IACH,aAAa,CACX,GAAG,EAAE,QAAQ,EACb,aAAa,CAAC,EAAE,oBAAoB,EACpC,cAAc,CAAC,EAAE,qBAAqB,EACtC,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,GACzC,IAAI,CAAC;IAER;;;;;;;;;;;;;;;;;;OAkBG;IACH,SAAS,CACP,OAAO,EAAE,QAAQ,EACjB,OAAO,EAAE,QAAQ,EACjB,gBAAgB,EAAE,MAAM,GAAG,IAAI,EAC/B,aAAa,CAAC,EAAE,oBAAoB,EACpC,cAAc,CAAC,EAAE,qBAAqB,EACtC,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,GACzC,IAAI,CAAC;IAER;;;;;;;;;;;;;;;OAeG;IACH,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAAC;IAEvD;;;;;;;OAOG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAE3B;;;;;;;OAOG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7B;;;OAGG;IACH,QAAQ,IAAI,IAAI,CAAC;IAEjB;;;OAGG;IACH,cAAc,IAAI,IAAI,CAAC;IAEvB;;;;;;;;;;;;;;;;OAgBG;IACH,SAAS,IAAI,MAAM,IAAI,CAAC;IAExB;;;;;OAKG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,WAAW,GAAG,WAAW,GAAG,MAAM,CAUtE;AA6ED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,qBAAqB,EAC7B,GAAG,EAAE,QAAQ,GACZ,eAAe,CA6iBjB"}