@rtif-sdk/web 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cory Robinson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# @rtif-sdk/web
+
+Web platform implementation for RTIF (Rich Text Input Format). A vanilla TypeScript rich text editor built on `contenteditable`, with plugin presets, keyboard shortcuts, clipboard handling, IME support, and accessibility.
+
+## Install
+
+```bash
+npm install @rtif-sdk/web
+```
+
+## Quick Start
+
+```typescript
+import { createWebEditor, PRESET_STANDARD } from '@rtif-sdk/web';
+
+const editor = createWebEditor({
+  root: document.getElementById('editor')!,
+  plugins: PRESET_STANDARD,
+  placeholder: 'Start typing...',
+  accessibleLabel: 'Document editor',
+});
+
+// Subscribe to changes
+editor.onChange((state) => {
+  console.log('Document:', JSON.stringify(state.doc));
+});
+```
+
+## Presets
+
+Four plugin presets are included, each a superset of the previous:
+
+| Preset | Plugins | Includes |
+|--------|---------|----------|
+| `PRESET_PLAINTEXT` | 0 | No formatting |
+| `PRESET_BASIC` | 4 | Bold, italic, underline, link |
+| `PRESET_STANDARD` | 11 | + strikethrough, code, heading, list, blockquote, code block, HR |
+| `PRESET_FULL` | 19 | + text color, font size, font family, alignment, indent, callout, image, embed |
+
+## Features
+
+- 8 RTIF operation types with full undo/redo
+- IME/composition input (CJK, accent keys, dictation)
+- Clipboard: copy/cut/paste with RTIF JSON, HTML, and plain text formats
+- Keyboard shortcuts (Cmd/Ctrl+B, I, U, K, Z, etc.)
+- Plugin system for custom block types, marks, commands, and input rules
+- Content pipeline for paste/drop handling (images, URLs, files)
+- @mention trigger infrastructure
+- Accessibility: ARIA roles, keyboard-only operation, screen reader support
+
+## Plugin Kit
+
+Create custom plugins with minimal boilerplate:
+
+```typescript
+import { defineBooleanMark, defineBlockType } from '@rtif-sdk/web';
+
+const highlight = defineBooleanMark({
+  markType: 'highlight',
+  shortcut: { key: 'h', mod: true, shift: true },
+  renderer: { apply(el) { el.style.backgroundColor = 'yellow'; } },
+});
+```
+
+## License
+
+MIT

package/dist/block-drag-handler.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Block drag-and-drop handler — enables reordering blocks via drag handles.
+ *
+ * Provides two main exports:
+ * - {@link computeMoveBlockOps} — Pure function that computes the RTIF operations
+ *   needed to move a block from one position to another.
+ * - {@link BlockDragHandler} — DOM event handler class that manages drag handles,
+ *   drag events, drop indicator, and dispatches move operations.
+ *
+ * Since RTIF has no `move_block` core operation, block reordering is composed
+ * from existing operations: `delete_text`, `merge_block`, `split_block`,
+ * `insert_text`, `set_block_type`, `set_block_attrs`, and `set_span_marks`.
+ *
+ * @module
+ */
+import type { Document, Operation } from '@rtif-sdk/core';
+/**
+ * Dependencies injected into {@link BlockDragHandler}.
+ *
+ * This keeps the handler decoupled from the editor wiring and makes
+ * it testable in isolation.
+ *
+ * @example
+ * ```ts
+ * const deps: BlockDragHandlerDeps = {
+ *   root: editorRoot,
+ *   getDoc: () => engine.state.doc,
+ *   dispatch: (ops) => engine.dispatch(ops),
+ *   isReadOnly: () => false,
+ * };
+ * ```
+ */
+export interface BlockDragHandlerDeps {
+    /** The editor's contenteditable root element. */
+    readonly root: HTMLElement;
+    /** Return the current RTIF document. */
+    readonly getDoc: () => Document;
+    /** Dispatch one or more RTIF operations to the engine. */
+    readonly dispatch: (ops: Operation | Operation[]) => void;
+    /** Whether the editor is in read-only mode. */
+    readonly isReadOnly: () => boolean;
+}
+/**
+ * Compute the shallow-merge diff needed to transform `currentAttrs` into
+ * `targetAttrs` via a single `set_block_attrs` operation.
+ *
+ * Returns `null` if no changes are needed (attrs are already equivalent).
+ *
+ * @param currentAttrs - The block's current attrs (may be undefined)
+ * @param targetAttrs - The desired attrs (may be undefined)
+ * @returns An attrs diff object for `set_block_attrs`, or null if no diff
+ *
+ * @example
+ * ```ts
+ * computeAttrsDiff({ level: 1 }, { level: 2 });
+ * // => { level: 2 }
+ *
+ * computeAttrsDiff({ level: 1, indent: 2 }, { color: 'red' });
+ * // => { level: null, indent: null, color: 'red' }
+ *
+ * computeAttrsDiff({ level: 1 }, { level: 1 });
+ * // => null
+ * ```
+ */
+export declare function computeAttrsDiff(currentAttrs: Record<string, unknown> | undefined, targetAttrs: Record<string, unknown> | undefined): Record<string, unknown> | null;
+/**
+ * Compute the RTIF operations needed to move a block to a new position.
+ *
+ * This is a pure function that takes the current document, the block ID to
+ * move, and the desired target index in the final array. It returns an
+ * array of RTIF operations that, when applied in sequence, produce a
+ * document with the block at the target position.
+ *
+ * The algorithm has three phases:
+ * 1. **Remove** — Delete the source block's text and merge it away
+ * 2. **Create** — Split at the target position to create an empty block
+ * 3. **Restore** — Insert text, set type/attrs, apply marks
+ *
+ * Block IDs are preserved when the source block is not the first block
+ * and the target position is not 0. In the target=0 case, the moved
+ * block inherits the ID of the block that was previously at index 0.
+ *
+ * @param doc - The current RTIF document
+ * @param blockId - The ID of the block to move
+ * @param targetIndex - The desired final index (0-based) in the result
+ * @returns Array of operations to apply, or empty array if no move needed
+ *
+ * @example
+ * ```ts
+ * // Move third block to first position
+ * const ops = computeMoveBlockOps(doc, 'b3', 0);
+ * for (const op of ops) {
+ *   const result = apply(currentDoc, op);
+ *   currentDoc = result.doc;
+ * }
+ * ```
+ */
+export declare function computeMoveBlockOps(doc: Document, blockId: string, targetIndex: number): Operation[];
+/**
+ * DOM event handler for block drag-and-drop reordering.
+ *
+ * Shows a drag handle on block hover. When the user drags a block handle
+ * and drops it between other blocks, computes and dispatches the RTIF
+ * operations to move the block to the new position.
+ *
+ * Uses the existing {@link DropIndicator} for visual drop feedback.
+ *
+ * @example
+ * ```ts
+ * const handler = new BlockDragHandler({
+ *   root: editorRoot,
+ *   getDoc: () => engine.state.doc,
+ *   dispatch: (ops) => engine.dispatch(ops),
+ *   isReadOnly: () => false,
+ * });
+ *
+ * handler.attach();
+ * // ... user drags blocks ...
+ * handler.detach();
+ * ```
+ */
+export declare class BlockDragHandler {
+    private readonly _deps;
+    private readonly _dropIndicator;
+    private _dragBlockId;
+    private _handleEl;
+    private _attached;
+    private readonly _onMouseOver;
+    private readonly _onMouseOut;
+    private readonly _onDragStart;
+    private readonly _onDragOver;
+    private readonly _onDragLeave;
+    private readonly _onDrop;
+    private readonly _onDragEnd;
+    /**
+     * Create a block drag handler.
+     *
+     * @param deps - Injected dependencies
+     *
+     * @example
+     * ```ts
+     * const handler = new BlockDragHandler(deps);
+     * handler.attach();
+     * ```
+     */
+    constructor(deps: BlockDragHandlerDeps);
+    /**
+     * Attach event listeners to the editor root.
+     *
+     * @example
+     * ```ts
+     * handler.attach();
+     * ```
+     */
+    attach(): void;
+    /**
+     * Detach event listeners and clean up DOM.
+     *
+     * @example
+     * ```ts
+     * handler.detach();
+     * ```
+     */
+    detach(): void;
+    /**
+     * Show the drag handle next to a block element.
+     */
+    private _showHandle;
+    /**
+     * Hide the drag handle.
+     */
+    private _hideHandle;
+    /**
+     * Remove the drag handle from the DOM.
+     */
+    private _removeHandle;
+    private _handleMouseOver;
+    private _handleMouseOut;
+    private _handleDragStart;
+    private _handleDragOver;
+    private _handleDragLeave;
+    private _handleDrop;
+    private _handleDragEnd;
+    /**
+     * Clean up drag state after drop or cancel.
+     */
+    private _cleanup;
+}
+//# sourceMappingURL=block-drag-handler.d.ts.map

package/dist/block-drag-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-drag-handler.d.ts","sourceRoot":"","sources":["../src/block-drag-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAe,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAgBvE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,oBAAoB;IACnC,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAE3B,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,+CAA+C;IAC/C,QAAQ,CAAC,UAAU,EAAE,MAAM,OAAO,CAAC;CACpC;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EACjD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC/C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAwBhC;AA6BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,GAClB,SAAS,EAAE,CAqOb;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuB;IAC7C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgB;IAC/C,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,SAAS,CAA4B;IAC7C,OAAO,CAAC,SAAS,CAAS;IAG1B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA0B;IACvD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA0B;IACtD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyB;IACtD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAyB;IACrD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyB;IACtD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IACjD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyB;IAEpD;;;;;;;;;;OAUG;gBACS,IAAI,EAAE,oBAAoB;IActC;;;;;;;OAOG;IACH,MAAM,IAAI,IAAI;IAcd;;;;;;;OAOG;IACH,MAAM,IAAI,IAAI;IAsBd;;OAEG;IACH,OAAO,CAAC,WAAW;IAyBnB;;OAEG;IACH,OAAO,CAAC,WAAW;IAMnB;;OAEG;IACH,OAAO,CAAC,aAAa;IAWrB,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,eAAe;IAevB,OAAO,CAAC,gBAAgB;IAiCxB,OAAO,CAAC,eAAe;IAiBvB,OAAO,CAAC,gBAAgB;IAaxB,OAAO,CAAC,WAAW;IAgCnB,OAAO,CAAC,cAAc;IAItB;;OAEG;IACH,OAAO,CAAC,QAAQ;CAcjB"}