@rtif-sdk/web 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,216 @@
+import type { IEditorEngine } from '@rtif-sdk/engine';
+/**
+ * Configuration for creating a web editor instance.
+ *
+ * @example
+ * ```ts
+ * const config: WebEditorConfig = {
+ *   root: document.getElementById('editor')!,
+ *   engine: createEngine({ initialDoc: myDoc }),
+ *   placeholder: 'Type something...',
+ *   accessibleLabel: 'Document editor',
+ * };
+ * ```
+ */
+export interface WebEditorConfig {
+    /** Target DOM element. Will become the contenteditable root. */
+    readonly root: HTMLElement;
+    /**
+     * The RTIF engine instance. The caller creates and owns this.
+     * The web editor reads state and dispatches operations through it.
+     */
+    readonly engine: IEditorEngine;
+    /** Placeholder text displayed when the document is empty. */
+    readonly placeholder?: string;
+    /**
+     * When true, all mutations are blocked. Selection and copy remain available.
+     * Default: false.
+     */
+    readonly readOnly?: boolean;
+    /**
+     * Accessible label applied to the contenteditable element via `aria-label`.
+     * Required for screen reader support per platform-requirements section 9.1.
+     */
+    readonly accessibleLabel: string;
+    /**
+     * Whether to enable the browser's built-in spellcheck.
+     * Default: true.
+     */
+    readonly spellcheck?: boolean;
+    /**
+     * Whether to focus the editor automatically on creation.
+     * Default: false.
+     */
+    readonly autoFocus?: boolean;
+    /**
+     * Custom web plugins to install.
+     *
+     * Each {@link WebPlugin} bundles an engine plugin with optional web-layer
+     * renderers. Plugins are installed after built-in renderers but before the
+     * initial render, so their renderers take effect immediately.
+     *
+     * @example
+     * ```ts
+     * import { defineBooleanMark, createWebEditor } from '@rtif-sdk/web';
+     *
+     * const highlight = defineBooleanMark({
+     *   markType: 'highlight',
+     *   renderer: { apply(el) { el.style.backgroundColor = 'yellow'; } },
+     * });
+     *
+     * createWebEditor({ ..., webPlugins: [highlight] });
+     * ```
+     */
+    readonly webPlugins?: ReadonlyArray<import('./plugin-kit.js').WebPlugin>;
+}
+/**
+ * The web editor instance returned by `createWebEditor`.
+ *
+ * Provides imperative control over the editor's focus state and lifecycle.
+ * All document mutations go through `engine.dispatch()`.
+ *
+ * @example
+ * ```ts
+ * const editor = createWebEditor(config);
+ * editor.focus();
+ * // ... user edits ...
+ * editor.destroy();
+ * ```
+ */
+export interface WebEditor {
+    /** The underlying RTIF engine instance. */
+    readonly engine: IEditorEngine;
+    /** The command bus for executing commands and querying state from toolbars. */
+    readonly commandBus: import('./command-bus.js').CommandBus;
+    /** The content pipeline for registering custom content handlers. */
+    readonly content: import('./content-pipeline.js').ContentPipeline;
+    /** The mark renderer registry for customizing mark visual rendering. */
+    readonly markRenderers: import('./mark-renderer.js').MarkRendererRegistry;
+    /** The block renderer registry for customizing block type visual rendering. */
+    readonly blockRenderers: import('./block-renderer.js').BlockRendererRegistry;
+    /** The trigger manager for trigger-based interactions (@mentions, #hashtags, etc.). */
+    readonly triggers: import('./trigger-manager.js').TriggerManager;
+    /** The cursor rect API for positioning floating UI. */
+    readonly cursorRect: import('./cursor-rect.js').CursorRectAPI;
+    /**
+     * Focus the editor's contenteditable element.
+     * If the editor was destroyed, this is a no-op.
+     */
+    focus(): void;
+    /**
+     * Blur the editor's contenteditable element.
+     * If the editor was destroyed, this is a no-op.
+     */
+    blur(): void;
+    /**
+     * Returns true if the editor's contenteditable element currently has focus.
+     *
+     * @returns Whether the editor is focused
+     */
+    isFocused(): boolean;
+    /**
+     * Tear down the editor. Removes all event listeners and DOM modifications.
+     * After calling destroy(), the editor instance is inert.
+     */
+    destroy(): void;
+}
+/**
+ * Cached offset information for a single block in the document.
+ *
+ * Used by the selection synchronization layer to convert between
+ * absolute RTIF offsets and DOM positions without recalculating
+ * block offsets on every selection change.
+ *
+ * @example
+ * ```ts
+ * // For a doc with blocks ["hello", "world"]:
+ * // entries = [
+ * //   { blockId: 'b1', startOffset: 0, length: 5 },
+ * //   { blockId: 'b2', startOffset: 6, length: 5 },
+ * // ]
+ * ```
+ */
+export interface BlockOffsetEntry {
+    /** The block's unique ID. */
+    readonly blockId: string;
+    /** Absolute document offset where this block's text begins. */
+    readonly startOffset: number;
+    /** The text length of this block (sum of all span text lengths). */
+    readonly length: number;
+}
+/**
+ * A position within the DOM, represented as a node and character offset.
+ *
+ * This is the DOM-level equivalent of an RTIF `Position`. The selection
+ * synchronization layer converts between `DomPoint` and RTIF absolute offsets.
+ *
+ * @example
+ * ```ts
+ * // Cursor at character 3 inside a text node:
+ * const point: DomPoint = { node: textNode, offset: 3 };
+ * ```
+ */
+export interface DomPoint {
+    /** The DOM node containing the position. Typically a Text node. */
+    readonly node: Node;
+    /** The character offset within the node. */
+    readonly offset: number;
+}
+/**
+ * Tracks the state of an active IME composition session.
+ *
+ * During composition (e.g., CJK input, accent dead-keys), RTIF operations
+ * are deferred until the composition commits. This state tracks everything
+ * needed to emit the correct `insert_text` operation on `compositionend`.
+ *
+ * @example
+ * ```ts
+ * // Idle state (no composition active):
+ * const idle: CompositionState = {
+ *   composing: false,
+ *   composingBlockId: null,
+ *   startOffset: null,
+ *   selectionRange: null,
+ * };
+ *
+ * // Active composition with a prior selection:
+ * const active: CompositionState = {
+ *   composing: true,
+ *   composingBlockId: 'b1',
+ *   startOffset: 5,
+ *   selectionRange: { start: 5, end: 10 },
+ * };
+ * ```
+ */
+export interface CompositionState {
+    /** Whether a composition session is currently active. */
+    readonly composing: boolean;
+    /** The block ID where composition started, or null when idle. */
+    readonly composingBlockId: string | null;
+    /** The absolute document offset where composition started, or null when idle. */
+    readonly startOffset: number | null;
+    /**
+     * The selection range (as absolute offsets) that was active when composition
+     * started. If non-null, this range is deleted on composition commit, not
+     * on composition start, to avoid breaking IME behavior.
+     */
+    readonly selectionRange: {
+        readonly start: number;
+        readonly end: number;
+    } | null;
+}
+/**
+ * A disposable resource handle. Call `dispose()` to unregister.
+ *
+ * @example
+ * ```ts
+ * const registration = pipeline.register(myHandler);
+ * // later:
+ * registration.dispose();
+ * ```
+ */
+export interface Disposable {
+    /** Unregister the resource. */
+    dispose(): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAE3B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAE/B,6DAA6D;IAC7D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAE5B;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAEjC;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAE9B;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAE7B;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,aAAa,CAAC,OAAO,iBAAiB,EAAE,SAAS,CAAC,CAAC;CAC1E;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,SAAS;IACxB,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAE/B,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,EAAE,OAAO,kBAAkB,EAAE,UAAU,CAAC;IAE3D,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,OAAO,uBAAuB,EAAE,eAAe,CAAC;IAElE,wEAAwE;IACxE,QAAQ,CAAC,aAAa,EAAE,OAAO,oBAAoB,EAAE,oBAAoB,CAAC;IAE1E,+EAA+E;IAC/E,QAAQ,CAAC,cAAc,EAAE,OAAO,qBAAqB,EAAE,qBAAqB,CAAC;IAE7E,uFAAuF;IACvF,QAAQ,CAAC,QAAQ,EAAE,OAAO,sBAAsB,EAAE,cAAc,CAAC;IAEjE,uDAAuD;IACvD,QAAQ,CAAC,UAAU,EAAE,OAAO,kBAAkB,EAAE,aAAa,CAAC;IAE9D;;;OAGG;IACH,KAAK,IAAI,IAAI,CAAC;IAEd;;;OAGG;IACH,IAAI,IAAI,IAAI,CAAC;IAEb;;;;OAIG;IACH,SAAS,IAAI,OAAO,CAAC;IAErB;;;OAGG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6BAA6B;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,QAAQ;IACvB,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAEpB,4CAA4C;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,yDAAyD;IACzD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAE5B,iEAAiE;IACjE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzC,iFAAiF;IACjF,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAEpC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE;QACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;KACtB,GAAG,IAAI,CAAC;CACV;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACzB,+BAA+B;IAC/B,OAAO,IAAI,IAAI,CAAC;CACjB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@rtif-sdk/web",
+  "version": "1.0.0",
+  "description": "RTIF web platform implementation (contenteditable)",
+  "author": "coryrobinson42@gmail.com",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "sideEffects": false,
+  "engines": { "node": ">=20.0.0" },
+  "keywords": ["rich-text", "editor", "contenteditable", "web-editor", "rtif", "wysiwyg"],
+  "scripts": {
+    "build": "tsc --build tsconfig.build.json",
+    "test": "vitest run",
+    "test:browser": "vitest run --config vitest.browser.config.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@rtif-sdk/core": "^1.0.0",
+    "@rtif-sdk/engine": "^1.0.0"
+  },
+  "license": "MIT"
+}