@rtif-sdk/web 1.0.0

package/dist/content-pipeline.js

@@ -0,0 +1,232 @@
+/**
+ * Content pipeline — unified ingestion for paste, drop, and programmatic input.
+ *
+ * The content pipeline routes incoming content items through a priority-ordered
+ * chain of handlers. Each handler declares which MIME types it accepts and
+ * processes matching items into RTIF operations. All operations from a single
+ * process() call are batched into one engine.dispatch() for a single undo group.
+ *
+ * @module
+ * @see docs/plans/web/03-content-pipeline.md
+ */
+import { deleteSelectionOps } from './clipboard.js';
+// ---------------------------------------------------------------------------
+// matchesMime helper
+// ---------------------------------------------------------------------------
+/**
+ * Check whether a MIME type matches any of the given patterns.
+ *
+ * Supports exact match, wildcard subtypes (e.g., `image/*`), and
+ * catch-all (`*\/*`).
+ *
+ * @param contentType - The MIME type to test (e.g., 'text/plain')
+ * @param patterns - Array of MIME patterns to match against
+ * @returns true if the content type matches any pattern
+ *
+ * @example
+ * ```ts
+ * matchesMime('image/png', ['image/*']);       // true
+ * matchesMime('text/plain', ['text/html']);     // false
+ * matchesMime('text/plain', ['*\/*']);          // true (catch-all)
+ * ```
+ */
+export function matchesMime(contentType, patterns) {
+    for (const pattern of patterns) {
+        // Catch-all
+        if (pattern === '*/*')
+            return true;
+        // Wildcard subtype: 'image/*' matches 'image/png'
+        if (pattern.endsWith('/*')) {
+            const prefix = pattern.slice(0, -1); // 'image/'
+            if (contentType.startsWith(prefix))
+                return true;
+            continue;
+        }
+        // Exact match
+        if (contentType === pattern)
+            return true;
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a content pipeline instance.
+ *
+ * The pipeline manages a priority-ordered set of content handlers and routes
+ * incoming content items through them. All operations dispatched by handlers
+ * are buffered and flushed as a single engine.dispatch() call, ensuring each
+ * paste/drop is a single undo group.
+ *
+ * @returns A new ContentPipeline instance
+ *
+ * @example
+ * ```ts
+ * const pipeline = createContentPipeline();
+ * pipeline.register(createPlainTextHandler(() => generateId()));
+ * ```
+ */
+export function createContentPipeline() {
+    let handlers = [];
+    const eventListeners = new Set();
+    let destroyed = false;
+    /**
+     * Get handlers sorted by descending priority (higher runs first).
+     */
+    function getSortedHandlers() {
+        return [...handlers].sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+    }
+    /**
+     * Emit a pipeline event to all listeners.
+     */
+    function emit(event) {
+        for (const listener of eventListeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Event listener errors must not break the pipeline
+            }
+        }
+    }
+    /**
+     * Create a ContentContext that buffers operations for a single process() call.
+     */
+    function createContext(opts) {
+        const opsBuffer = [];
+        let selectionDeleted = false;
+        // Compute insert offset: dropOffset takes precedence, otherwise use selection
+        const sel = opts.engine.state.selection;
+        const insertOffset = opts.dropOffset !== undefined
+            ? opts.dropOffset
+            : Math.min(sel.anchor.offset, sel.focus.offset);
+        const context = {
+            engine: opts.engine,
+            commands: opts.commands,
+            insertOffset,
+            source: opts.source,
+            deleteSelectionAndGetOffset() {
+                if (selectionDeleted)
+                    return insertOffset;
+                selectionDeleted = true;
+                const currentSel = opts.engine.state.selection;
+                const doc = opts.engine.state.doc;
+                const deleteOps = deleteSelectionOps(doc, currentSel);
+                if (deleteOps.length > 0) {
+                    opsBuffer.push(...deleteOps);
+                }
+                return insertOffset;
+            },
+            dispatch(ops) {
+                opsBuffer.push(...ops);
+            },
+            generateBlockId() {
+                return opts.generateBlockId();
+            },
+        };
+        return { context, getBufferedOps: () => opsBuffer };
+    }
+    const pipeline = {
+        register(handler) {
+            if (destroyed) {
+                return { dispose: () => { } };
+            }
+            handlers.push(handler);
+            return {
+                dispose() {
+                    handlers = handlers.filter((h) => h !== handler);
+                },
+            };
+        },
+        async process(items, contextOpts) {
+            if (destroyed || items.length === 0)
+                return false;
+            // Emit contentReceived event (allows cancellation)
+            const receivedEvent = {
+                type: 'contentReceived',
+                items,
+                source: contextOpts.source,
+                prevented: false,
+                preventDefault() {
+                    this.prevented = true;
+                },
+            };
+            emit(receivedEvent);
+            if (receivedEvent.prevented)
+                return false;
+            const sorted = getSortedHandlers();
+            const { context, getBufferedOps } = createContext(contextOpts);
+            // Handler-first iteration: for each handler, check each item
+            for (const handler of sorted) {
+                for (const item of items) {
+                    // Check MIME type match
+                    if (!matchesMime(item.type, handler.accept))
+                        continue;
+                    // Optional canHandle check
+                    if (handler.canHandle) {
+                        try {
+                            const can = await handler.canHandle(item, context);
+                            if (!can)
+                                continue;
+                        }
+                        catch {
+                            // canHandle errors skip this handler
+                            continue;
+                        }
+                    }
+                    // Try to handle
+                    try {
+                        const handled = await handler.handle(item, context);
+                        if (handled) {
+                            // Flush all buffered ops as a single dispatch
+                            const allOps = getBufferedOps();
+                            if (allOps.length > 0) {
+                                contextOpts.engine.dispatch(allOps);
+                            }
+                            // Emit contentHandled
+                            emit({
+                                type: 'contentHandled',
+                                handlerId: handler.id,
+                                item,
+                            });
+                            return true;
+                        }
+                    }
+                    catch {
+                        // handler.handle() errors skip this handler+item pair
+                        continue;
+                    }
+                }
+            }
+            // No handler accepted any item — emit contentRejected for each
+            for (const item of items) {
+                const hasMatchingHandler = sorted.some((h) => matchesMime(item.type, h.accept));
+                emit({
+                    type: 'contentRejected',
+                    item,
+                    reason: hasMatchingHandler ? 'all-declined' : 'no-handler',
+                });
+            }
+            return false;
+        },
+        hasHandlerForType(type) {
+            if (destroyed)
+                return false;
+            return handlers.some((h) => matchesMime(type, h.accept));
+        },
+        onEvent(listener) {
+            eventListeners.add(listener);
+            return () => {
+                eventListeners.delete(listener);
+            };
+        },
+        destroy() {
+            destroyed = true;
+            handlers = [];
+            eventListeners.clear();
+        },
+    };
+    return pipeline;
+}
+//# sourceMappingURL=content-pipeline.js.map

package/dist/content-pipeline.js.map

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

package/dist/cursor-nav.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Keyboard navigation handler for the RTIF web editor.
+ *
+ * Handles `keydown` events for:
+ * - Undo / redo (Cmd+Z, Cmd+Shift+Z / Ctrl+Z, Ctrl+Y)
+ * - Select all (Cmd+A / Ctrl+A)
+ * - Document-level cursor movement (Cmd+Home/End, Cmd+Up/Down)
+ * - Document-level selection extension (Cmd+Shift+Home/End, Cmd+Shift+Up/Down)
+ *
+ * Arrow keys, word-level movement, and Home/End within a line are delegated
+ * to the browser's native `contenteditable` behavior. The `selectionchange`
+ * event (handled by selection-sync) reads the resulting DOM selection back
+ * into RTIF.
+ *
+ * @see docs/spec/platform-requirements.md sections 2, 3, and 5
+ */
+import type { Document, Selection, Operation } from '@rtif-sdk/core';
+/**
+ * Detect whether the current platform is macOS or iOS.
+ *
+ * Uses `navigator.platform` with a fallback for iPad Safari (which reports
+ * `"MacIntel"` but has touch support).
+ *
+ * @returns `true` on Apple platforms, `false` otherwise
+ *
+ * @example
+ * ```ts
+ * if (isMac()) {
+ *   // Use metaKey for keyboard shortcuts
+ * }
+ * ```
+ */
+export declare function isMac(): boolean;
+/**
+ * Check whether the platform modifier key is pressed.
+ *
+ * On macOS/iOS this is the Meta (Command) key; on other platforms it is
+ * the Control key.
+ *
+ * @param e - The keyboard event to inspect
+ * @returns `true` if the platform modifier key is held
+ *
+ * @example
+ * ```ts
+ * element.addEventListener('keydown', (e) => {
+ *   if (isModKey(e) && e.key === 'z') {
+ *     // undo
+ *   }
+ * });
+ * ```
+ */
+export declare function isModKey(e: KeyboardEvent): boolean;
+/**
+ * Dependencies injected into {@link CursorNavHandler}.
+ *
+ * @example
+ * ```ts
+ * const deps: CursorNavDeps = {
+ *   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,
+ *   setSelection: (sel) => { ... },
+ *   isMac: () => isMac(),
+ * };
+ * ```
+ */
+export interface CursorNavDeps {
+    /** Return the current RTIF selection. */
+    readonly getSelection: () => Selection;
+    /** Return the current RTIF document. */
+    readonly getDoc: () => Document;
+    /** Dispatch one or more RTIF 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;
+    /** Whether an IME composition session is active. */
+    readonly isComposing: () => boolean;
+    /** Whether the editor is in read-only mode. */
+    readonly isReadOnly: () => boolean;
+    /**
+     * Update the RTIF selection without dispatching an operation.
+     * This triggers DOM selection sync and onChange notification.
+     */
+    readonly setSelection: (selection: Selection) => void;
+    /** Whether the current platform is macOS/iOS. */
+    readonly isMac: () => boolean;
+}
+/**
+ * Handles `keydown` events for keyboard shortcuts and document-level
+ * cursor navigation.
+ *
+ * The handler intercepts:
+ * - **Undo/redo**: Cmd+Z, Cmd+Shift+Z (Mac) / Ctrl+Z, Ctrl+Y (Win/Linux)
+ * - **Select all**: Cmd+A / Ctrl+A
+ * - **Document start/end**: Cmd+Home, Cmd+End, Cmd+Up, Cmd+Down (Mac)
+ * - **Selection to document edges**: Cmd+Shift+Home/End/Up/Down
+ *
+ * All other key events (including arrow keys, Home/End without Cmd,
+ * word-level movement) are left to the browser's native contenteditable
+ * handling. The selection-sync module reads the resulting DOM selection
+ * back into RTIF via `selectionchange`.
+ *
+ * @example
+ * ```ts
+ * const handler = new CursorNavHandler(root, deps);
+ * handler.attach();
+ * // ... later ...
+ * handler.detach();
+ * ```
+ */
+export declare class CursorNavHandler {
+    private readonly _root;
+    private readonly _deps;
+    private _keydownHandler;
+    constructor(root: HTMLElement, deps: CursorNavDeps);
+    /**
+     * Attach the `keydown` event listener to the root element.
+     *
+     * @example
+     * ```ts
+     * handler.attach();
+     * ```
+     */
+    attach(): void;
+    /**
+     * Remove the `keydown` event listener from the root element.
+     *
+     * @example
+     * ```ts
+     * handler.detach();
+     * ```
+     */
+    detach(): void;
+    private _onKeydown;
+    /**
+     * Handle Cmd/Ctrl + Home/End/ArrowUp/ArrowDown for document-level navigation.
+     *
+     * Returns `true` if the event was handled (and preventDefault was called),
+     * `false` if the event should be left to the browser.
+     */
+    private _handleDocumentNav;
+}
+//# sourceMappingURL=cursor-nav.d.ts.map

package/dist/cursor-nav.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor-nav.d.ts","sourceRoot":"","sources":["../src/cursor-nav.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAOrE;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,KAAK,IAAI,OAAO,CAM/B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,aAAa,GAAG,OAAO,CAElD;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,QAAQ,CAAC,YAAY,EAAE,MAAM,SAAS,CAAC;IAEvC,wCAAwC;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,QAAQ,CAAC;IAEhC,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,SAAS,GAAG,SAAS,EAAE,KAAK,IAAI,CAAC;IAE1D,kCAAkC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC;IAE1B,kCAAkC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC;IAE1B,oDAAoD;IACpD,QAAQ,CAAC,WAAW,EAAE,MAAM,OAAO,CAAC;IAEpC,+CAA+C;IAC/C,QAAQ,CAAC,UAAU,EAAE,MAAM,OAAO,CAAC;IAEnC;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,SAAS,EAAE,SAAS,KAAK,IAAI,CAAC;IAEtD,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC;CAC/B;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,eAAe,CAA6C;gBAExD,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,aAAa;IAKlD;;;;;;;OAOG;IACH,MAAM,IAAI,IAAI;IAKd;;;;;;;OAOG;IACH,MAAM,IAAI,IAAI;IAWd,OAAO,CAAC,UAAU;IAuDlB;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;CA6C3B"}

package/dist/cursor-nav.js

@@ -0,0 +1,230 @@
+/**
+ * Keyboard navigation handler for the RTIF web editor.
+ *
+ * Handles `keydown` events for:
+ * - Undo / redo (Cmd+Z, Cmd+Shift+Z / Ctrl+Z, Ctrl+Y)
+ * - Select all (Cmd+A / Ctrl+A)
+ * - Document-level cursor movement (Cmd+Home/End, Cmd+Up/Down)
+ * - Document-level selection extension (Cmd+Shift+Home/End, Cmd+Shift+Up/Down)
+ *
+ * Arrow keys, word-level movement, and Home/End within a line are delegated
+ * to the browser's native `contenteditable` behavior. The `selectionchange`
+ * event (handled by selection-sync) reads the resulting DOM selection back
+ * into RTIF.
+ *
+ * @see docs/spec/platform-requirements.md sections 2, 3, and 5
+ */
+import { docLength } from '@rtif-sdk/core';
+// ---------------------------------------------------------------------------
+// Platform detection
+// ---------------------------------------------------------------------------
+/**
+ * Detect whether the current platform is macOS or iOS.
+ *
+ * Uses `navigator.platform` with a fallback for iPad Safari (which reports
+ * `"MacIntel"` but has touch support).
+ *
+ * @returns `true` on Apple platforms, `false` otherwise
+ *
+ * @example
+ * ```ts
+ * if (isMac()) {
+ *   // Use metaKey for keyboard shortcuts
+ * }
+ * ```
+ */
+export function isMac() {
+    if (typeof navigator === 'undefined')
+        return false;
+    return /Mac|iPod|iPhone|iPad/.test(navigator.platform)
+        || (navigator.platform === 'MacIntel'
+            && typeof navigator.maxTouchPoints === 'number'
+            && navigator.maxTouchPoints > 1);
+}
+/**
+ * Check whether the platform modifier key is pressed.
+ *
+ * On macOS/iOS this is the Meta (Command) key; on other platforms it is
+ * the Control key.
+ *
+ * @param e - The keyboard event to inspect
+ * @returns `true` if the platform modifier key is held
+ *
+ * @example
+ * ```ts
+ * element.addEventListener('keydown', (e) => {
+ *   if (isModKey(e) && e.key === 'z') {
+ *     // undo
+ *   }
+ * });
+ * ```
+ */
+export function isModKey(e) {
+    return isMac() ? e.metaKey : e.ctrlKey;
+}
+// ---------------------------------------------------------------------------
+// CursorNavHandler class
+// ---------------------------------------------------------------------------
+/**
+ * Handles `keydown` events for keyboard shortcuts and document-level
+ * cursor navigation.
+ *
+ * The handler intercepts:
+ * - **Undo/redo**: Cmd+Z, Cmd+Shift+Z (Mac) / Ctrl+Z, Ctrl+Y (Win/Linux)
+ * - **Select all**: Cmd+A / Ctrl+A
+ * - **Document start/end**: Cmd+Home, Cmd+End, Cmd+Up, Cmd+Down (Mac)
+ * - **Selection to document edges**: Cmd+Shift+Home/End/Up/Down
+ *
+ * All other key events (including arrow keys, Home/End without Cmd,
+ * word-level movement) are left to the browser's native contenteditable
+ * handling. The selection-sync module reads the resulting DOM selection
+ * back into RTIF via `selectionchange`.
+ *
+ * @example
+ * ```ts
+ * const handler = new CursorNavHandler(root, deps);
+ * handler.attach();
+ * // ... later ...
+ * handler.detach();
+ * ```
+ */
+export class CursorNavHandler {
+    _root;
+    _deps;
+    _keydownHandler = null;
+    constructor(root, deps) {
+        this._root = root;
+        this._deps = deps;
+    }
+    /**
+     * Attach the `keydown` event listener to the root element.
+     *
+     * @example
+     * ```ts
+     * handler.attach();
+     * ```
+     */
+    attach() {
+        this._keydownHandler = (e) => this._onKeydown(e);
+        this._root.addEventListener('keydown', this._keydownHandler);
+    }
+    /**
+     * Remove the `keydown` event listener from the root element.
+     *
+     * @example
+     * ```ts
+     * handler.detach();
+     * ```
+     */
+    detach() {
+        if (this._keydownHandler) {
+            this._root.removeEventListener('keydown', this._keydownHandler);
+            this._keydownHandler = null;
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Keydown dispatcher
+    // -----------------------------------------------------------------------
+    _onKeydown(e) {
+        // Never interfere with IME composition
+        if (this._deps.isComposing())
+            return;
+        const mod = this._deps.isMac() ? e.metaKey : e.ctrlKey;
+        // --- Undo: Cmd+Z / Ctrl+Z (no shift, no alt) ---
+        if (mod && !e.shiftKey && !e.altKey && e.key === 'z') {
+            e.preventDefault();
+            this._deps.undo();
+            return;
+        }
+        // --- Redo: Cmd+Shift+Z (Mac) / Ctrl+Y (Win/Linux) ---
+        if (this._deps.isMac()) {
+            if (e.metaKey && e.shiftKey && !e.altKey && e.key === 'z') {
+                e.preventDefault();
+                this._deps.redo();
+                return;
+            }
+        }
+        else {
+            if (e.ctrlKey && !e.shiftKey && !e.altKey && e.key === 'y') {
+                e.preventDefault();
+                this._deps.redo();
+                return;
+            }
+            // Also support Ctrl+Shift+Z on non-Mac
+            if (e.ctrlKey && e.shiftKey && !e.altKey && e.key === 'z') {
+                e.preventDefault();
+                this._deps.redo();
+                return;
+            }
+        }
+        // --- Select all: Cmd+A / Ctrl+A ---
+        if (mod && !e.shiftKey && !e.altKey && e.key === 'a') {
+            e.preventDefault();
+            const doc = this._deps.getDoc();
+            const len = docLength(doc);
+            this._deps.setSelection({
+                anchor: { offset: 0 },
+                focus: { offset: len },
+            });
+            return;
+        }
+        // --- Document-level navigation ---
+        // These handle Cmd+Home/End and Cmd+Up/Down (Mac equivalents).
+        // With Shift held, they extend selection instead of moving cursor.
+        if (mod && !e.altKey) {
+            if (this._handleDocumentNav(e))
+                return;
+        }
+    }
+    /**
+     * Handle Cmd/Ctrl + Home/End/ArrowUp/ArrowDown for document-level navigation.
+     *
+     * Returns `true` if the event was handled (and preventDefault was called),
+     * `false` if the event should be left to the browser.
+     */
+    _handleDocumentNav(e) {
+        const doc = this._deps.getDoc();
+        const len = docLength(doc);
+        const sel = this._deps.getSelection();
+        // Move to document start
+        if (e.key === 'Home' || (this._deps.isMac() && e.key === 'ArrowUp')) {
+            e.preventDefault();
+            if (e.shiftKey) {
+                // Extend selection: keep anchor, move focus to 0
+                this._deps.setSelection({
+                    anchor: sel.anchor,
+                    focus: { offset: 0 },
+                });
+            }
+            else {
+                // Collapse cursor to document start
+                this._deps.setSelection({
+                    anchor: { offset: 0 },
+                    focus: { offset: 0 },
+                });
+            }
+            return true;
+        }
+        // Move to document end
+        if (e.key === 'End' || (this._deps.isMac() && e.key === 'ArrowDown')) {
+            e.preventDefault();
+            if (e.shiftKey) {
+                // Extend selection: keep anchor, move focus to end
+                this._deps.setSelection({
+                    anchor: sel.anchor,
+                    focus: { offset: len },
+                });
+            }
+            else {
+                // Collapse cursor to document end
+                this._deps.setSelection({
+                    anchor: { offset: len },
+                    focus: { offset: len },
+                });
+            }
+            return true;
+        }
+        return false;
+    }
+}
+//# sourceMappingURL=cursor-nav.js.map

package/dist/cursor-nav.js.map

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