@rtif-sdk/web 1.0.0

package/dist/composition.d.ts

@@ -0,0 +1,220 @@
+/**
+ * IME composition state machine for the RTIF web editor.
+ *
+ * During composition (CJK input, accent dead keys, dictation, emoji picker),
+ * the browser owns the DOM in the composing block. RTIF operations are NOT
+ * dispatched and the composing block is NOT reconciled until the composition
+ * session ends. On commit, a single {@link CompositionCommit} is returned
+ * so the caller can dispatch the appropriate RTIF operations.
+ *
+ * State machine:
+ * ```
+ * IDLE --compositionstart--> COMPOSING --compositionend--> IDLE
+ *                                |                           |
+ *                        (browser renders preview)   (commit RTIF ops)
+ *                        (no RTIF ops dispatched)
+ * ```
+ *
+ * @module
+ */
+import type { Selection } from '@rtif-sdk/core';
+import type { CompositionState } from './types.js';
+/**
+ * The result of a completed composition session.
+ *
+ * Returned by {@link CompositionHandler.onCompositionEnd} when the user
+ * commits text. The caller is responsible for dispatching the corresponding
+ * RTIF operations (delete selection range if present, then insert text).
+ *
+ * @example
+ * ```ts
+ * const commit = compositionHandler.onCompositionEnd(event);
+ * if (commit) {
+ *   if (commit.deleteRange) {
+ *     engine.dispatch({ type: 'delete_text', offset: commit.deleteRange.offset, count: commit.deleteRange.count });
+ *   }
+ *   engine.dispatch({ type: 'insert_text', offset: commit.offset, text: commit.text });
+ * }
+ * ```
+ */
+export interface CompositionCommit {
+    /** The committed text from the composition session. */
+    readonly text: string;
+    /** The absolute document offset where the text should be inserted. */
+    readonly offset: number;
+    /**
+     * If the user had a non-collapsed selection when composition started,
+     * this range should be deleted before inserting the committed text.
+     * Deletion happens on commit, not on start, to avoid breaking IME.
+     */
+    readonly deleteRange: {
+        readonly offset: number;
+        readonly count: number;
+    } | null;
+}
+/**
+ * Dependencies injected into the {@link CompositionHandler}.
+ *
+ * These callbacks allow the handler to read editor state without
+ * depending directly on the engine or DOM.
+ */
+export interface CompositionDeps {
+    /**
+     * Return the current RTIF selection from the engine, or null if
+     * the editor has no selection (e.g. during initialization).
+     */
+    readonly getSelection: () => Selection | null;
+    /**
+     * Resolve an absolute document offset to the block ID at that position.
+     * Returns null if the offset cannot be resolved.
+     *
+     * @param offset - Absolute document offset
+     */
+    readonly getBlockIdAtOffset: (offset: number) => string | null;
+}
+/**
+ * Manages IME composition state for the RTIF web editor.
+ *
+ * Attach the three `onComposition*` methods to the corresponding DOM events
+ * on the contenteditable element. The handler tracks whether a composition
+ * session is active and produces a {@link CompositionCommit} when the session
+ * ends with committed text.
+ *
+ * During `isComposing() === true`:
+ * - The InputBridge must NOT dispatch RTIF operations for composition-related
+ *   `beforeinput` events (`insertCompositionText`, `deleteByComposition`).
+ * - The InputBridge must NOT call `preventDefault()` on those events.
+ * - The Renderer must NOT reconcile the composing block.
+ *
+ * @example
+ * ```ts
+ * const handler = new CompositionHandler({
+ *   getSelection: () => engine.state.selection,
+ *   getBlockIdAtOffset: (offset) => {
+ *     const { blockIndex } = resolve(engine.state.doc, offset);
+ *     return engine.state.doc.blocks[blockIndex]?.id ?? null;
+ *   },
+ * });
+ *
+ * el.addEventListener('compositionstart', (e) => handler.onCompositionStart(e));
+ * el.addEventListener('compositionupdate', (e) => handler.onCompositionUpdate(e));
+ * el.addEventListener('compositionend', (e) => {
+ *   const commit = handler.onCompositionEnd(e);
+ *   if (commit) {
+ *     // dispatch RTIF operations from commit
+ *   }
+ * });
+ * ```
+ */
+export declare class CompositionHandler {
+    private _composing;
+    private _composingBlockId;
+    private _startOffset;
+    private _selectionRange;
+    private readonly _deps;
+    constructor(deps: CompositionDeps);
+    /**
+     * Handle the `compositionstart` DOM event.
+     *
+     * Enters the composing state. Reads the current RTIF selection to
+     * determine where the composition will insert text. If a non-collapsed
+     * selection exists, records it so the range can be deleted on commit
+     * (not on start, to avoid breaking IME).
+     *
+     * Does NOT call `preventDefault()` — the browser must be allowed to
+     * render its native composition preview.
+     *
+     * @param _e - The compositionstart event (data not used)
+     */
+    onCompositionStart(_e: CompositionEvent): void;
+    /**
+     * Handle the `compositionupdate` DOM event.
+     *
+     * This is intentionally a no-op. The browser is rendering its native
+     * composition preview and we must not interfere. No RTIF operations
+     * are dispatched during composition.
+     *
+     * @param _e - The compositionupdate event (ignored)
+     */
+    onCompositionUpdate(_e: CompositionEvent): void;
+    /**
+     * Handle the `compositionend` DOM event.
+     *
+     * Exits the composing state and returns a {@link CompositionCommit}
+     * describing the text to insert and any selection range to delete.
+     *
+     * Returns `null` if:
+     * - The committed text (`e.data`) is empty or null (composition cancelled)
+     * - No composition was in progress (`compositionstart` was never received)
+     * - The start offset is unknown (selection was null at composition start)
+     *
+     * The caller is responsible for dispatching RTIF operations from the
+     * returned commit.
+     *
+     * @param e - The compositionend event containing the committed text
+     * @returns A commit descriptor, or `null` if no operation should be dispatched
+     */
+    onCompositionEnd(e: CompositionEvent): CompositionCommit | null;
+    /**
+     * Whether a composition session is currently active.
+     *
+     * When `true`, the InputBridge and Renderer must defer to the browser's
+     * native composition handling.
+     *
+     * @returns `true` if between `compositionstart` and `compositionend`
+     *
+     * @example
+     * ```ts
+     * if (compositionHandler.isComposing()) {
+     *   // Skip RTIF operation dispatch and DOM reconciliation
+     * }
+     * ```
+     */
+    isComposing(): boolean;
+    /**
+     * The block ID where the current composition is occurring.
+     *
+     * Used by the Renderer to skip reconciliation of this block during
+     * composition. Returns `null` when not composing or when the block
+     * could not be resolved.
+     *
+     * @returns The composing block ID, or `null`
+     *
+     * @example
+     * ```ts
+     * const blockId = compositionHandler.getComposingBlockId();
+     * reconcile(root, prevDoc, nextDoc, blockId);
+     * ```
+     */
+    getComposingBlockId(): string | null;
+    /**
+     * Return a snapshot of the current composition state.
+     *
+     * The returned object is a plain value — it will not change when the
+     * handler's internal state changes.
+     *
+     * @returns An immutable snapshot of the composition state
+     *
+     * @example
+     * ```ts
+     * const state = compositionHandler.getState();
+     * console.log(state.composing, state.composingBlockId);
+     * ```
+     */
+    getState(): CompositionState;
+    /**
+     * Force-reset the handler to idle state.
+     *
+     * Use this when the editor blurs, is destroyed, or needs to abandon
+     * a composition session for any reason.
+     *
+     * @example
+     * ```ts
+     * el.addEventListener('blur', () => compositionHandler.reset());
+     * ```
+     */
+    reset(): void;
+    /** Clear all internal state to the idle defaults. */
+    private _resetInternal;
+}
+//# sourceMappingURL=composition.d.ts.map

package/dist/composition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition.d.ts","sourceRoot":"","sources":["../src/composition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAMnD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE;QACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;KACxB,GAAG,IAAI,CAAC;CACV;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,SAAS,GAAG,IAAI,CAAC;IAE9C;;;;;OAKG;IACH,QAAQ,CAAC,kBAAkB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CAChE;AAiBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,iBAAiB,CAAuB;IAChD,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,eAAe,CAAiE;IAExF,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;gBAE5B,IAAI,EAAE,eAAe;IAQjC;;;;;;;;;;;;OAYG;IACH,kBAAkB,CAAC,EAAE,EAAE,gBAAgB,GAAG,IAAI;IAgC9C;;;;;;;;OAQG;IACH,mBAAmB,CAAC,EAAE,EAAE,gBAAgB,GAAG,IAAI;IAI/C;;;;;;;;;;;;;;;;OAgBG;IACH,gBAAgB,CAAC,CAAC,EAAE,gBAAgB,GAAG,iBAAiB,GAAG,IAAI;IAgD/D;;;;;;;;;;;;;;OAcG;IACH,WAAW,IAAI,OAAO;IAItB;;;;;;;;;;;;;;OAcG;IACH,mBAAmB,IAAI,MAAM,GAAG,IAAI;IAIpC;;;;;;;;;;;;;OAaG;IACH,QAAQ,IAAI,gBAAgB;IAa5B;;;;;;;;;;OAUG;IACH,KAAK,IAAI,IAAI;IAQb,qDAAqD;IACrD,OAAO,CAAC,cAAc;CAMvB"}

package/dist/composition.js

@@ -0,0 +1,271 @@
+/**
+ * IME composition state machine for the RTIF web editor.
+ *
+ * During composition (CJK input, accent dead keys, dictation, emoji picker),
+ * the browser owns the DOM in the composing block. RTIF operations are NOT
+ * dispatched and the composing block is NOT reconciled until the composition
+ * session ends. On commit, a single {@link CompositionCommit} is returned
+ * so the caller can dispatch the appropriate RTIF operations.
+ *
+ * State machine:
+ * ```
+ * IDLE --compositionstart--> COMPOSING --compositionend--> IDLE
+ *                                |                           |
+ *                        (browser renders preview)   (commit RTIF ops)
+ *                        (no RTIF ops dispatched)
+ * ```
+ *
+ * @module
+ */
+// ---------------------------------------------------------------------------
+// Idle state singleton (avoids re-creating the same object)
+// ---------------------------------------------------------------------------
+const IDLE_STATE = {
+    composing: false,
+    composingBlockId: null,
+    startOffset: null,
+    selectionRange: null,
+};
+// ---------------------------------------------------------------------------
+// CompositionHandler
+// ---------------------------------------------------------------------------
+/**
+ * Manages IME composition state for the RTIF web editor.
+ *
+ * Attach the three `onComposition*` methods to the corresponding DOM events
+ * on the contenteditable element. The handler tracks whether a composition
+ * session is active and produces a {@link CompositionCommit} when the session
+ * ends with committed text.
+ *
+ * During `isComposing() === true`:
+ * - The InputBridge must NOT dispatch RTIF operations for composition-related
+ *   `beforeinput` events (`insertCompositionText`, `deleteByComposition`).
+ * - The InputBridge must NOT call `preventDefault()` on those events.
+ * - The Renderer must NOT reconcile the composing block.
+ *
+ * @example
+ * ```ts
+ * const handler = new CompositionHandler({
+ *   getSelection: () => engine.state.selection,
+ *   getBlockIdAtOffset: (offset) => {
+ *     const { blockIndex } = resolve(engine.state.doc, offset);
+ *     return engine.state.doc.blocks[blockIndex]?.id ?? null;
+ *   },
+ * });
+ *
+ * el.addEventListener('compositionstart', (e) => handler.onCompositionStart(e));
+ * el.addEventListener('compositionupdate', (e) => handler.onCompositionUpdate(e));
+ * el.addEventListener('compositionend', (e) => {
+ *   const commit = handler.onCompositionEnd(e);
+ *   if (commit) {
+ *     // dispatch RTIF operations from commit
+ *   }
+ * });
+ * ```
+ */
+export class CompositionHandler {
+    _composing = false;
+    _composingBlockId = null;
+    _startOffset = null;
+    _selectionRange = null;
+    _deps;
+    constructor(deps) {
+        this._deps = deps;
+    }
+    // -----------------------------------------------------------------------
+    // Event handlers
+    // -----------------------------------------------------------------------
+    /**
+     * Handle the `compositionstart` DOM event.
+     *
+     * Enters the composing state. Reads the current RTIF selection to
+     * determine where the composition will insert text. If a non-collapsed
+     * selection exists, records it so the range can be deleted on commit
+     * (not on start, to avoid breaking IME).
+     *
+     * Does NOT call `preventDefault()` — the browser must be allowed to
+     * render its native composition preview.
+     *
+     * @param _e - The compositionstart event (data not used)
+     */
+    onCompositionStart(_e) {
+        this._composing = true;
+        const selection = this._deps.getSelection();
+        if (selection === null) {
+            // No selection available — store nulls, compositionEnd will return null
+            this._composingBlockId = null;
+            this._startOffset = null;
+            this._selectionRange = null;
+            return;
+        }
+        const anchorOffset = selection.anchor.offset;
+        const focusOffset = selection.focus.offset;
+        // startOffset is always the focus position (where composition occurs)
+        this._startOffset = focusOffset;
+        // Resolve composing block from the focus offset
+        this._composingBlockId = this._deps.getBlockIdAtOffset(focusOffset);
+        // Record selection range if non-collapsed
+        if (anchorOffset !== focusOffset) {
+            const start = Math.min(anchorOffset, focusOffset);
+            const end = Math.max(anchorOffset, focusOffset);
+            this._selectionRange = { start, end };
+        }
+        else {
+            this._selectionRange = null;
+        }
+    }
+    /**
+     * Handle the `compositionupdate` DOM event.
+     *
+     * This is intentionally a no-op. The browser is rendering its native
+     * composition preview and we must not interfere. No RTIF operations
+     * are dispatched during composition.
+     *
+     * @param _e - The compositionupdate event (ignored)
+     */
+    onCompositionUpdate(_e) {
+        // Intentional no-op. Browser renders the composition preview.
+    }
+    /**
+     * Handle the `compositionend` DOM event.
+     *
+     * Exits the composing state and returns a {@link CompositionCommit}
+     * describing the text to insert and any selection range to delete.
+     *
+     * Returns `null` if:
+     * - The committed text (`e.data`) is empty or null (composition cancelled)
+     * - No composition was in progress (`compositionstart` was never received)
+     * - The start offset is unknown (selection was null at composition start)
+     *
+     * The caller is responsible for dispatching RTIF operations from the
+     * returned commit.
+     *
+     * @param e - The compositionend event containing the committed text
+     * @returns A commit descriptor, or `null` if no operation should be dispatched
+     */
+    onCompositionEnd(e) {
+        // If we weren't composing, nothing to commit
+        const wasComposing = this._composing;
+        const startOffset = this._startOffset;
+        const selectionRange = this._selectionRange;
+        // Always reset state, even if we return null
+        this._resetInternal();
+        if (!wasComposing) {
+            return null;
+        }
+        // If startOffset is null, we can't produce a valid commit
+        if (startOffset === null) {
+            return null;
+        }
+        // Check for cancelled composition (empty or null data)
+        const committedText = e.data;
+        if (!committedText) {
+            return null;
+        }
+        // Build the commit
+        let deleteRange = null;
+        let insertOffset = startOffset;
+        if (selectionRange !== null) {
+            deleteRange = {
+                offset: selectionRange.start,
+                count: selectionRange.end - selectionRange.start,
+            };
+            // Insertion happens at the start of the deleted range
+            insertOffset = selectionRange.start;
+        }
+        return {
+            text: committedText,
+            offset: insertOffset,
+            deleteRange,
+        };
+    }
+    // -----------------------------------------------------------------------
+    // State queries
+    // -----------------------------------------------------------------------
+    /**
+     * Whether a composition session is currently active.
+     *
+     * When `true`, the InputBridge and Renderer must defer to the browser's
+     * native composition handling.
+     *
+     * @returns `true` if between `compositionstart` and `compositionend`
+     *
+     * @example
+     * ```ts
+     * if (compositionHandler.isComposing()) {
+     *   // Skip RTIF operation dispatch and DOM reconciliation
+     * }
+     * ```
+     */
+    isComposing() {
+        return this._composing;
+    }
+    /**
+     * The block ID where the current composition is occurring.
+     *
+     * Used by the Renderer to skip reconciliation of this block during
+     * composition. Returns `null` when not composing or when the block
+     * could not be resolved.
+     *
+     * @returns The composing block ID, or `null`
+     *
+     * @example
+     * ```ts
+     * const blockId = compositionHandler.getComposingBlockId();
+     * reconcile(root, prevDoc, nextDoc, blockId);
+     * ```
+     */
+    getComposingBlockId() {
+        return this._composingBlockId;
+    }
+    /**
+     * Return a snapshot of the current composition state.
+     *
+     * The returned object is a plain value — it will not change when the
+     * handler's internal state changes.
+     *
+     * @returns An immutable snapshot of the composition state
+     *
+     * @example
+     * ```ts
+     * const state = compositionHandler.getState();
+     * console.log(state.composing, state.composingBlockId);
+     * ```
+     */
+    getState() {
+        if (!this._composing) {
+            return IDLE_STATE;
+        }
+        return {
+            composing: this._composing,
+            composingBlockId: this._composingBlockId,
+            startOffset: this._startOffset,
+            selectionRange: this._selectionRange,
+        };
+    }
+    /**
+     * Force-reset the handler to idle state.
+     *
+     * Use this when the editor blurs, is destroyed, or needs to abandon
+     * a composition session for any reason.
+     *
+     * @example
+     * ```ts
+     * el.addEventListener('blur', () => compositionHandler.reset());
+     * ```
+     */
+    reset() {
+        this._resetInternal();
+    }
+    // -----------------------------------------------------------------------
+    // Private
+    // -----------------------------------------------------------------------
+    /** Clear all internal state to the idle defaults. */
+    _resetInternal() {
+        this._composing = false;
+        this._composingBlockId = null;
+        this._startOffset = null;
+        this._selectionRange = null;
+    }
+}
+//# sourceMappingURL=composition.js.map

package/dist/composition.js.map

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

package/dist/content-extraction.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Content extraction — converts browser clipboard and drag events into
+ * {@link ContentItem} arrays for the content pipeline.
+ *
+ * This module bridges between the browser's DataTransfer API and the
+ * content pipeline's abstract ContentItem interface. It handles deduplication,
+ * lazy data access, and file wrapping.
+ *
+ * @module
+ */
+import type { ContentItem, ContentItemSource } from './content-pipeline.js';
+/**
+ * Extract content items from a ClipboardEvent.
+ *
+ * Uses the `DataTransferItemList` API when available for lazy data access.
+ * Falls back to `getData()` for string types. Deduplicates entries where both
+ * APIs provide the same MIME type.
+ *
+ * @param e - The clipboard event (from a 'paste' handler)
+ * @returns Array of ContentItem objects for pipeline processing
+ *
+ * @example
+ * ```ts
+ * root.addEventListener('paste', (e) => {
+ *   e.preventDefault();
+ *   const items = extractFromPaste(e);
+ *   pipeline.process(items, contextOpts);
+ * });
+ * ```
+ */
+export declare function extractFromPaste(e: ClipboardEvent): ContentItem[];
+/**
+ * Extract content items from a DragEvent.
+ *
+ * Uses the `DataTransferItemList` API when available, falling back to
+ * `DataTransfer.files` and `getData()`. Items are created with source 'drop'.
+ *
+ * @param e - The drag event (from a 'drop' handler)
+ * @returns Array of ContentItem objects for pipeline processing
+ *
+ * @example
+ * ```ts
+ * root.addEventListener('drop', (e) => {
+ *   e.preventDefault();
+ *   const items = extractFromDrop(e);
+ *   pipeline.process(items, contextOpts);
+ * });
+ * ```
+ */
+export declare function extractFromDrop(e: DragEvent): ContentItem[];
+/**
+ * Create a ContentItem from a File object.
+ *
+ * The `getString()` method returns `file.text()` for text MIME types,
+ * null otherwise. `getFile()` and `getBlob()` always return the file.
+ *
+ * @param file - The File to wrap
+ * @param source - How the file entered the editor
+ * @returns A ContentItem wrapping the file
+ *
+ * @example
+ * ```ts
+ * const fileInput = document.querySelector('input[type=file]');
+ * const file = fileInput.files[0];
+ * const item = fileToContentItem(file, 'input');
+ * ```
+ */
+export declare function fileToContentItem(file: File, source: ContentItemSource): ContentItem;
+//# sourceMappingURL=content-extraction.d.ts.map

package/dist/content-extraction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-extraction.d.ts","sourceRoot":"","sources":["../src/content-extraction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAM5E;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,cAAc,GAAG,WAAW,EAAE,CAKjE;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,SAAS,GAAG,WAAW,EAAE,CAK3D;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,iBAAiB,GACxB,WAAW,CAiBb"}