@rtif-sdk/web 1.0.0

package/dist/input-bridge.d.ts

@@ -0,0 +1,273 @@
+/**
+ * InputBridge — translates DOM `beforeinput` events into RTIF engine operations.
+ *
+ * This module is the core of the "controlled contenteditable" approach.
+ * It intercepts `beforeinput` events, prevents default browser behavior for
+ * most input types, and dispatches the corresponding RTIF operations through
+ * the injected dependencies.
+ *
+ * During IME composition, composition-related input types are passed through
+ * to the browser so that native composition rendering works correctly.
+ * The composition handler (separate module) emits RTIF operations on commit.
+ *
+ * @module
+ */
+import type { Document, Selection, Operation } from '@rtif-sdk/core';
+/**
+ * Injected dependencies for the InputBridge.
+ *
+ * The bridge does not import the engine directly. Instead, the parent module
+ * wires these callbacks at construction time, keeping the bridge testable
+ * and decoupled from the engine's concrete class.
+ *
+ * @example
+ * ```ts
+ * const deps: InputBridgeDeps = {
+ *   getSelection: () => engine.state.selection,
+ *   getDoc: () => engine.state.doc,
+ *   dispatch: (ops) => engine.dispatch(ops),
+ *   undo: () => engine.undo(),
+ *   redo: () => engine.redo(),
+ *   isComposing: () => compositionHandler.isComposing(),
+ *   isReadOnly: () => config.readOnly ?? false,
+ *   generateBlockId: () => crypto.randomUUID(),
+ * };
+ * ```
+ */
+export interface InputBridgeDeps {
+    /** Get the current RTIF selection from the engine. */
+    readonly getSelection: () => Selection;
+    /** Get the current document from the engine. */
+    readonly getDoc: () => Document;
+    /** Dispatch one or more operations to the engine. */
+    readonly dispatch: (ops: Operation | Operation[]) => void;
+    /** Trigger undo on the engine. */
+    readonly undo: () => void;
+    /** Trigger redo on the engine. */
+    readonly redo: () => void;
+    /** Check whether an IME composition session is currently active. */
+    readonly isComposing: () => boolean;
+    /** Check whether the editor is in read-only mode. */
+    readonly isReadOnly: () => boolean;
+    /** Generate a unique block ID for `split_block` operations. */
+    readonly generateBlockId: () => string;
+    /**
+     * Get pending marks from the engine.
+     * When pending marks exist, inserted text should have those marks applied.
+     * Returns empty object if no pending marks.
+     */
+    readonly getPendingMarks?: () => Record<string, unknown>;
+    /**
+     * Clear pending marks on the engine after they've been consumed.
+     */
+    readonly clearPendingMarks?: () => void;
+    /**
+     * Find the range of an atomic mark containing the given offset.
+     * Returns the absolute offset and count of the mark range, or null
+     * if the offset is not inside an atomic mark.
+     */
+    readonly findAtomicMarkRange?: (offset: number) => {
+        offset: number;
+        count: number;
+    } | null;
+    /**
+     * Check whether a block type is atomic (non-editable, e.g., HR, image, embed).
+     * Used to prevent corrupt state when backspace/delete would merge into an atomic block.
+     */
+    readonly isAtomicBlock?: (blockType: string) => boolean;
+}
+/**
+ * Find the offset of the word boundary before the given local offset in block text.
+ *
+ * A "word character" is any character matching `\w` (alphanumeric + underscore).
+ * The algorithm: first skip any non-word characters (punctuation, whitespace),
+ * then skip word characters. The result is the start of the word.
+ *
+ * @param blockText - The full text of the block
+ * @param localOffset - The current cursor position within the block (0-indexed)
+ * @returns The local offset of the word boundary (always <= localOffset)
+ *
+ * @example
+ * ```ts
+ * findWordBoundaryBackward('hello world', 11); // => 6 (start of "world")
+ * findWordBoundaryBackward('hello world', 5);  // => 0 (start of "hello")
+ * ```
+ */
+export declare function findWordBoundaryBackward(blockText: string, localOffset: number): number;
+/**
+ * Find the offset of the word boundary after the given local offset in block text.
+ *
+ * The algorithm: first skip word characters, then skip non-word characters
+ * (whitespace, punctuation). The result is the position after the word
+ * and its trailing whitespace.
+ *
+ * @param blockText - The full text of the block
+ * @param localOffset - The current cursor position within the block (0-indexed)
+ * @returns The local offset of the word boundary (always >= localOffset)
+ *
+ * @example
+ * ```ts
+ * findWordBoundaryForward('hello world', 0); // => 6 (after "hello ")
+ * findWordBoundaryForward('hello world', 6); // => 11 (after "world")
+ * ```
+ */
+export declare function findWordBoundaryForward(blockText: string, localOffset: number): number;
+/**
+ * Compute the operations needed to delete a selection range.
+ *
+ * For single-block selections, returns a single `delete_text`. For cross-block
+ * selections, composes `delete_text` and `merge_block` operations that the
+ * engine can apply sequentially.
+ *
+ * The algorithm works forward through the blocks:
+ * 1. Delete the tail of the start block (from startLocalOffset to end).
+ * 2. For each subsequent block up to and including the end block:
+ *    a. Merge it into the previous block.
+ *    b. Delete the appropriate text (all text for intermediate blocks,
+ *       or endLocalOffset characters for the end block).
+ *
+ * After each merge, the text from the merged block appears at the position
+ * where the start block's tail was deleted, so all delete offsets are the
+ * same absolute offset (the start of the selection).
+ *
+ * @param doc - The current document
+ * @param selection - The selection to delete (may be forward or backward)
+ * @returns Array of operations to dispatch. Empty if selection is collapsed.
+ *
+ * @example
+ * ```ts
+ * // Single-block selection
+ * const ops = deleteSelectionOps(doc, { anchor: { offset: 2 }, focus: { offset: 7 } });
+ * // => [{ type: 'delete_text', offset: 2, count: 5 }]
+ *
+ * // Cross-block selection
+ * const ops = deleteSelectionOps(doc, { anchor: { offset: 3 }, focus: { offset: 8 } });
+ * // => [delete_text, merge_block, delete_text, ...]
+ * ```
+ */
+export declare function deleteSelectionOps(doc: Document, selection: Selection): Operation[];
+/**
+ * The InputBridge intercepts DOM `beforeinput` events on a contenteditable
+ * element and translates them into RTIF operations.
+ *
+ * This is the "controlled contenteditable" approach: most input types are
+ * prevented and handled through the RTIF engine, while IME composition
+ * events are passed through to the browser for native rendering.
+ *
+ * @example
+ * ```ts
+ * const bridge = new InputBridge(root, {
+ *   getSelection: () => engine.state.selection,
+ *   getDoc: () => engine.state.doc,
+ *   dispatch: (ops) => engine.dispatch(ops),
+ *   undo: () => engine.undo(),
+ *   redo: () => engine.redo(),
+ *   isComposing: () => compositionHandler.isComposing(),
+ *   isReadOnly: () => false,
+ *   generateBlockId: () => crypto.randomUUID(),
+ * });
+ * bridge.attach();
+ * ```
+ */
+export declare class InputBridge {
+    private readonly _root;
+    private readonly _deps;
+    private _attached;
+    /**
+     * Bound reference to the beforeinput handler so we can add/remove
+     * the same function reference.
+     */
+    private readonly _boundHandler;
+    constructor(root: HTMLElement, deps: InputBridgeDeps);
+    /**
+     * Attach the `beforeinput` event listener to the root element.
+     *
+     * Safe to call multiple times — only one listener is registered.
+     *
+     * @example
+     * ```ts
+     * bridge.attach();
+     * ```
+     */
+    attach(): void;
+    /**
+     * Remove the `beforeinput` event listener from the root element.
+     *
+     * Safe to call without a prior `attach()`.
+     *
+     * @example
+     * ```ts
+     * bridge.detach();
+     * ```
+     */
+    detach(): void;
+    /**
+     * Handle a `beforeinput` event by translating its `inputType` into
+     * RTIF operations.
+     *
+     * This method is public for testing. In production it is called by the
+     * bound event listener installed via `attach()`.
+     *
+     * @param e - The InputEvent from the `beforeinput` event
+     *
+     * @example
+     * ```ts
+     * // Typically called via the event listener, but can be called directly:
+     * bridge.handleBeforeInput(inputEvent);
+     * ```
+     */
+    handleBeforeInput(e: InputEvent): void;
+    /**
+     * Handle `insertText` and `insertCompositionText` (when not composing).
+     *
+     * When pending marks are present (e.g., user toggled bold with collapsed cursor),
+     * appends a `set_span_marks` operation after the `insert_text` to apply those
+     * marks to the newly inserted text, then clears the pending marks.
+     */
+    private _handleInsertText;
+    /**
+     * Handle `insertLineBreak` (Shift+Enter).
+     * Inserts a newline character within the current block (soft line break).
+     */
+    private _handleInsertLineBreak;
+    /**
+     * Handle `insertParagraph` (Enter key).
+     */
+    private _handleSplitBlock;
+    /**
+     * Handle `deleteContentBackward` (Backspace, 1 character).
+     */
+    private _handleDeleteBackward;
+    /**
+     * Handle `deleteContentForward` (Delete key, 1 character).
+     */
+    private _handleDeleteForward;
+    /**
+     * Handle `deleteWordBackward` (Ctrl/Option + Backspace).
+     */
+    private _handleDeleteWordBackward;
+    /**
+     * Handle `deleteWordForward` (Ctrl/Option + Delete).
+     */
+    private _handleDeleteWordForward;
+    /**
+     * Handle `deleteSoftLineBackward` and `deleteHardLineBackward`
+     * (Cmd+Backspace on Mac).
+     */
+    private _handleDeleteLineBackward;
+    /**
+     * Handle `deleteSoftLineForward` and `deleteHardLineForward`
+     * (Cmd+Delete on Mac).
+     */
+    private _handleDeleteLineForward;
+    /**
+     * Handle `insertReplacementText` (spellcheck/autocorrect acceptance).
+     *
+     * Reads the replacement text from `e.dataTransfer` or `e.data`, and
+     * the target range from `e.getTargetRanges()`. Falls back to treating
+     * the current selection as the target range if target ranges are
+     * unavailable.
+     */
+    private _handleInsertReplacement;
+}
+//# sourceMappingURL=input-bridge.d.ts.map

package/dist/input-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-bridge.d.ts","sourceRoot":"","sources":["../src/input-bridge.ts"],"names":[],"mappings":"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"}